@tideorg/mcp 1.4.1 → 1.9.0

package/playbooks/setup-server-delegation.md

@@ -1,142 +0,0 @@
-# Setup Server-Side Delegation
-
-For apps where the backend needs to call TideCloak admin APIs on behalf of authenticated users.
-
----
-
-## When to Use
-
-- Your server manages users, roles, or policies via TideCloak admin API
-- You need server-side role management or access approvals
-- You want to avoid using master admin credentials from your server
-
----
-
-## Prerequisites
-
-- TideCloak bootstrapped and running
-- `tidecloak.json` exported with `jwk`, `vendorId`, `homeOrkUrl`
-- App has working Tide login (provider wired, DPoP enabled)
-- Node.js 18+ on the server (Ed25519 support)
-
----
-
-## Steps
-
-### 1. Install server SDK
-
-```bash
-npm install @tidecloak/server
-```
-
-### 2. Create delegation instance
-
-```ts
-// server/lib/delegation.ts
-import { TideDelegation } from '@tidecloak/server';
-
-let _delegation: TideDelegation | null = null;
-
-export function getDelegation(): TideDelegation {
-  if (!_delegation) {
-    _delegation = new TideDelegation({
-      tidecloakUrl: process.env.TIDECLOAK_URL || config['auth-server-url'],
-      realm: process.env.TIDECLOAK_REALM || config.realm,
-      clientId: process.env.TIDECLOAK_CLIENT_ID || config.resource,
-    });
-  }
-  return _delegation;
-}
-```
-
-Use a lazy singleton. Do not create a new instance per request.
-
-### 3. Wire delegation exchange endpoint
-
-```ts
-app.post('/api/delegation', authenticate, getDelegation().handleDelegation());
-```
-
-This endpoint receives signed delegation artifacts from the browser and exchanges them with TideCloak for a delegation token.
-
-### 4. Add delegation middleware to admin routes
-
-```ts
-app.get('/api/admin/users',
-  authenticate,
-  requireAdmin,
-  getDelegation().requireDelegation(),
-  async (req, res) => {
-    const adminUrl = `${tidecloakUrl}/admin/realms/${realm}`;
-    const users = await req.delegation.fetch(`${adminUrl}/users`);
-    res.json(users);
-  }
-);
-```
-
-The middleware:
-- Checks if a cached delegation token exists for this user session
-- If yes: attaches `req.delegation` with `token` and `fetch()` helper
-- If no: responds 419 with a delegation challenge
-
-### 5. Wrap browser fetch with createTideFetch
-
-```ts
-import { createTideFetch } from '@tidecloak/js';
-
-// Wrap the app's fetch function
-const appFetch = createTideFetch(window.fetch);
-
-// Use appFetch for all server calls that may need delegation
-const users = await appFetch('/api/admin/users');
-```
-
-`createTideFetch` intercepts 419 responses, handles the delegation signing flow with the browser's DPoP key, and retries the original request.
-
-### 6. Optional: scope delegation roles
-
-```ts
-// Only include specific roles in the delegation token
-getDelegation().requireDelegation({
-  roles: {
-    realm: ['admin'],
-    clients: { 'my-app': ['manage-users'] }
-  }
-})
-```
-
-If `roles` is specified, only listed roles appear in the delegation token. Unlisted realms/clients are stripped. Cannot add roles the user does not have.
-
----
-
-## Verification
-
-- [ ] `@tidecloak/server` in server package.json
-- [ ] `/api/delegation` POST route wired with `handleDelegation()`
-- [ ] Admin routes use `requireDelegation()` middleware
-- [ ] Browser uses `createTideFetch` wrapper
-- [ ] Admin API calls succeed: user list, role management, etc.
-- [ ] 419 responses are handled transparently (no user-visible interruption)
-- [ ] Delegation token is cached (no 419 on every request)
-
----
-
-## Troubleshooting
-
-**Repeated 419 responses**
-Check that `/api/delegation` is wired correctly and the `authenticate` middleware sets `req.accessToken`.
-
-**"No pending delegation challenge"**
-Server restarted between 419 and delegation POST. Browser retries automatically.
-
-**"Delegation exchange failed"**
-Check TideCloak has `tide-chain-of-trust` client authenticator enabled and `DelegationToken:1` in VRK model whitelist. A VRK rotation is needed after adding the model ID.
-
-**"DPoP is not initialized"**
-`signDelegationRequest` needs the DPoP provider. Ensure `useDPoP` is in the TideCloakProvider config object.
-
-**Delegation token has wrong roles**
-If using scoped delegation, everything not listed is excluded. Omit `roles` for full permissions.
-
-**Admin API returns 403**
-The user does not have the required role (e.g., `tide-realm-admin` on `realm-management`). Delegation can only use roles the user already has.