@tideorg/mcp 1.4.0

package/canon/delegation.md

@@ -0,0 +1,195 @@
+# Server-Side Delegation - Canon
+
+Canonical reference for server-side admin API calls via delegation tokens.
+
+When your app server needs to call TideCloak admin APIs (manage users, roles, policies), it cannot use the browser's DPoP-bound access token. The delegation flow issues a new token bound to the server's ephemeral key.
+
+---
+
+## Packages
+
+| Package | Side | Purpose |
+|---------|------|---------|
+| `@tidecloak/server` | Server | `TideDelegation` class, middleware, DPoP proof generation |
+| `@tidecloak/js` | Browser | `createTideFetch` wrapper, `signDelegationRequest`, `signDpopApproval` |
+
+---
+
+## Flow: Forgetful Interrupt Pattern
+
+1. Browser calls server endpoint (e.g., `GET /api/admin/users`)
+2. Server `requireDelegation()` middleware checks cache. No cached token.
+3. Server generates ephemeral Ed25519 key, responds **419** with challenge
+4. `createTideFetch` intercepts 419, calls `IAMService.signDelegationRequest(payload)` and `IAMService.signDpopApproval(serverJkt)`
+5. Browser POSTs signed artifacts to `/api/delegation`
+6. Server `handleDelegation()` exchanges with TideCloak token endpoint
+7. TideCloak validates chain of trust, signs delegation token via ORK network
+8. Server caches delegation token, responds `{ delegated: true }`
+9. `createTideFetch` retries original request. Server finds cached token, proceeds.
+
+Subsequent requests use the cached token until it expires.
+
+---
+
+## Setup
+
+### Server
+
+```js
+import { TideDelegation } from '@tidecloak/server';
+
+const delegation = new TideDelegation({
+  tidecloakUrl: process.env.TIDECLOAK_URL,
+  realm: process.env.TIDECLOAK_REALM,
+  clientId: process.env.TIDECLOAK_CLIENT_ID,
+});
+
+// Exchange endpoint
+app.post('/api/delegation', authenticate, delegation.handleDelegation());
+
+// Protected route with delegation
+app.get('/api/admin/users',
+  authenticate,
+  delegation.requireDelegation(),
+  async (req, res) => {
+    const users = await req.delegation.fetch(adminUrl + '/users');
+    res.json(users);
+  }
+);
+```
+
+### Browser
+
+```js
+import { createTideFetch } from '@tidecloak/js';
+
+const appFetch = createTideFetch(window.fetch);
+
+// Delegation is transparent
+const users = await appFetch('/api/admin/users');
+```
+
+---
+
+## Scoped Delegation
+
+Limit roles in the delegation token. If `roles` is specified, only listed roles/clients appear. Everything else is stripped.
+
+```js
+// Only read role for my-app client
+delegation.requireDelegation({
+  roles: {
+    clients: { 'my-app': ['read'] }
+  }
+})
+
+// Realm + multiple clients
+delegation.requireDelegation({
+  roles: {
+    realm: ['admin'],
+    clients: {
+      'my-app': ['read', 'write'],
+      'other-app': ['view']
+    }
+  }
+})
+
+// No filtering (default)
+delegation.requireDelegation()
+```
+
+Rules:
+- Omitting `roles` entirely keeps all user roles
+- Once `roles` is specified, unlisted realms/clients are stripped
+- Cannot escalate. Requesting a role the user does not have silently drops it.
+
+---
+
+## Token Exchange Endpoint
+
+The server exchanges artifacts at TideCloak's standard OIDC token endpoint:
+
+```
+POST /realms/{realm}/protocol/openid-connect/token
+```
+
+Parameters (form-encoded):
+- `grant_type`: `urn:ietf:params:oauth:grant-type:token-exchange`
+- `client_id`: app client ID
+- `subject_token`: user's access token
+- `subject_token_type`: `urn:ietf:params:oauth:token-type:access_token`
+- `actor_token`: browser-signed delegation request JWT
+- `actor_token_type`: `urn:ietf:params:oauth:token-type:jwt`
+- `dpop_approval`: session key approval of server's DPoP key
+
+Headers:
+- `DPoP`: server's DPoP proof JWT (Ed25519, contains server's public key)
+
+Response: `{ access_token, token_type: "DPoP", expires_in, issued_token_type }`
+
+---
+
+## Chain of Trust
+
+Two-hop validation ensures the delegation token is legitimately authorized:
+
+**HOP 1**: `subject_token.cnf.jkt == thumbprint(BROWSER_KEY from actor_token header)`
+The browser that owns the access token is the same one that signed the delegation request.
+
+**HOP 2**: `actor_token.cnf.jkt == thumbprint(SERVER_KEY from DPoP header)`
+The delegation request authorizes the server's specific ephemeral key.
+
+Validated at two layers:
+1. TideCloak authenticator (Java) - before token is built
+2. ORK signing model (C#) - before token is threshold-signed
+
+---
+
+## Using req.delegation.fetch()
+
+The `fetch` helper on `req.delegation` handles DPoP proof generation and Authorization headers:
+
+```js
+// GET
+const users = await req.delegation.fetch(url);
+
+// POST with JSON
+await req.delegation.fetch(url, { method: 'POST', body: { name: 'role' } });
+
+// PUT
+await req.delegation.fetch(url, { method: 'PUT', body: { enabled: true } });
+
+// DELETE
+await req.delegation.fetch(url, { method: 'DELETE' });
+```
+
+---
+
+## Anti-Patterns
+
+- **Do not use master admin credentials** for server-side admin calls. Use delegation.
+- **Do not forward the user's browser token** to admin API. It is DPoP-bound to the browser's key.
+- **Do not skip DPoP on delegation requests**. The delegation token is DPoP-bound to the server's ephemeral key. Every admin API call needs a fresh DPoP proof with `ath` claim.
+- **Do not share delegation tokens across users**. They are cached per session ID.
+- **Do not hardcode server keys**. They are ephemeral Ed25519 keys, generated per session.
+
+---
+
+## Prerequisites
+
+- TideCloak with `tide-chain-of-trust` client authenticator enabled (added by default in recent TideCloak builds)
+- `DelegationToken:1` in the VRK model whitelist (requires VRK rotation after adding)
+- DPoP enabled on the client
+- `@tidecloak/server` installed on the backend
+- `createTideFetch` wrapping fetch on the frontend
+- An `authenticate` middleware that sets `req.accessToken` from the Authorization header
+
+---
+
+## Invariants
+
+- Delegation tokens are short-lived (max 600s / 10 minutes)
+- Server key is ephemeral per session, cleared when delegation cache expires
+- The browser must approve each server key via ORK enclave (DPoP approval)
+- Scoped delegation can only reduce roles, never add them
+- Delegation tokens have `act: { sub: clientId }` per RFC 8693