pqc-memory-mcp 1.0.0

package/docs/crypticpqc-cross-domain-auth.md

@@ -0,0 +1,194 @@
+# Cryptic PQC — shared auth across domains
+
+This document maps how **one identity story** should span the four public surfaces. It is the coordination layer between teams/repos; **pqc-api** (`crypticpqc.com`) remains the **authoritative** place for org/bucket/API-key resolution unless explicitly delegated.
+
+| Origin | Role | Typical credentials |
+|--------|------|---------------------|
+| **`https://crypticpqc.com`** | pqc-db / pqc-api — data, memory API, `GET /api/v1/mcp/tenant-context`, portal JSON if served here | **`JWTService.ValidateAccessToken`** — **HS256 pqc-db access JWT** on protected routes; optional **`X-API-Key`** / **`MCP_TENANT_SERVICE_API_KEY`** on tenant-context |
+| **`https://app.crypticpqc.com`** | Vael-client — React SPA (Auth0 + Google connection) | Auth0 only at **login**; after callback, pqc-db **mints HS256 access JWTs** (`portal_token` cookie, etc.). **API calls must use that pqc-db JWT**, not a raw Auth0 API access token (see below). |
+| **`https://mcp.crypticpqc.com`** | pqc-memory-mcp — Streamable HTTP MCP for Claude / tools | No end-user login UI; **`Authorization: Bearer`** from client; **`PQC_TENANT_RESOLUTION_URL`** → crypticpqc.com; optional RFC 9728 metadata |
+| **`https://crypto.crypticpqc.com`** | Key manager — keys, policies, crypto operations | **Only pqc-db calls this service** (browser/MCP do not). User identity stops at pqc-db; pqc-db uses **service-to-service** credentials to crypto. |
+
+**Naming note:** Production API hostname may be `crypticpqc.com` or `api.crypticpqc.com`; pick **one canonical public API origin** and use it everywhere env vars say “pqc-api origin.”
+
+---
+
+## Ground truth: pqc-db (CrypticPQDB) today
+
+This matches the current **portal + JWT** implementation:
+
+1. **Auth0 is used only on the login / OAuth callback path**  
+   pqc-db verifies the **Auth0 ID token** (`VerifyIDToken`), then **mints pqc-db tokens** (`GenerateTokenPair`) and sets e.g. **`portal_token`** (access JWT in an HTTP-only cookie).
+
+2. **Every normal protected route (including portal middleware) expects a pqc-db access JWT**  
+   `JWTService.ValidateAccessToken` parses **HMAC-SHA256** tokens signed with the app secret and checks custom claims (`uid`, `oid`, `type: access`, etc.). Anything that is not that format (including a raw **Auth0-issued API access token** in `Authorization: Bearer`) **will not validate**.
+
+3. **Implication**  
+   “Shared auth” across SPA and API means: **same login story (Auth0 once)**, **same ongoing credential (pqc-db JWT)**. It does **not** mean “send Auth0’s access token to pqc-db on every request” in the current code.
+
+---
+
+## Why Auth0 for login, pqc-db JWT after
+
+Auth0 is an **identity provider** (OIDC): it proves a human completed login and gives a stable **`sub`** (and profile). It is not your **application session layer**. pqc-db was built around the latter first.
+
+- **One credential shape on the hot path** — Portal, REST, `tenant-context`, and shared middleware expect the same **claims** (`uid`, `oid`, role, `type: access`). Treating Auth0 access tokens as `Bearer` on every route would add a **parallel** stack (JWKS, issuer/audience rules, claim mapping, opaque-token edge cases) across handlers.
+- **Tenancy lives in the database** — Resolve “this IdP user → this `users` / org row” **once** at callback, then mint a JWT that already carries **org and role** the API trusts, instead of re-deriving IdP claims on every request.
+- **Operations** — **HS256** with a local secret is cheap, deterministic, and does not tie routine API traffic to Auth0 availability or JWKS cache behavior.
+- **Evolution** — Add or change IdPs (Auth0, another OIDC, password) at login without rewriting downstream auth: services still only accept **pqc-db JWT** (and API keys).
+- **Claude MCP** — The connector sends **Auth0’s** access token into paths that expect **pqc-db** JWT; the A/B/C-style fixes close that **boundary** without a wholesale “Auth0 for all APIs” rewrite.
+
+---
+
+## Design principles (updated)
+
+1. **One Auth0 tenant for human login; multiple Auth0 applications if needed**  
+   SPA: PKCE. Claude MCP connector (if used): separate app + secret, callback `https://claude.ai/api/mcp/auth_callback`. **`PQC_MCP_AUTHORIZATION_SERVERS`** = Auth0 issuer URL so Claude can complete OAuth — **but** see the MCP gap below.
+
+2. **One token family pqc-db validates on API routes today: HS256 pqc-db access JWT**  
+   To support Claude without changing validation, you need **either** a **new code path** on `tenant-context` (or a small **exchange** endpoint) that turns an Auth0 access token into trust **or** mints a pqc-db JWT for MCP. **Do not** assume Claude’s Auth0 access token works against `ValidateAccessToken` as deployed.
+
+3. **MCP never stores long-lived user secrets**  
+   MCP resolves **Bearer →** `tenant-context` **→** memory **`api_key`** + `bucket_id` (see [pqc-api-tenant-context-go.md](./pqc-api-tenant-context-go.md)). That Bearer must be something **tenant-context** accepts.
+
+4. **Key manager: backend-only from pqc-db**  
+   End users authenticate to **pqc-db** (via Auth0 bootstrap + pqc-db JWT). **Only pqc-db** calls **`crypto.crypticpqc.com`**; lock that edge with mTLS, private network, or a service API key.
+
+---
+
+## High-level flows
+
+### A. Human in the portal (SPA)
+
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant App as app.crypticpqc.com
+  participant A0 as Auth0
+  participant API as crypticpqc.com
+
+  U->>App: Open app
+  App->>A0: OIDC authorize (PKCE)
+  A0->>U: Google / login
+  A0->>App: Auth0 tokens (callback to pqc-db)
+  App->>API: Login callback / session establishment
+  API->>A0: Verify ID token mint pqc-db JWT
+  API-->>App: Set-Cookie portal_token (pqc-db access JWT)
+  App->>API: API calls Cookie and/or Authorization Bearer pqc-db JWT
+  API->>API: JWTService.ValidateAccessToken (HS256 only)
+```
+
+### B. Claude remote MCP (**gap vs current pqc-db**)
+
+```mermaid
+sequenceDiagram
+  participant C as Claude.ai
+  participant A0 as Auth0
+  participant MCP as mcp.crypticpqc.com
+  participant API as crypticpqc.com
+
+  C->>MCP: GET /.well-known/oauth-protected-resource/mcp
+  MCP-->>C: authorization_servers, resource
+  C->>A0: OAuth (connector client + secret)
+  A0-->>C: Auth0 API access_token
+  C->>MCP: POST /mcp Authorization Bearer (Auth0 token)
+  MCP->>API: GET /api/v1/mcp/tenant-context Bearer (same)
+  Note over API: Today: ValidateAccessToken expects pqc-db HS256 JWT — Auth0 token fails
+```
+
+**Ways to close the gap (pick one):**
+
+| Approach | Idea |
+|----------|------|
+| **A. Dual validation on `tenant-context` only** | If Bearer looks like Auth0 (e.g. `iss` + RS256), validate via JWKS and map `sub` → user/org; else existing `ValidateAccessToken`. |
+| **B. Token exchange endpoint** | e.g. `POST /api/v1/auth/mcp-exchange`: body or `Authorization: Bearer <auth0>`, response = pqc-db access JWT; MCP calls exchange first (requires product decision). |
+| **C. Claude-only mint** | Highly constrained endpoint that issues short-lived pqc-db JWT after Auth0 proof (similar to B). |
+
+Until one of these exists, **OAuth metadata + Auth0 on Claude** alone is not enough for a working tenant-context.
+
+### C. Key manager (only pqc-db calls crypto)
+
+```mermaid
+flowchart LR
+  subgraph users [Users]
+    U[Browser / Claude]
+  end
+  subgraph api [pqc-db]
+    PQC[crypticpqc.com]
+  end
+  subgraph km [Key manager]
+    CRY[crypto.crypticpqc.com]
+  end
+
+  U -->|Auth0 then pqc-db JWT| PQC
+  PQC -->|service auth only| CRY
+```
+
+**Implementation checklist for crypto:**
+
+- [ ] No public “log in to crypto” required if UI never talks to crypto directly.
+- [ ] **mTLS**, private network, or **service API key** on pqc-db → crypto.
+- [ ] Authorize key operations inside **pqc-db** (org, role, policy) before calling crypto.
+
+---
+
+## Planned implementation: pqc-db (CrypticPQDB)
+
+The **Claude Auth0 application** (client ID + secret) lives in **Auth0** and **Claude’s connector Advanced settings** only. For a standard **JWT + JWKS** verify path, **pqc-db does not need the Claude client secret**; it verifies **user access tokens** with **JWKS**, using **`iss`** (Auth0 domain / issuer URL) and **`aud`** (the **Auth0 API identifier** those tokens are minted for—not the OAuth client ID).
+
+**Core change (choose one):**
+
+1. **`POST /api/v1/auth/mcp-exchange` (recommended)** — Verify Auth0 access JWT (JWKS + `iss` / `aud`), resolve user, **`GenerateTokenPair`**, return pqc-db **`access_token`** (and optional refresh) like portal login. **pqc-mcp-server** can then call exchange once, then **`GET /api/v1/mcp/tenant-context`** with the **pqc-db** Bearer.
+
+2. **JWKS branch on `GET /api/v1/mcp/tenant-context` only** — Same verify + user resolve, then existing tenant resolver; MCP keeps a single hop to `tenant-context` with Auth0 Bearer.
+
+**Supporting work in pqc-db:**
+
+- **Config / env:** e.g. `AUTH0_DOMAIN` (or issuer URL), **`AUTH0_AUDIENCE`** (or `AUTH0_MCP_AUDIENCE` if MCP uses a different Auth0 API than the portal). Document in `env.example`.
+- **User mapping:** Prefer **`auth0_sub`** (or equivalent) on **`users`**, set from the **portal** Auth0 callback on login; exchange / tenant-context resolves by **`sub`**. Avoid email-only mapping.
+- **Hardening:** Optional **`MCP_TENANT_SERVICE_API_KEY`** on **`mcp-exchange`** (mirror `tenant-context`) so the mint endpoint is not a public oracle.
+- **Auth0 API / audience:** Claude’s app must receive tokens whose **`aud`** matches what pqc-db validates (same or dedicated Auth0 API—env must match).
+- **Tests and docs** for the new path.
+
+**Follow-up in pqc-mcp-server (if exchange):** teach HTTP MCP to detect Auth0 Bearer vs pqc-db JWT, call **`mcp-exchange`**, cache **pqc-db** JWT for TTL, then call **`tenant-context`** (or call **`tenant-context`** only with the minted token).
+
+**Implementation plan (working copy):** `local/mcp_auth0_exchange_8d491625.plan.md` (under `local/`, gitignored — copy or sync important deltas into committed docs). **Committed API contract** for MCP consumers: [mcp-auth0-exchange-contract.md](./mcp-auth0-exchange-contract.md).
+
+---
+
+## Environment alignment (MCP server)
+
+| Variable | Points to |
+|----------|-----------|
+| `PQC_TENANT_RESOLUTION_URL` | **crypticpqc.com** (pqc-api **origin** only) |
+| `PQC_MCP_PUBLIC_URL` | **https://mcp.crypticpqc.com** |
+| `PQC_MCP_AUTHORIZATION_SERVERS` | **Auth0 issuer** URL(s), comma-separated if ever multiple |
+| `PQC_MCP_ALLOWED_HOSTS` | `mcp.crypticpqc.com` (if you enable host allowlisting) |
+
+See also: [claude-remote-oauth.md](./claude-remote-oauth.md), [pqc-db-mcp-tenant-context.md](./pqc-db-mcp-tenant-context.md).
+
+---
+
+## CORS and cookies
+
+- **SPA** on `app.crypticpqc.com` calling **API** on `crypticpqc.com`: allow origin in API CORS; prefer **Authorization header** over cross-site cookies for API calls unless you intentionally use **SameSite=None; Secure** first-party cookie patterns.
+- **MCP** is server-to-server from Claude’s infrastructure: CORS is irrelevant for `POST /mcp`; focus on **TLS**, **Host** allowlist, and **token validation**.
+
+---
+
+## Checklist — “shared auth layer done”
+
+1. [ ] **Canonical API base URL** documented and used in SPA, MCP (`PQC_TENANT_RESOLUTION_URL`), and runbooks.  
+2. [ ] **SPA:** After Auth0 login, all `/api/v1/...` calls use **pqc-db access JWT** (cookie and/or `Authorization`), not raw Auth0 access tokens.  
+3. [ ] **Claude MCP:** Chosen strategy **A / B / C** implemented on pqc-db so `tenant-context` succeeds with the Bearer Claude sends.  
+4. [ ] **MCP:** `/.well-known/oauth-protected-resource/mcp` returns **200 JSON** in production (still needed for Claude OAuth discovery).  
+5. [ ] **crypto.crypticpqc.com:** reachable only from pqc-db with service auth; policies enforced in pqc-db before calling crypto.
+
+---
+
+## Related repos
+
+- **pqc-mcp-server** (this repo) — HTTP MCP + tenant fetch.  
+- **pqc-db / CrypticPQDB** — `tenant-context`, JWT validation, buckets.  
+- **vael-client** — SPA on `app.crypticpqc.com`.  
+- **Key manager** — implement and link OpenAPI / auth doc here when available.

package/docs/mcp-auth0-exchange-contract.md

@@ -0,0 +1,75 @@
+# pqc-db: `POST /api/v1/auth/mcp-exchange` (contract)
+
+This describes the **pqc-db** endpoint planned for Claude remote MCP. Source plan (local, may be gitignored): `local/mcp_auth0_exchange_8d491625.plan.md`. **pqc-mcp-server** should call this, then `GET /api/v1/mcp/tenant-context` with the minted **pqc-db access JWT**.
+
+## Request
+
+- **Method / path:** `POST /api/v1/auth/mcp-exchange`
+- **Headers:**
+  - `Authorization: Bearer <Auth0 access JWT>` (required)
+  - `X-API-Key: <shared secret>` — when pqc-db **`MCP_TENANT_SERVICE_API_KEY`** (or equivalent) is set; same semantics as `GET /api/v1/mcp/tenant-context` and MCP **`PQC_MCP_SERVICE_API_KEY`**.
+
+## Response (success)
+
+- **200** `Content-Type: application/json`
+- Body shape (aligned with login / `TokenPair`): recommended
+
+```json
+{
+  "tokens": {
+    "access_token": "<pqc-db HS256 JWT>",
+    "refresh_token": "<optional>",
+    "expires_at": "2026-03-21T12:00:00Z",
+    "token_type": "Bearer"
+  }
+}
+```
+
+`expires_at` may be an **RFC3339 string** or a numeric epoch (seconds or ms); **pqc-mcp-server** accepts both. Exact field names should match pqc-db **`AuthResponse`** / OpenAPI.
+
+## Errors (intended mapping)
+
+| HTTP | When |
+|------|------|
+| **400** | Token malformed / not a JWT (e.g. opaque token) |
+| **401** | Invalid or expired Auth0 JWT after JWKS verify |
+| **403** | User inactive |
+| **404** | No `users` row for `auth0_sub` (`not_linked` style — user must complete portal Auth0 login once) |
+| **503** / **501** | Exchange not configured (`AUTH0_DOMAIN` / `AUTH0_MCP_AUDIENCE` unset) — if implemented |
+
+## pqc-db prerequisites
+
+- **`users.auth0_sub`** populated from portal Auth0 callback (`userInfo.Sub`) on login / invitation complete.
+- **JWKS verify** with **`iss`** (Auth0 issuer) and **`aud`** = Auth0 **API identifier** (not OAuth client id). Env e.g. `AUTH0_DOMAIN`, `AUTH0_MCP_AUDIENCE`.
+- Access token must be a **JWT** (three dot-separated segments); opaque tokens need a different design.
+
+### Opaque token from Claude (`not_jwt_opaque_unsupported`)
+
+**pqc-db `AUTH0_MCP_AUDIENCE` only affects validation after you already have a JWT.** Opaque access tokens usually mean Auth0 did **not** mint an API JWT—often because the **authorize/token request never targeted your API**.
+
+Common fix: **align PRM `resource` with Auth0’s API Identifier** (the `audience` value). This server defaults PRM `resource` to `{PQC_MCP_PUBLIC_URL}/mcp`. If your Auth0 API Identifier is **`https://mcp.example.com`** (no `/mcp`) and the MCP client passes that string as `audience`, Auth0 won’t match an API registered as **`https://mcp.example.com/mcp`**, and you can get an opaque token.
+
+**Options:** (1) Set **`PQC_MCP_PRM_RESOURCE`** on MCP to exactly match **`AUTH0_MCP_AUDIENCE`** / Auth0 API Identifier, **or** (2) Change the Auth0 API Identifier to match PRM’s `resource`, **or** (3) Confirm in **Auth0 → Monitoring → Logs** that successful token exchanges include `audience=` for your API.
+
+## pqc-mcp-server behavior (implemented)
+
+Set **`PQC_MCP_AUTH0_EXCHANGE`**:
+
+| Value | Behavior |
+|-------|----------|
+| *(unset)* / `0` / `false` / `off` | Bearer sent only to **`tenant-context`** (pqc-db access JWT only). |
+| **`1`**, **`retry`**, **`true`** | Try **`tenant-context`** first; on **401**, if Bearer looks like a JWT, **POST mcp-exchange**, cache minted JWT until **`expires_at`**, retry **`tenant-context`**. |
+| **`always`** | Always **POST mcp-exchange** first (JWT-shaped Bearer only), then **`tenant-context`** with minted JWT. |
+
+**Claude + Auth0:** use **`always`** or **`retry`** in production. **`PQC_MCP_SERVICE_API_KEY`** is sent on both **mcp-exchange** and **tenant-context** when set.
+
+Cached **`access_token`** is keyed by the **inbound** Auth0 token hash; **`TenantRuntimeCache`** still keys runtimes by the same inbound Bearer so sessions stay stable.
+
+## Security notes
+
+- Token-minting endpoint: protect with **service key**, HTTPS, and document rate-limit intent for ops (see plan §7).
+
+## See also
+
+- [crypticpqc-cross-domain-auth.md](./crypticpqc-cross-domain-auth.md) — full cross-domain narrative and planned implementation.
+- [pqc-api-tenant-context-go.md](./pqc-api-tenant-context-go.md) — `tenant-context` wire format.

