gradatum-server

Stateless HTTP/MCP facade on port 19090. Auth Path 2 (/auth/exchange) added in alpha.5. Handles read/search and enqueues write operations.

Status : Alpha — placeholder v0.0.2. Phase 2.0c-bis Auth Path 2 LIVE 2026-05-07 (git tag v0.1.0-alpha.5). Source code private until v1.0 public release per D5 criterion. See gradatum.org.

Part of gradatum — Memory backbone for AI agents.

Usage

gradatum-server [--config <path>]

HTTP Endpoints (alpha.5)

Method	Path	Auth	Description
`GET`	`/health`	None	Health check — returns `{"status":"ok","version":"..."}`
`POST`	`/auth/exchange`	API key (`ak_xxx`)	Exchange API key → JWT (Auth Path 2 — alpha.5)
`GET`	`/metrics`	Loopback only	Prometheus metrics (port :19091)
`POST`	`/api/v1/vault_search`	JWT Bearer	Full-text + semantic search
`POST`	`/api/v1/vault_read`	JWT Bearer	Read note by path
`POST`	`/api/v1/vault_list`	JWT Bearer	List notes with pagination
`GET`	`/api/v1/vault_status`	JWT Bearer	Vault status and stats
`GET`	`/api/v1/vault_authors`	JWT Bearer	List note authors
`GET`	`/api/v1/vault_tags`	JWT Bearer	List tags with frequencies
`POST`	`/api/v1/vault_graph`	JWT Bearer	Wikilink graph from a root note
`POST`	`/api/v1/vault_links`	JWT Bearer	Wikilinks for a note
`POST`	`/api/v1/vault_trace`	JWT Bearer	Trace chain through a note
`POST`	`/api/v1/vault_context`	JWT Bearer	Context window for a note

/auth/exchange (Auth Path 2 — alpha.5)

Request : POST /auth/exchange

Authorization: Bearer ak_<prefix><secret>

Response (ExchangeResponse V2 — 5 fields):

{
  "token": "<JWT>",
  "ttl_secs": 86400,
  "scopes": ["read"],
  "tenant_id": "main",
  "kid": "<key-id>"
}

Errors :

401 Unauthorized — invalid or revoked key (uniform, no enumeration leak)
429 Too Many Requests — rate limiting (Phase 2.1, deferred)

Architecture : /auth/exchange is mounted BEFORE the JWT middleware — it cannot require its own JWT.

MCP Endpoint

Path	Description
`/mcp`	Streamable HTTP (MCP 2025-03-26)
`/sse`	SSE legacy transport

Configuration (TOML)

bind = "127.0.0.1:19090"     # C3: TLS required for non-loopback
data_root = "/var/lib/gradatum"
jwt_public_key_path = "/etc/gradatum/jwt_ed25519.pub"
jwt_private_key_path = "/etc/gradatum/jwt_ed25519.key"
[acl]
preset_path = "/etc/gradatum/acl/hierarchical.toml"
[auth]
api_keys_db_path = "/var/lib/gradatum/db/api_keys.db"
revocation_db_path = "/var/lib/gradatum/db/revocation.db"

Auth Path 2 bootstrap (alpha.5)

# 1. Create an API key (operator)
gradatum-admin api-key create --owner myagent --scopes read --tenant main

# 2. Exchange for JWT (consumer)
curl -X POST http://127.0.0.1:19090/auth/exchange \
     -H "Authorization: Bearer ak_<key>"

# 3. Use JWT on all /api/v1/* endpoints
curl http://127.0.0.1:19090/api/v1/vault_status \
     -H "Authorization: Bearer <jwt>"

Graceful shutdown

SIGTERM → 30-second drain.

Documentation

Project : https://gradatum.org
Source : private until v1.0
Roadmap : Phase 2.0c-bis (alpha.5 LIVE) → Phase 2.1 v0.1.0-rc.1 → v0.1.0 public
License : Apache-2.0

gradatum-server 0.0.2