gradatum-server 0.0.2

Stateless HTTP/MCP façade :19090 — Auth Path 2 (/auth/exchange) + read/search + enqueues writes (alpha.5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

# 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](https://gradatum.org).

**Part of [`gradatum`](https://crates.io/crates/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):
```json
{
  "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)

```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)

```bash
# 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