@tideorg/mcp 1.4.0

package/playbooks/verify-jwt-server-side.md

@@ -0,0 +1,439 @@
+# Verify JWT Server-Side (Complete Implementation)
+
+Complete guide to implementing server-side JWT verification for Tide.
+
+---
+
+## When to Use
+
+- Implementing API authentication
+- Need complete JWT verification code
+- Want production-ready implementation
+- Referenced by other playbooks
+
+---
+
+## Prerequisites
+
+- Adapter JSON exported from TideCloak
+- Adapter JSON has `jwk` field (required for Tide's JWT verification model)
+- Node.js project (Next.js or Express)
+
+---
+
+## Complete Implementation
+
+If you already created `lib/auth/tidecloakConfig.ts`, `lib/auth/tideJWT.ts`, and `lib/auth/protect.ts` from [protect-api-nextjs.md](protect-api-nextjs.md), the versions below **replace** them. This playbook adds DPoP verification, client-role checking in `hasRole`, `extractToken` (supports both Bearer and DPoP schemes), and `iat` future-validation.
+
+### Step 1: Install Dependencies
+
+```bash
+npm install jose
+```
+
+`jose` library: industry-standard JWT verification.
+
+---
+
+### Step 2: Adapter JSON Loader
+
+```typescript
+// lib/auth/tidecloakConfig.ts
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+export interface TidecloakConfig {
+  realm: string;
+  'auth-server-url': string;
+  'ssl-required': string;
+  resource: string;
+  'public-client': boolean;
+  'confidential-port': number;
+  jwk: { keys: any[] };  // Required: Embedded JWKS for local verification
+  vendorId?: string;
+  homeOrkUrl?: string;
+}
+
+export function loadTideConfig(): TidecloakConfig {
+  // Priority: env var > file
+  if (process.env.CLIENT_ADAPTER) {
+    return JSON.parse(process.env.CLIENT_ADAPTER);
+  }
+
+  const configPath = join(process.cwd(), 'data', 'tidecloak.json');
+  const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+
+  if (!config.jwk) {
+    throw new Error(
+      'Adapter JSON missing jwk field. ' +
+      'This field is required for Tide JWT verification. ' +
+      'Export via Tide-specific endpoint (providerId=keycloak-oidc-keycloak-json), not generic Keycloak adapter.'
+    );
+  }
+
+  return config;
+}
+```
+
+---
+
+### Step 3: JWT Verification
+
+```typescript
+// lib/auth/tideJWT.ts
+import { jwtVerify, createLocalJWKSet } from 'jose';
+import type { JWTPayload, JWTVerifyOptions } from 'jose';
+import { loadTideConfig } from './tidecloakConfig';
+
+// Lazy initialization — do NOT load config at module level.
+// Next.js 16 evaluates module-level code during `next build` for static
+// page generation. If tidecloak.json doesn't exist yet (placeholder or
+// pre-bootstrap), eager loading throws at build time.
+let _jwks: ReturnType<typeof createLocalJWKSet> | null = null;
+let _config: ReturnType<typeof loadTideConfig> | null = null;
+
+function getConfig() {
+  if (!_config) {
+    _config = loadTideConfig();
+    if (!_config.jwk) {
+      throw new Error(
+        'Adapter JSON missing jwk field. ' +
+        'This field is required for Tide JWT verification. ' +
+        'Export via Tide-specific endpoint (providerId=keycloak-oidc-keycloak-json), not generic Keycloak adapter.'
+      );
+    }
+    _jwks = createLocalJWKSet(_config.jwk);
+  }
+  return { config: _config, JWKS: _jwks! };
+}
+
+export async function verifyTideJWT(token: string): Promise<JWTPayload> {
+  const { config, JWKS } = getConfig();
+  const options: JWTVerifyOptions = {
+    issuer: `${config['auth-server-url'].replace(/\/+$/, '')}/realms/${config.realm}`,
+  };
+
+  const { payload } = await jwtVerify(token, JWKS, options);
+
+  // TideCloak access tokens use azp (authorized party) for the client ID.
+  // The aud claim typically contains "account", not the client ID.
+  if (payload.azp !== config.resource) {
+    throw new Error('Token azp does not match client');
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+
+  if (payload.exp && payload.exp < now) {
+    throw new Error('Token expired');
+  }
+
+  if (payload.iat && payload.iat > now + 60) {
+    throw new Error('Token issued in future');
+  }
+
+  return payload;
+}
+
+export function hasRole(payload: JWTPayload, role: string): boolean {
+  // Check realm roles
+  const realmRoles = (payload.realm_access as any)?.roles || [];
+  if (realmRoles.includes(role)) {
+    return true;
+  }
+
+  // Check client roles
+  const resourceAccess = payload.resource_access as any;
+  if (resourceAccess) {
+    for (const client of Object.values(resourceAccess)) {
+      const clientRoles = (client as any)?.roles || [];
+      if (clientRoles.includes(role)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+export function extractToken(authHeader: string | null): string {
+  if (!authHeader) {
+    throw new Error('Missing Authorization header');
+  }
+
+  if (authHeader.startsWith('Bearer ')) {
+    return authHeader.substring(7);
+  }
+
+  if (authHeader.startsWith('DPoP ')) {
+    return authHeader.substring(5);
+  }
+
+  throw new Error('Invalid Authorization header format');
+}
+```
+
+---
+
+### Step 4: DPoP Verification (Optional Defense-in-Depth)
+
+**Caveat: App-side DPoP proof re-verification is incompatible with `secureFetch`.** When the client uses `IAMService.secureFetch` from `@tidecloak/js`, the DPoP proofs it sends are in a Tide-specific format, not standard RFC 9449 compact JWS. Calling `jwtVerify()` on the `dpop` header fails with `401: Invalid Compact JWS`. DPoP binding is already enforced at TideCloak during token issuance — the `cnf.jkt` claim in the JWT proves the token was DPoP-bound. **JWT signature verification via embedded JWKS (VVK) is the primary security layer.** VERIFIED (LEARNINGS-batch-005 L-06).
+
+**If your app uses `secureFetch`**: Skip this step. The `withAuth` middleware from Step 5 should check for `cnf.jkt` presence (proving DPoP binding at issuance) but should NOT attempt to re-verify the DPoP proof itself. Remove or disable the `verifyDPoP()` call in `withAuth`.
+
+**If your app uses manual DPoP (not `secureFetch`)**: The verification below applies. When the `TideCloakProvider` has `useDPoP={{ mode: 'strict', alg: 'ES256' }}`, TideCloak binds access tokens with a `cnf.jkt` claim.
+
+```typescript
+// lib/auth/dpop.ts
+import { jwtVerify, decodeJwt, importJWK } from 'jose';
+import { createHash } from 'crypto';
+
+const jtiCache = new Map<string, number>();
+const JTI_TTL_MS = 2 * 60 * 1000;  // 2 minutes
+
+export async function verifyDPoP(
+  req: { method: string; url: string; headers: Headers },
+  accessToken: string
+): Promise<void> {
+  const dpopHeader = req.headers.get('dpop');
+  if (!dpopHeader) {
+    throw new Error('DPoP header missing');
+  }
+
+  // Parse the DPoP proof header (not the access token)
+  const parts = dpopHeader.split('.');
+  if (parts.length !== 3) throw new Error('Invalid DPoP JWT structure');
+
+  const headerJson = JSON.parse(
+    Buffer.from(parts[0], 'base64url').toString()
+  );
+
+  // Validate typ and alg from the DPoP proof header
+  if (headerJson.typ !== 'dpop+jwt') {
+    throw new Error('Invalid DPoP type');
+  }
+
+  const supportedAlgs = ['ES256', 'EdDSA'];
+  if (!supportedAlgs.includes(headerJson.alg)) {
+    throw new Error(`Unsupported DPoP algorithm: ${headerJson.alg}`);
+  }
+
+  // Must have jwk in proof header
+  const jwk = headerJson.jwk;
+  if (!jwk) throw new Error('Missing jwk in DPoP header');
+
+  // Verify signature using the embedded public key
+  const publicKey = await importJWK(jwk, headerJson.alg);
+  const { payload } = await jwtVerify(dpopHeader, publicKey);
+
+  // Verify htm (HTTP method)
+  if (payload.htm !== req.method) {
+    throw new Error('DPoP htm mismatch');
+  }
+
+  // Verify htu (HTTP URI, no query string)
+  const url = new URL(req.url);
+  const expectedHtu = `${url.protocol}//${url.host}${url.pathname}`;
+  if (payload.htu !== expectedHtu) {
+    throw new Error('DPoP htu mismatch');
+  }
+
+  // Verify iat freshness (120s window)
+  const now = Math.floor(Date.now() / 1000);
+  const iat = payload.iat as number;
+  if (iat < now - 120 || iat > now + 120) {
+    throw new Error('DPoP iat out of range');
+  }
+
+  // Verify jti not replayed
+  const jti = payload.jti as string;
+  if (!jti || jtiCache.has(jti)) {
+    throw new Error('DPoP jti missing or replayed');
+  }
+  jtiCache.set(jti, Date.now() + JTI_TTL_MS);
+
+  // Purge expired jtis periodically
+  if (jtiCache.size > 1000) {
+    const cutoff = Date.now();
+    jtiCache.forEach((expiry, key) => {
+      if (expiry < cutoff) jtiCache.delete(key);
+    });
+  }
+
+  // Verify cnf.jkt binding: access token's cnf.jkt must match
+  // the JWK Thumbprint (RFC 7638) of the DPoP proof's public key
+  const tokenPayload = decodeJwt(accessToken);
+  const expectedJkt = computeJwkThumbprint(jwk);
+
+  if ((tokenPayload.cnf as any)?.jkt !== expectedJkt) {
+    throw new Error('DPoP cnf.jkt mismatch — token not bound to this key');
+  }
+}
+
+/**
+ * Compute JWK Thumbprint per RFC 7638.
+ * Uses canonical JSON with alphabetically sorted required members only.
+ */
+function computeJwkThumbprint(jwk: any): string {
+  let canonical: string;
+  if (jwk.kty === 'EC') {
+    canonical = `{"crv":"${jwk.crv}","kty":"${jwk.kty}","x":"${jwk.x}","y":"${jwk.y}"}`;
+  } else if (jwk.kty === 'OKP') {
+    canonical = `{"crv":"${jwk.crv}","kty":"${jwk.kty}","x":"${jwk.x}"}`;
+  } else if (jwk.kty === 'RSA') {
+    canonical = `{"e":"${jwk.e}","kty":"${jwk.kty}","n":"${jwk.n}"}`;
+  } else {
+    throw new Error(`Unsupported key type for JWK thumbprint: ${jwk.kty}`);
+  }
+  return createHash('sha256').update(canonical).digest('base64url');
+}
+```
+
+---
+
+### Step 5: Middleware (Next.js App Router)
+
+```typescript
+// lib/auth/protect.ts
+import { NextRequest } from 'next/server';
+import { verifyTideJWT, hasRole, extractToken } from './tideJWT';
+import { verifyDPoP } from './dpop';
+import type { JWTPayload } from 'jose';
+
+type AuthHandler = (req: NextRequest, jwt: JWTPayload) => Promise<Response>;
+
+export function withAuth(handler: AuthHandler) {
+  return async (req: NextRequest) => {
+    const authHeader = req.headers.get('authorization');
+
+    try {
+      const token = extractToken(authHeader);
+      const jwt = await verifyTideJWT(token);
+
+      // DPoP binding check: if cnf.jkt is present, TideCloak bound
+      // this token with DPoP at issuance. This proves the token was
+      // DPoP-bound — no further proof verification is needed when
+      // using secureFetch (its proofs are Tide-specific, not RFC 9449).
+      //
+      // If you use manual DPoP (not secureFetch), uncomment the
+      // verifyDPoP call below to also verify the proof.
+      //
+      // const cnfJkt = (jwt as any).cnf?.jkt;
+      // if (cnfJkt) {
+      //   if (!req.headers.get('dpop')) {
+      //     return Response.json(
+      //       { error: 'DPoP proof required for DPoP-bound token' },
+      //       { status: 401 }
+      //     );
+      //   }
+      //   await verifyDPoP(req, token);
+      // }
+
+      return handler(req, jwt);
+    } catch (err) {
+      console.error('Auth failed:', err);
+      return Response.json(
+        { error: err instanceof Error ? err.message : 'Unauthorized' },
+        { status: 401 }
+      );
+    }
+  };
+}
+
+export function withRole(role: string, handler: AuthHandler) {
+  return withAuth(async (req, jwt) => {
+    if (!hasRole(jwt, role)) {
+      return Response.json({ error: 'Forbidden' }, { status: 403 });
+    }
+    return handler(req, jwt);
+  });
+}
+```
+
+---
+
+### Step 6: Express Middleware
+
+```typescript
+// server/auth.ts (Express)
+import express from 'express';
+import { verifyTideJWT, hasRole, extractToken } from './lib/auth/tideJWT';
+import { verifyDPoP } from './lib/auth/dpop';
+
+export async function authenticate(
+  req: express.Request,
+  res: express.Response,
+  next: express.NextFunction
+) {
+  const authHeader = req.headers.authorization;
+
+  try {
+    const token = extractToken(authHeader ?? null);
+    const jwt = await verifyTideJWT(token);
+
+    // DPoP enforcement: if token has cnf.jkt, it is DPoP-bound.
+    // Server must verify the DPoP proof. Without proof, reject.
+    const cnfJkt = (jwt as any).cnf?.jkt;
+    if (cnfJkt) {
+      if (!req.headers.dpop) {
+        return res.status(401).json({ error: 'DPoP proof required for DPoP-bound token' });
+      }
+      await verifyDPoP(req as any, token);
+    }
+
+    req.user = jwt;
+    next();
+  } catch (err) {
+    res.status(401).json({ error: 'Unauthorized' });
+  }
+}
+
+export function requireRole(role: string) {
+  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    if (!req.user || !hasRole(req.user, role)) {
+      return res.status(403).json({ error: 'Forbidden' });
+    }
+    next();
+  };
+}
+
+// Usage
+app.get('/api/admin/users', authenticate, requireRole('admin'), (req, res) => {
+  res.json({ users: [...] });
+});
+```
+
+---
+
+## Verification Checklist
+
+- [ ] Valid JWT verified successfully
+- [ ] Expired JWT rejected
+- [ ] Malformed JWT rejected
+- [ ] Wrong issuer rejected
+- [ ] Wrong audience rejected
+- [ ] Role check works
+- [ ] DPoP-bound token (has `cnf.jkt`) without DPoP proof header is rejected (401)
+- [ ] DPoP-bound token with valid DPoP proof is accepted
+- [ ] DPoP proof with wrong `htm` (method) is rejected
+- [ ] DPoP proof with wrong `htu` (URL) is rejected
+- [ ] Replayed DPoP `jti` is rejected
+
+---
+
+## Common Failures
+
+See [canon/troubleshooting.md T-02](../canon/troubleshooting.md#t-02-jwt-verification-fails-401-unauthorized).
+
+---
+
+## Known Uncertainties
+
+None. All critical requirements documented above.
+
+---
+
+## References
+
+- [protect-api-nextjs.md](protect-api-nextjs.md) - API protection guide
+- [canon/invariants.md I-03, I-04](../canon/invariants.md) - JWT verification rules
+- keylessh: `server/lib/auth/tideJWT.ts`, `server/auth.ts` (DC-01, DC-02)

package/prompts/add-admin-approval-flow.md

@@ -0,0 +1,50 @@
+# Prompt: Add an Admin-Only or Approval-Driven Workflow
+
+Copy-paste this prompt to an AI coding agent to add role-gated admin functionality to an existing Tide-enabled app.
+
+---
+
+## The Prompt
+
+> Add an admin-only workflow to my existing Tide-enabled Next.js app. Only users with the `admin` role should be able to access admin pages and admin API routes.
+>
+> **Assumptions**:
+> - The app already has Tide auth working (login/logout functional).
+> - TideCloak is running. The `admin` role exists in the realm and is assigned to at least one user.
+> - I may or may not have server-side JWT verification in place yet.
+>
+> **Inspect first**:
+> 1. Confirm Tide setup: `@tidecloak/nextjs` in `package.json`, `TideCloakProvider` in layout, `data/tidecloak.json` with `jwk` field.
+> 2. Check if `lib/auth/tideJWT.ts` and `lib/auth/protect.ts` exist.
+> 3. Check if existing admin API routes already verify JWT: `grep -r "verifyTideJWT\|withAuth\|withRole" app/api/admin/ lib/auth/`
+> 4. Check if existing admin pages use only `hasRealmRole()` / `hasClientRole()` for protection (UI gating only — not real authorization).
+>
+> **If Tide setup checks fail**, stop. Use the `tide-setup` skill first.
+>
+> **If `lib/auth/tideJWT.ts` does not exist**, use the `tide-route-and-api-protection` skill first (playbooks `protect-api-nextjs` then `verify-jwt-server-side`).
+>
+> **Once server-side auth is confirmed**, add admin RBAC:
+> 1. **Admin API routes**: Wrap with `withRole('admin', handler)` from `lib/auth/protect.ts`. Follow playbook `add-rbac-nextjs`.
+> 2. **Admin pages**: Add client-side `hasRole('admin')` checks for UI gating (show/hide admin content). This is UX only — the API enforces the real check.
+> 3. **Verify**: `curl` admin API with a non-admin token returns 403. Admin token returns 200. Bypassing the UI (direct curl) still enforces the role check.
+>
+> **Do not**:
+> - Treat `hasRole('admin')` on the client as sufficient protection. It is UI gating only.
+> - Create admin bypass paths or emergency override routes.
+> - Use Next.js `proxy.ts` (or legacy `middleware.ts`) for role enforcement. It runs at the edge and cannot verify JWT signatures.
+> - Implement a custom approval queue unless you have confirmed the TideCloak IGA workflow is appropriate. IGA uses cryptographic quorum enforcement — it is not a simple approval table.
+>
+> **About IGA (multi-admin approval)**:
+> If IGA is enabled on the realm, admin changes (user creation, role assignment) already require cryptographic quorum approval inside TideCloak. Do not build a custom approval system that duplicates or bypasses this. Deep governance configuration (quorum tuning, custom Forseti contracts) is only partially documented — see playbook `setup-iga-admin-panel` for what is currently available.
+
+---
+
+## Acceptance Criteria
+
+- [ ] Admin API returns 403 for non-admin user
+- [ ] Admin API returns 200 for admin user
+- [ ] Admin pages show "Access Denied" for non-admin (UI gating)
+- [ ] Direct curl to admin API without token returns 401
+- [ ] Direct curl with non-admin token returns 403
+- [ ] No admin bypass paths exist in the codebase
+- [ ] Post-auth redirect handler exists at configured `redirectUri` path

package/prompts/build-private-customer-portal.md

@@ -0,0 +1,85 @@
+# Prompt: Build a Private Customer Portal with Tide
+
+Copy-paste this prompt to an AI coding agent to scaffold a customer portal with Tide authentication and protected APIs.
+
+---
+
+## The Prompt
+
+> Build a private customer portal using Next.js and Tide authentication.
+>
+> **Route first, then act.** Use the development team model. Do not bundle all work into one pass.
+>
+> **Team sequence for this task**:
+> 1. **Scenario Resolver** — confirm this is a fresh app with standard auth (not shared encryption, not retrofit)
+> 2. **Setup / Platform Engineer** — bootstrap TideCloak if not running
+> 3. **Application Engineer** — wire SDK, provider, config, redirect handler, CSP, DPoP auth page
+> 4. **Security Engineer** — route guards + API protection + JWT/DPoP verification
+> 5. **IAM / Policy Engineer** — if roles or encryption needed
+> 6. **Reviewer / QA Engineer** — compliance check before handoff
+>
+> **Scenario check**: Check `reference-apps/INDEX.md` for a matching scenario pattern. If one matches, use its manifest for roles, policies, and playbook sequence.
+>
+> **Assumptions**:
+> - This is a fresh Next.js project (App Router).
+> - I want login, protected pages, and protected API routes.
+>
+> **Default dev flow** (for a new project):
+> ```
+> npm install
+> npm run init    # starts TideCloak, creates realm, exports tidecloak.json
+> npm run dev
+> ```
+> The init script handles TideCloak bootstrap automatically. Docker, curl, and jq are required. You must open the invite link printed by the script to link your admin Tide account.
+>
+> **Inspect first** (if not starting fresh):
+> 1. Is TideCloak running? `curl -sf http://localhost:8080 > /dev/null && echo "Running" || echo "Not running"`
+> 2. Check if `@tidecloak/nextjs` is in `package.json`.
+> 3. Check if `TideCloakProvider` (Next.js) or `TideCloakContextProvider` (React) is in `app/layout.tsx` or `app/providers.tsx`.
+> 4. Check if `data/tidecloak.json` exists with `jwk`, `vendorId`, and `homeOrkUrl` fields.
+>
+> **If TideCloak is not running and no init script exists**, bootstrap manually:
+> 1. Playbook `start-tidecloak-dev` — start the Docker container
+> 2. Playbook `bootstrap-realm-from-template` — create realm, enable licensing + IGA
+> 3. Playbook `initialize-admin-and-link-account` — create admin, link Tide account, export adapter JSON
+>
+> All three playbooks are sequential and mandatory. Bootstrap is NOT complete until a user with `tideUserKey` exists and `data/tidecloak.json` is exported.
+>
+> **If TideCloak is running but checks 2-4 fail**, follow the `tide-setup` skill to complete setup. Use playbook `add-auth-nextjs-fresh`.
+>
+> **Package versions** (before writing package.json):
+> 1. Run `npm view @tidecloak/nextjs version` to get the current stable version. Pin it exactly (e.g., `"0.13.26"`). Do not use `"latest"` or `"^"` for `@tidecloak/*` packages.
+> 2. If the resolved version is 0.99.x, skip it. Use the highest non-0.99.x version instead. If unsure, fall back to the versions in `canon/version-policy.md`.
+> 3. Run `npm view next version` and `npm view react version` to get current stable framework versions. Use caret ranges (e.g., `"^15.0.0"`). Align React and React DOM to the same major.
+> 4. Do not use `--force` or `--legacy-peer-deps` as the default install strategy. If peer dependency conflicts arise, resolve them by aligning versions.
+> 5. After writing package.json, include a short version-selection summary in your output: which versions you chose and why.
+>
+> **Build sequence** (follow playbooks in order):
+> 1. **Setup**: Playbook `add-auth-nextjs-fresh`. Includes SDK install, provider wiring with DPoP, adapter JSON, silent SSO file, post-auth redirect handler, and CSP.
+> 2. **Login**: Use `useTideCloak()` hook. Verify login redirects to TideCloak and back.
+> 3. **Protected pages**: Playbook `protect-routes-nextjs`. These are UI gating only — not real authorization.
+> 4. **Protected APIs**: Playbooks `protect-api-nextjs` then `verify-jwt-server-side`. This is where real authorization happens. Every API route returning customer data must verify JWT server-side.
+> 5. **Verify**: Unauthenticated `curl` to API returns 401. Valid token returns 200. Direct API call bypassing UI still enforces auth.
+>
+> **Do not**: Create fake auth helpers, plain-text role cookies, or ad hoc login logic. Do not treat `hasRole()` or route guards as real API protection. See `adapters/AGENTS.md` Forbidden Shortcuts for the full list.
+>
+> **If I later need roles** (admin vs customer), follow playbook `add-rbac-nextjs`. Only after API protection is verified.
+>
+> **If I later need to encrypt customer data**, default to self-encryption (user-bound — only the encrypting user can decrypt). Run playbook `configure-e2ee-roles-and-policies` to set up `_tide_{tag}.selfencrypt`/`.selfdecrypt` roles, then follow playbook `add-rbac-nextjs` (E2EE section). Do NOT rename roles to `encrypt`/`decrypt` — the suffix does not change the model.
+>
+> **If I explicitly need multiple users to decrypt the same data**, that is a different encryption model (policy-governed VVK). Route to `setup-forseti-e2ee`. It requires a Forseti contract, policy signing, and `IAMService.doEncrypt(data, policyBytes)`. Do not treat this as a role rename from self-encryption.
+
+---
+
+## Acceptance Criteria
+
+- [ ] TideCloak running with realm configured and adapter JSON exported
+- [ ] Login redirects to TideCloak and returns authenticated
+- [ ] Protected pages redirect unauthenticated users to login
+- [ ] API routes return 401 without valid JWT
+- [ ] API routes return 200 with valid JWT
+- [ ] Direct API call (bypassing UI) still returns 401/403
+- [ ] Browser console shows no CSP violations or 404s
+- [ ] DPoP is enabled on the provider
+- [ ] `silent-check-sso.html` exists in `public/`
+- [ ] Post-auth redirect handler exists at configured `redirectUri` path (no 404 after login)