package/docs/mcp-authorization-spec-alignment.md

@@ -0,0 +1,29 @@
+# MCP authorization spec vs pqc-memory-mcp (alignment notes)
+
+References: [Claude — Building custom connectors via remote MCP servers](https://support.claude.com/en/articles/11503834-building-custom-connectors-via-remote-mcp-servers), [MCP authorization (2025-11-25)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization), [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).
+
+## On track
+
+| Area | Spec / product | This stack |
+|------|----------------|------------|
+| Transport | Streamable HTTP (SSE still mentioned but may deprecate) | `StreamableHTTPServerTransport` + `POST /mcp` |
+| OAuth | Supported; DCR or static client id/secret | Auth0 + Claude Advanced client; external IdP |
+| Callback | `https://claude.ai/api/mcp/auth_callback` (allowlist `https://claude.com/...` too if hardening) | Documented in connector setup |
+| Token to MCP | `Authorization: Bearer` on MCP requests | `requireBearerAuth` + tenant verifier |
+| No token passthrough to pqc-db memory API | Resource server must not forward client tokens to upstream as-if native | **Planned:** Auth0 token → **`mcp-exchange`** → pqc-db JWT → `tenant-context` / memory API (separate credential) |
+| Resource metadata | RFC 9728; `authorization_servers` | `/.well-known/oauth-protected-resource/mcp` when env set |
+| `resource` in OAuth (RFC 8707) | Clients MUST send `resource` for token binding | **Auth0** maps **`audience`** to the API Identifier string, not always the PRM `resource` path. If PRM says `https://host/mcp` but Auth0 API Identifier is `https://host`, some clients may request the wrong audience → **opaque** access tokens. Align via **`PQC_MCP_PRM_RESOURCE`** or change Auth0 API Identifier (see [mcp-auth0-exchange-contract.md](mcp-auth0-exchange-contract.md) opaque-token note). |
+
+## Gaps / follow-ups
+
+1. **PRM always on in prod** — Spec treats protected-resource metadata as part of the OAuth story. Missing `PQC_MCP_PUBLIC_URL` / `PQC_MCP_AUTHORIZATION_SERVERS` yields **404** on well-known; fix with env on Zeabur.
+
+2. **`401` + `WWW-Authenticate`** — Spec expects clients to handle `resource_metadata` (and optional `scope`) on unauthorized responses. Behavior depends on **`@modelcontextprotocol/sdk`** middleware; verify on upgrade that Claude’s discovery path still works.
+
+3. **Refresh tokens** — Claude docs say servers should support expiry/refresh. After **mcp-exchange**, align token TTL/refresh with portal `TokenPair` behavior so long sessions do not silently die.
+
+4. **SDK versioning** — Upstream [typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk): **v1.x** is current production line; **v2** is pre-alpha on `main`. This repo pins a **v1.x** `@modelcontextprotocol/sdk`; track release notes for auth/transport changes.
+
+## TypeScript SDK
+
+Official implementation and examples: [github.com/modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk). Runnable Streamable HTTP examples live under `examples/`; auth-heavy flows are documented in SDK `docs/` and MCP spec.

package/docs/mcp-org-object-storage.md

@@ -0,0 +1,55 @@
+# Org object storage — MCP ↔ pqc-db API
+
+The MCP server talks to **pqc-db tenant API** only (`{apiUrl}/api/v1/...`). There is **no** direct MinIO/SDK path in this repo.
+
+## Authentication
+
+Same as other non-session routes (e.g. code graph): **`X-API-Key`** from tenant context.
+
+**Streamable HTTP:** the JWT that successfully resolved **`GET /api/v1/mcp/tenant-context`** is also sent as **`Authorization: Bearer`** on tenant API calls (`TenantContext.apiBearerToken` → `PqcClient`).
+
+Memory **`X-Memory-Session`** is **not** used for these routes.
+
+## Endpoints
+
+| Action | Method | Path |
+|--------|--------|------|
+| Upload (encrypted) | `POST` | `/api/v1/keys/managed/{key_id}/objects` |
+| Download (decrypted) | `GET` | `/api/v1/keys/managed/{key_id}/objects/{object_id}` |
+| List | `GET` | `/api/v1/objects` |
+| Metadata | `GET` | `/api/v1/objects/{id}` |
+
+### Upload (`multipart/form-data`)
+
+- **`file`** (required) — binary body
+- **`bucket_id`** (required) — org **data** bucket UUID
+- **`filename`** (optional) — display name override
+
+Success is typically **201** with JSON including **`object_id`**.
+
+### Download
+
+Response body: decrypted bytes (e.g. `application/octet-stream`). Use the **`key_id`** from upload or from list/metadata.
+
+### List
+
+Optional query: **`bucket=<uuid>`**. Rows for encrypted objects may include **`key_id`**.
+
+### Metadata
+
+May include **`download_hint`** for encrypted objects.
+
+## Not supported here
+
+Legacy or portal-only paths such as **`/api/v1/objects/upload`**, **`/api/v1/objects/{id}/download`**, or dashboard upload URLs — MCP implements **only** the managed-key pair above.
+
+## MCP tools
+
+| Tool | Maps to |
+|------|---------|
+| `object_upload` | multipart POST |
+| `object_download` | GET bytes → base64 in tool result |
+| `object_list` | GET `/objects` |
+| `object_get` | GET `/objects/{id}` |
+
+`object_upload` accepts **`file_base64`** (MCP-friendly); `object_download` returns **`file_base64`** plus size and content type. Large downloads are capped by **`max_bytes`** (default 10 MiB, max 50 MiB) to avoid accidental huge tool payloads.

package/docs/pqc-api-tenant-context-go.md

@@ -0,0 +1,238 @@
+# pqc-api: `GET /api/v1/mcp/tenant-context` (Go)
+
+This is what **pqc-mcp-server** calls when `PQC_TENANT_RESOLUTION_URL` is set (HTTP MCP mode). Implement this on **pqc-api** so each user’s **Bearer** token resolves to memory credentials.
+
+## Aligned with pqc-api (deployed behavior)
+
+| Topic | Detail |
+|--------|--------|
+| **MCP env** | `PQC_TENANT_RESOLUTION_URL` = **public API origin only** (no path), e.g. `https://crypticpqc.com` or `http://localhost:8081`. MCP appends `/api/v1/mcp/tenant-context`. |
+| **Bearer** | **pqc-api access JWT** (e.g. from `POST /api/v1/auth/login` or portal), **HS256**, must match **`JWT_SECRET`** / **`JWT_ISSUER`** on pqc-api. |
+| **After 200** | MCP uses **`api_url`**, **`api_key`**, **`bucket_id`** from JSON for all memory calls — not separate hard-coded `PQC_API_URL` in HTTP mode. |
+| **Service key** | Optional pair: MCP **`PQC_MCP_SERVICE_API_KEY`** ↔ pqc-api **`MCP_TENANT_SERVICE_API_KEY`** (same value). Sent as **`X-API-Key`** on tenant-context **only**. If pqc-api enforces it, both must be set; otherwise leave both unset. |
+| **TTL** | **`session_ttl_minutes`** in JSON (pqc-api often uses **1440**); MCP falls back to **`PQC_SESSION_TTL`** if omitted. |
+| **Provisioning** | Org needs a **`data_buckets`** row with **`bucket_mode = memory`**, or tenant-context returns **404** with `not_provisioned` (or similar). |
+| **pqc-api config** | **`PUBLIC_API_URL`** / **`BASE_URL`** (or equivalent) so returned **`api_url`** is correct for clients. |
+
+**Auth0 vs this Bearer:** In the current CrypticPQDB stack, **Auth0 participates only in the OAuth callback** (ID token verification); ongoing API auth is **pqc-db HS256 access JWTs** via `JWTService.ValidateAccessToken`. If the MCP client sends an **Auth0-issued access token**, it will **not** pass that validator unless you add a **separate** code path on this handler (JWKS) or an **exchange** step. See [crypticpqc-cross-domain-auth.md](./crypticpqc-cross-domain-auth.md).
+
+## Wire contract (must match MCP client)
+
+**Method / path:** `GET /api/v1/mcp/tenant-context`  
+**Base URL:** MCP sets `PQC_TENANT_RESOLUTION_URL` to the **origin** of pqc-api (scheme + host + port).
+
+### Request headers
+
+| Header | Required | Notes |
+|--------|----------|--------|
+| `Authorization` | Yes | `Bearer <access_token>` — **pqc-api JWT** (HS256), same as other `/api/v1/...` authenticated calls |
+| `X-API-Key` | No | Sent only if MCP has `PQC_MCP_SERVICE_API_KEY`; must match pqc-api **`MCP_TENANT_SERVICE_API_KEY`** when that env is set |
+
+### Success: `200 OK`
+
+`Content-Type: application/json`
+
+```json
+{
+  "api_url": "https://api.yourcompany.com",
+  "api_key": "pqc_xxxxxxxx",
+  "bucket_id": "550e8400-e29b-41d4-a716-446655440000",
+  "session_ttl_minutes": 1440
+}
+```
+
+| Field | Type | Required | Meaning |
+|-------|------|----------|---------|
+| `api_url` | string | Yes | Base URL the MCP will use for **all** memory calls (typically your public API root; **no** trailing slash) |
+| `api_key` | string | Yes | Value MCP sends as `X-API-Key` on subsequent `POST /api/v1/memory/session/start`, etc. |
+| `bucket_id` | string | Yes | UUID passed to `startSession` as `bucket_id` |
+| `session_ttl_minutes` | number | No | Memory session TTL; MCP falls back to `PQC_SESSION_TTL` or 1440 |
+
+### Errors
+
+Return JSON when possible so operators see a message in logs (`error` string is what the Node client prefers on non-2xx):
+
+```json
+{ "error": "invalid_token" }
+```
+
+| HTTP | When |
+|------|------|
+| `401` | Missing `Authorization`, not `Bearer`, invalid/expired JWT, wrong **`MCP_TENANT_SERVICE_API_KEY`** (if enforced) |
+| `403` | Token valid but user/org not allowed to use MCP / no bucket |
+| `404` | Not provisioned — e.g. no **`data_buckets`** with **`bucket_mode = memory`**; body may include `"error":"not_provisioned"` |
+| `500` | Database or internal failure (avoid leaking internals in `error` string to untrusted clients if this URL is internet-facing) |
+
+## Example: `curl` (local testing)
+
+```bash
+# After you mint a real access token from your IdP:
+curl -sS -D - \
+  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
+  -H "X-API-Key: pqc_service_optional" \
+  "https://localhost:8081/api/v1/mcp/tenant-context"
+```
+
+**Example success body:**
+
+```json
+{
+  "api_url": "http://localhost:8081",
+  "api_key": "pqc_user_or_connector_key_abc",
+  "bucket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "session_ttl_minutes": 1440
+}
+```
+
+**Example error:**
+
+```http
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+
+{"error":"invalid or expired token"}
+```
+
+## Go types
+
+```go
+// internal/mcp/types.go (or your layout)
+
+type TenantContextResponse struct {
+	APIURL             string `json:"api_url"`
+	APIKey             string `json:"api_key"`
+	BucketID           string `json:"bucket_id"`
+	SessionTTLMinutes  *int   `json:"session_ttl_minutes,omitempty"`
+}
+
+type ErrorResponse struct {
+	Error string `json:"error"`
+}
+```
+
+## Go handler sketch (Gin)
+
+```go
+package mcp
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Dependencies you inject: JWT validator, DB, config (public API base, optional service key).
+func RegisterTenantContextRoute(r *gin.Engine, h *TenantContextHandler) {
+	// Adjust group prefix to match your existing /api/v1 router.
+	v1 := r.Group("/api/v1")
+	v1.GET("/mcp/tenant-context", h.Handle)
+}
+
+type TenantContextHandler struct {
+	// ExpectedBaseURL is what you return as api_url (e.g. cfg.PublicAPIURL).
+	ExpectedBaseURL string
+	// Optional: if non-empty, require X-API-Key to match (shared secret with MCP).
+	ServiceAPIKey string
+	// Resolver loads api_key + bucket_id for the authenticated subject.
+	Resolver TenantResolver
+	// ValidateAndParseBearer validates JWT (JWKS/introspection) and returns claims (sub, org, email).
+	Auth BearerAuth
+}
+
+type TenantResolver interface {
+	Resolve(ctx interface{}, subject string, orgID *string) (apiKey, bucketID string, ttl *int, err error)
+}
+
+type BearerAuth interface {
+	ValidateBearer(c *gin.Context, rawToken string) (subject string, orgID *string, err error)
+}
+
+func (h *TenantContextHandler) Handle(c *gin.Context) {
+	if h.ServiceAPIKey != "" && c.GetHeader("X-API-Key") != h.ServiceAPIKey {
+		c.JSON(http.StatusUnauthorized, ErrorResponse{Error: "unauthorized"})
+		return
+	}
+
+	authz := c.GetHeader("Authorization")
+	if !strings.HasPrefix(strings.ToLower(authz), "bearer ") {
+		c.JSON(http.StatusUnauthorized, ErrorResponse{Error: "missing bearer token"})
+		return
+	}
+	raw := strings.TrimSpace(authz[7:])
+
+	subject, orgID, err := h.Auth.ValidateBearer(c, raw)
+	if err != nil {
+		c.JSON(http.StatusUnauthorized, ErrorResponse{Error: "invalid or expired token"})
+		return
+	}
+
+	apiKey, bucketID, ttl, err := h.Resolver.Resolve(c, subject, orgID)
+	if err != nil {
+		// map ErrNotProvisioned -> 404, ErrForbidden -> 403, etc.
+		c.JSON(http.StatusInternalServerError, ErrorResponse{Error: "tenant lookup failed"})
+		return
+	}
+
+	resp := TenantContextResponse{
+		APIURL:    strings.TrimRight(h.ExpectedBaseURL, "/"),
+		APIKey:    apiKey,
+		BucketID:  bucketID,
+	}
+	if ttl != nil {
+		resp.SessionTTLMinutes = ttl
+	}
+	c.JSON(http.StatusOK, resp)
+}
+```
+
+You would replace the generic `Resolve` / `ValidateBearer` with your real packages (existing user table, org RLS, API key issuance).
+
+## JWT validation (what to implement inside `ValidateBearer`)
+
+Typical steps:
+
+1. Parse `Authorization` bearer string.
+2. Verify signature using your IdP’s **JWKS** (issuer from token `iss`, audience `aud` must match what your OAuth client uses).
+3. Reject if `exp` in the past.
+4. Return stable **`sub`** (and optional `org_id` from a custom claim you control).
+
+Libraries commonly used:
+
+- `github.com/golang-jwt/jwt/v5` + fetch JWKS from `https://<issuer>/.well-known/jwks.json`, or  
+- `github.com/lestrrat-go/jwx/v2/jwk` + `jwt.Parse`
+
+**Do not** log the raw bearer or the full JWT in production.
+
+## Resolver (what to implement inside `Resolve`)
+
+1. Look up user by `sub` (or email claim) in your DB.
+2. Ensure they belong to an **org** with a **memory bucket** (your existing `bucket` model).
+3. Return an **API key** that:
+   - is allowed to call `POST /api/v1/memory/session/start` with that `bucket_id`, and  
+   - is scoped so it cannot access other orgs’ buckets (your existing RLS / middleware).
+
+If the user exists but has no bucket yet, return **404** and a JSON `error` like `"not_provisioned"` so you can distinguish from bad tokens.
+
+## Alignment with MCP env
+
+| MCP env | Role |
+|---------|------|
+| `PQC_TENANT_RESOLUTION_URL` | Must be the base URL where this handler lives (`GET .../api/v1/mcp/tenant-context`) |
+| `PQC_MCP_SERVICE_API_KEY` | Optional; if set, MCP sends it as `X-API-Key` on every tenant-context request |
+
+Returned `api_url` should match what memory routes already use (same host as `PQC_API_URL` in stdio mode), so the MCP’s `PqcClient` hits the correct deployment.
+
+## Testing checklist
+
+1. **401:** no header, malformed bearer, expired JWT, wrong `aud`.
+2. **403:** valid JWT but user not entitled for MCP.
+3. **404:** valid JWT, user exists, no bucket / mapping.
+4. **200:** returns all three required fields; MCP can call `session/start` with returned `api_key` + `bucket_id`.
+5. **Service key:** with `PQC_MCP_SERVICE_API_KEY` set on MCP, handler rejects missing/wrong `X-API-Key`.
+
+## Security reminders
+
+- Use **HTTPS** in production for this endpoint (bearer + optional service key).
+- Rate-limit by IP and/or by `sub` after JWT parse to reduce brute force.
+- Return **generic** `error` strings to anonymous clients; log detailed reasons server-side only.

package/docs/pqc-db-mcp-tenant-context.md

@@ -0,0 +1,15 @@
+# pqc-db / pqc-api: MCP tenant context API
+
+The **HTTP** entrypoint in **pqc-mcp-server** resolves tenants by calling pqc-api:
+
+`GET {PQC_TENANT_RESOLUTION_URL}/api/v1/mcp/tenant-context`
+
+Use **public API origin only** for `PQC_TENANT_RESOLUTION_URL` (e.g. `https://crypticpqc.com`), no path.
+
+## Request / response
+
+See **[pqc-api-tenant-context-go.md](pqc-api-tenant-context-go.md)** for headers, JSON body, errors, Go examples, and alignment with **JWT_SECRET** / **JWT_ISSUER**, **`MCP_TENANT_SERVICE_API_KEY`**, **`not_provisioned`**, and **`data_buckets` (`bucket_mode = memory`)**.
+
+## Legacy note
+
+Older text referred generically to “OAuth / JWKS / IdP”. **As pqc-api is today**, the Bearer is typically the **pqc-api access JWT** (HS256). External IdPs must either issue compatible tokens or you add an exchange step on pqc-api before this handler runs.

package/docs/pqc-db-tenant-context-implementation.md

@@ -0,0 +1,32 @@
+# pqc-db: implementing `GET /api/v1/mcp/tenant-context`
+
+This endpoint is **not** implemented in the `pqc-mcp-server` repo; it belongs in **pqc-db** (Go). The MCP HTTP server calls it on every Bearer-authenticated session to map the OAuth access token to memory tenant credentials.
+
+## Behavior
+
+1. Read `Authorization: Bearer <access_token>`.
+2. Validate the token (JWKS for your IdP, introspection, or shared secret per your security model).
+3. Resolve `sub` / org / email to an internal user and **bucket_id**.
+4. Load or mint an **API key** constrained to that bucket (or return an existing org-scoped key policy your team accepts).
+5. Return JSON:
+
+```json
+{
+  "api_url": "https://api.yourdomain.com",
+  "api_key": "pqc_…",
+  "bucket_id": "uuid",
+  "session_ttl_minutes": 1440
+}
+```
+
+## Suggested Go shape
+
+- **Router**: Gin (or your existing router), e.g. `memory.GET("/mcp/tenant-context", handler)`.
+- **Middleware**: Reuse existing API auth if this route is only called from MCP with end-user tokens; otherwise restrict via `X-API-Key` (`PQC_MCP_SERVICE_API_KEY`) plus Bearer.
+- **RLS**: Ensure the resolved `bucket_id` belongs to the same org as the token claims.
+- **Errors**: `401` invalid token, `403` no entitlement, `404` user not provisioned.
+
+## Tests
+
+- Valid token → 200 and consistent bucket.
+- Token for user A must never return user B’s `bucket_id` or `api_key`.