package/prompts/migrate-generic-auth-to-tide.md

@@ -0,0 +1,67 @@
+# Prompt: Migrate from Generic Auth to Tide (Constrained — Inspection and Planning Only)
+
+Copy-paste this prompt to an AI coding agent to assess an existing auth setup and plan a migration to Tide. This prompt is intentionally constrained because a universal migration recipe does not yet exist.
+
+---
+
+## Important Limitation
+
+There is no fully documented Keycloak-to-TideCloak migration path (GAP-023, STILL_UNRESOLVED). All Tide exemplars are greenfield. This prompt guides inspection, planning, and partial implementation using the available setup and protection playbooks. It does not provide an automated end-to-end migration.
+
+---
+
+## The Prompt
+
+> I have an existing Next.js app with authentication. I want to migrate to Tide. Help me assess the current setup and plan the migration.
+>
+> **This is a planning and incremental migration prompt, not a one-shot rewrite.** A universal Tide migration recipe is not yet available. Work with what the Tide playbooks support today.
+>
+> **Inspect first** (before any code changes):
+> 1. What auth is currently in use? `grep -r "NextAuth\|next-auth\|passport\|jsonwebtoken\|jose\|auth0\|clerk\|supabase" package.json lib/ app/ pages/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -20`
+> 2. Where is the auth provider wired? `grep -r "SessionProvider\|AuthProvider\|ClerkProvider" app/layout.tsx pages/_app.tsx 2>/dev/null`
+> 3. How are API routes protected today? `grep -r "getServerSession\|getToken\|requireAuth\|authenticate\|verifyToken" app/api/ pages/api/ lib/ --include="*.ts" 2>/dev/null | head -20`
+> 4. How are routes guarded? `grep -r "useSession\|isAuthenticated\|PrivateRoute\|AuthGuard" app/ pages/ components/ --include="*.tsx" 2>/dev/null | head -10`
+> 5. Is there existing role/permission logic? `grep -r "role\|permission\|isAdmin\|hasRole" app/ lib/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -10`
+> 6. Does any proxy/middleware handle auth? `cat proxy.ts 2>/dev/null || cat middleware.ts 2>/dev/null`
+>
+> **Produce an assessment** (do not start coding yet):
+> - List the current auth provider and its integration points (provider wrapper, API middleware, route guards, session storage).
+> - Identify which API routes are currently protected and how.
+> - Identify any role or permission logic.
+> - Identify what can be replaced incrementally vs what requires simultaneous changes.
+>
+> **Package versions** (when installing Tide packages):
+> - Run `npm view @tidecloak/nextjs version` before adding to package.json. Pin the exact version. Do not use `"latest"`.
+> - If the resolved version is 0.99.x, skip it. Fall back to `canon/version-policy.md`.
+> - Do not use `--force` or `--legacy-peer-deps`. Align versions to resolve peer conflicts.
+>
+> **Incremental migration order** (using existing Tide playbooks):
+> 1. Add Tide provider alongside existing auth — playbook `add-auth-nextjs-existing`. Both systems coexist.
+> 2. Verify Tide login works independently. Do not proceed until confirmed.
+> 3. Migrate one API route to Tide JWT verification as a pilot — playbooks `protect-api-nextjs` then `verify-jwt-server-side`.
+> 4. Migrate remaining API routes.
+> 5. Replace route guards with Tide `useTideCloak()` guards — playbook `protect-routes-nextjs`. These are UI-only in both old and new systems.
+> 6. Add RBAC on Tide claims if needed — playbook `add-rbac-nextjs`.
+> 7. Remove old auth provider and its dependencies. Verify everything works with Tide only.
+>
+> **What cannot be migrated automatically**:
+> - **Realm migration** — no Keycloak-to-TideCloak procedure documented. You may need to recreate the realm. (GAP-023)
+> - **Users** — must be created in TideCloak and linked via Tide account linking. No bulk migration tool.
+> - **Sessions** — cannot be transferred. Users re-login after the switch.
+> - **Passwords** — Tide uses threshold PRISM. Existing password hashes are not transferable.
+>
+> **Do not**: Claim a universal migration recipe exists. Do not silently remove old auth before confirming Tide login works. Do not create shim layers that fake Tide behavior using old tokens. See `adapters/AGENTS.md` Forbidden Shortcuts for additional prohibitions.
+>
+> **If the app is not yet connected to TideCloak at all**, start with the `tide-setup` skill.
+
+---
+
+## Acceptance Criteria
+
+- [ ] Assessment document produced listing current auth integration points
+- [ ] Tide provider added and login verified before any old auth is removed
+- [ ] Each migrated API route verified: 401 without Tide JWT, 200 with valid Tide JWT
+- [ ] Old auth removed only after all routes and APIs confirmed working with Tide
+- [ ] No shim layers, fake auth helpers, or plain-text role cookies in the final codebase
+- [ ] DPoP enabled from the start
+- [ ] Post-auth redirect handler exists at configured `redirectUri` path