@tideorg/mcp 1.4.1 → 1.9.0

package/package.json

@@ -1,45 +1,48 @@
-{
-  "name": "@tideorg/mcp",
-  "version": "1.4.1",
-  "description": "MCP server exposing Tide operational guidance — canon, playbooks, skills, prompts, adapters, and scenarios for AI coding agents",
-  "type": "module",
-  "bin": {
-    "tide-agent-pack": "mcp-server/dist/index.js"
-  },
-  "scripts": {
-    "build": "cd mcp-server && npm run build",
-    "prepublishOnly": "npm run build"
-  },
-  "files": [
-    "mcp-server/dist/",
-    "canon/",
-    "playbooks/",
-    "skills/",
-    "prompts/",
-    "adapters/",
-    "reference-apps/",
-    "GAP_REGISTER.md"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "zod": "^3.24.0"
-  },
-  "keywords": [
-    "mcp",
-    "tidecloak",
-    "tide",
-    "auth",
-    "security",
-    "threshold-cryptography",
-    "ai-agent",
-    "coding-agent"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/tide-foundation/tide-agent-pack"
-  },
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "@tideorg/mcp",
+  "version": "1.9.0",
+  "description": "MCP server exposing Tide operational guidance — canon, playbooks, skills, prompts, adapters, and scenarios for AI coding agents",
+  "type": "module",
+  "bin": {
+    "tide-agent-pack": "mcp-server/dist/index.js"
+  },
+  "scripts": {
+    "build": "cd mcp-server && npm run build",
+    "test": "cd mcp-server && npm test",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "mcp-server/dist/",
+    "canon/",
+    "playbooks/",
+    "skills/",
+    "prompts/",
+    "adapters/",
+    "reference-apps/",
+    "GAP_REGISTER.md",
+    "PRIVACY.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "keywords": [
+    "mcp",
+    "tidecloak",
+    "tide",
+    "auth",
+    "security",
+    "threshold-cryptography",
+    "ai-agent",
+    "coding-agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tide-foundation/tide-agent-pack"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/playbooks/add-auth-nextjs-existing.md

@@ -298,7 +298,9 @@ export function ProfileButton() {
 import { useTideCloak } from '@tidecloak/nextjs';
 
 export function ProfileButton() {
-  const { authenticated, user, login, logout } = useTideCloak();
+  // useTideCloak() has no `user` object. Read claims via getValueFromIdToken /
+  // getValueFromToken (e.g. getValueFromIdToken('preferred_username')).
+  const { authenticated, login, logout } = useTideCloak();
 
   if (!authenticated) {
     return <button onClick={login}>Login</button>;
@@ -334,34 +336,37 @@ export async function GET(req) {
 }
 ```
 
-**After** (Tide - manual JWT verification):
+**After** (Tide - server-side JWT verification):
 
-You must implement server-side JWT verification. Tide SDK does not provide automatic API protection.
+Tide ships a server-side verification helper. `@tidecloak/nextjs/server` exports `verifyTideCloakToken(config, token, allowedRoles?)` (re-exported from `@tidecloak/verify`). Use it instead of hand-rolling JWKS verification.
 
-See [verify-jwt-server-side.md](verify-jwt-server-side.md) for full implementation.
-
-**Quick pattern** (based on keylessh):
+**Quick pattern** (supported helper):
 ```typescript
 // app/api/users/route.ts
 import { NextRequest } from 'next/server';
-import { verifyTideJWT } from '@/lib/auth/tideJWT';  // See verify-jwt-server-side.md
+import { verifyTideCloakToken } from '@tidecloak/nextjs/server';
+import tcConfig from '../../../data/tidecloak.json';
 
 export async function GET(req: NextRequest) {
   const authHeader = req.headers.get('authorization');
   if (!authHeader) {
     return Response.json({ error: 'Unauthorized' }, { status: 401 });
   }
+  // Accepts "Bearer <jwt>" or "DPoP <jwt>"
+  const token = authHeader.replace(/^(Bearer|DPoP) /, '');
 
-  try {
-    const jwt = await verifyTideJWT(authHeader.replace('Bearer ', ''));
-    return Response.json({ users: [...] });
-  } catch (err) {
+  // Arg order is (config, token, allowedRoles) — config FIRST.
+  const payload = await verifyTideCloakToken(tcConfig, token, []);
+  if (!payload) {
     return Response.json({ error: 'Invalid token' }, { status: 401 });
   }
+  return Response.json({ users: [...] });
 }
 ```
 
-**Critical**: You must create `lib/auth/tideJWT.ts` with local JWKS verification. See [verify-jwt-server-side.md](verify-jwt-server-side.md) for exact implementation.
+`verifyTideCloakToken` verifies the signature against the adapter's embedded `jwk` (local JWKS), checks the issuer/`azp`, and optionally enforces `allowedRoles`. It returns the decoded payload on success and `false` on failure.
+
+**If you need the manual version** (or DPoP proof re-verification): see [verify-jwt-server-side.md](verify-jwt-server-side.md), which shows the same checks hand-rolled with `jose` in `lib/auth/tideJWT.ts`.
 
 ---
 
@@ -390,13 +395,24 @@ export const config = {
 };
 ```
 
-**After** (Tide - client-side route guard):
+**After** (Tide options):
+
+Option A — **use the Tide-provided proxy/middleware helpers.** `@tidecloak/nextjs/server` ships `createTideCloakProxy` (Next.js 16+ `proxy.ts`, Node runtime) and `createTideCloakMiddleware` (Edge `middleware.ts`, still supported). These replace a NextAuth-style middleware export and perform real token verification via `verifyTideCloakToken`:
+```typescript
+// proxy.ts (Next.js 16+)  — or middleware.ts on 15 and earlier
+import { createTideCloakProxy } from '@tidecloak/nextjs/server';
+import tcConfig from './data/tidecloak.json';
 
-**Remove proxy.ts / middleware.ts** if it only checks auth. Tide provider handles client-side auth state.
+export default createTideCloakProxy(tcConfig);
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/admin/:path*'],
+};
+```
 
-For API protection, use server-side JWT verification (Step 8), not proxy/middleware.
+Option B — **remove proxy.ts / middleware.ts** and rely on the client-side provider for UX gating plus server-side JWT verification in each API route (Step 8). Do this if you do not want request-interception at all.
 
-**Warning**: `proxy.ts` (and legacy `middleware.ts`) route protection is UI gating only, NOT real authorization. See [canon/feature-mapping.md](../canon/feature-mapping.md#protected-routes-vs-protected-apis).
+**Warning**: A plain, hand-written `proxy.ts` / `middleware.ts` that only checks cookie presence is UI gating only, NOT real authorization. The `createTideCloakProxy` / `createTideCloakMiddleware` helpers above DO verify the token, but you should still verify JWTs inside API routes (Step 8) as the authoritative enforcement point. See [canon/feature-mapping.md](../canon/feature-mapping.md#protected-routes-vs-protected-apis).
 
 If you want client-side route guards, implement in component:
 ```typescript
@@ -632,7 +648,7 @@ grep -r "from 'next-auth\|from \"next-auth" . --include="*.tsx" --include="*.ts"
 
 **Cause**: Old auth proxy or middleware still active.
 
-**Fix**: Remove or update `proxy.ts` (or legacy `middleware.ts`). Tide has no built-in Next.js request interception. Implement client-side route guards (Step 9) or server-side JWT verification.
+**Fix**: Remove or update `proxy.ts` (or legacy `middleware.ts`). Either switch it to Tide's `createTideCloakProxy` / `createTideCloakMiddleware` from `@tidecloak/nextjs/server` (Step 9, Option A), or remove it and rely on client-side route guards plus server-side JWT verification (Step 8).
 
 ---
 

package/playbooks/add-auth-nextjs-fresh.md

@@ -83,7 +83,7 @@ ls -la app/ 2>/dev/null && echo "App Router" || echo "Pages Router"
 npm install @tidecloak/nextjs
 ```
 
-**Verify version**: All `@tidecloak/*` packages are currently at `0.13.x`. Run `npm view @tidecloak/nextjs version` to confirm. Do not assume `1.0.0`.
+**Verify version**: `@tidecloak/*` packages are currently at `0.13.33` (run `npm view @tidecloak/nextjs version` to confirm/pin). Do not assume `1.0.0`.
 
 **Next.js 16+ bundler**: Next.js 16 defaults to Turbopack. The Tide SDK requires webpack for `strictExportPresence = false` and `@tidecloak/react` ESM alias. Update `package.json` scripts:
 ```json

package/playbooks/add-rbac-nextjs.md

@@ -137,13 +137,18 @@ Tide E2EE uses tag-based roles for **self-encryption** (user-bound, private data
 // Client-side E2EE with role enforcement (self-encryption)
 const { doEncrypt, doDecrypt } = useTideCloak();
 
+// Both take a single argument: an ARRAY of items. Each encrypt item is
+// { data, tags }; the tags drive the _tide_<tag>.self* role check.
 // Requires _tide_ssn.selfencrypt role
-const ciphertext = await doEncrypt('ssn', '123-45-6789');
+const [ciphertext] = await doEncrypt([{ data: '123-45-6789', tags: ['ssn'] }]);
 
+// doDecrypt takes the array of encrypted items ({ encrypted, tags }).
 // Requires _tide_ssn.selfdecrypt role
-const plaintext = await doDecrypt('ssn', ciphertext);
+const [plaintext] = await doDecrypt([{ encrypted: ciphertext, tags: ['ssn'] }]);
 ```
 
+**Signature note**: The `useTideCloak()` `doEncrypt`/`doDecrypt` are single-argument (`data`) wrappers. `data` is an array so you can encrypt/decrypt multiple fields in one call. This matches the shapes in [setup-forseti-e2ee.md](setup-forseti-e2ee.md) and [configure-e2ee-roles-and-policies.md](configure-e2ee-roles-and-policies.md). Do NOT call them with positional `(tag, value)` arguments — that form does not exist.
+
 Fabric enforces roles cryptographically. See [canon/concepts.md#tag-based-e2ee-roles](../canon/concepts.md#tag-based-e2ee-roles).
 
 **Self-encryption is user-bound**: only the encrypting user can decrypt. Giving another user the `selfdecrypt` role does NOT let them decrypt your data. For shared data between users, use policy-governed VVK encryption with a Forseti contract instead. See [setup-forseti-e2ee.md](setup-forseti-e2ee.md) and [canon/anti-patterns.md AP-24](../canon/anti-patterns.md#ap-24-using-self-encryption-for-shared-data-between-users).

package/playbooks/bootstrap-realm-from-template.md

@@ -79,6 +79,14 @@ This activates the Tide license and generates the VRK. No manual "Manage License
 
 **Critical:** Content-Type must be `application/x-www-form-urlencoded`. JSON causes failure.
 
+**Form parameters** (`setUpTideRealm` on `main`):
+
+| Param | Required | Default | Notes |
+|-------|----------|---------|-------|
+| `email` | Yes (for licensing) | — | Used to request the free-tier license. Ignored only when `skipLicense=true`. |
+| `isRagnarokEnabled` | No | `true` | Enables realm offboarding (Ragnarok). The endpoint already defaults it to `true`; passing `isRagnarokEnabled=true` explicitly is harmless and matches the default. |
+| `skipLicense` | No | `false` | When `true`, skips license activation (`email` unused) and returns early. Leave at the default for normal bootstrap. |
+
 ### Step 5: Enable IGA
 
 ```bash
@@ -94,28 +102,35 @@ curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/toggle-iga"
 Realm creation + Tide setup generates change requests that must be approved before proceeding.
 
 ```bash
-approve_and_commit() {
-  local TYPE=$1
-  TOKEN="$(get_token)"
-  local requests=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/$TYPE/requests" \
-    -H "Authorization: Bearer $TOKEN" 2>/dev/null || echo "[]")
+# Current /iga/change-requests/... surface (replaces legacy /tide-admin/change-set/...).
+# Bootstrap runs in FirstAdmin/Tideless mode, so authorize signs server-side (no enclave).
+# Full spec: canon/iga-change-requests-api.md.
+approve_all_pending() {
+  local TOKEN ready id
 
-  echo "$requests" | jq -c '.[]' | while read -r req; do
-    local id=$(echo "$req" | jq -r .draftRecordId)
-    local cst=$(echo "$req" | jq -r .changeSetType)
-    local at=$(echo "$req" | jq -r .actionType)
-    local payload="{\"changeSetId\":\"$id\",\"changeSetType\":\"$cst\",\"actionType\":\"$at\"}"
+  # 1. Authorize all pending CREATE/DELETE change requests in one call.
+  TOKEN="$(get_token)"
+  curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests/bulk-authorize" \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/json" \
+    -d '{"actionTypeIn":["CREATE","DELETE"],"limit":100}' > /dev/null 2>&1
 
+  # 2. Commit ready CRs; loop passes so dependent CRs become ready.
+  for pass in 1 2 3 4 5; do
     TOKEN="$(get_token)"
-    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/sign" \
-      -H "Authorization: Bearer $TOKEN" \
-      -H "Content-Type: application/json" -d "$payload"
-
-    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/commit" \
-      -H "Authorization: Bearer $TOKEN" \
-      -H "Content-Type: application/json" -d "$payload"
+    ready=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests?status=PENDING" \
+      -H "Authorization: Bearer $TOKEN" 2>/dev/null \
+      | jq -r '.[] | select(.readyToCommit==true) | .id' 2>/dev/null)
+    [ -z "$ready" ] && break
+    for id in $ready; do
+      TOKEN="$(get_token)"
+      curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests/$id/commit" \
+        -H "Authorization: Bearer $TOKEN" > /dev/null 2>&1
+    done
   done
 }
+# Legacy call sites pass a type arg the new list-all surface ignores.
+approve_and_commit() { approve_all_pending; }
 
 approve_and_commit clients
 ```
@@ -135,7 +150,7 @@ approve_and_commit clients
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| "Could not create tide realm" | JSON sent to `setUpTideRealm` instead of form data | Use `application/x-www-form-urlencoded` |
+| "Tide realm setup failed" / "Could not set up the Tide realm" | JSON sent to `setUpTideRealm` instead of form data | Use `application/x-www-form-urlencoded` |
 | "email is null or empty" | Missing email parameter | Add `--data-urlencode "email=..."` |
 | 404 on setUpTideRealm | Wrong path (`/tide-admin/setUpTideRealm`) | Correct path: `/vendorResources/setUpTideRealm` |
 | Realm import fails | Placeholders not replaced in template | Verify `sed` replaced all three: `REALM_NAME`, `CLIENT_NAME`, `CLIENT_APP_URL` |

package/playbooks/deploy-tidecloak-docker.md

@@ -372,34 +372,38 @@ curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/toggle-iga"
   -H "Content-Type: application/x-www-form-urlencoded" \
   --data-urlencode "isIGAEnabled=true"
 
-# 5. Auto-approve client change requests (created during realm setup)
-approve_and_commit() {
-  local TYPE=$1
+# 5. Auto-approve change requests created during realm setup.
+#    Uses the current /iga/change-requests/... surface (replaces the legacy
+#    /tide-admin/change-set/... surface). During bootstrap the realm is in
+#    FirstAdmin/Tideless mode, so authorize signs server-side (no enclave).
+#    See canon/iga-change-requests-api.md.
+approve_all_pending() {
+  local TOKEN ready id
+
+  # 1. Authorize every pending CREATE/DELETE change request in one call.
   TOKEN="$(get_token)"
-  local requests=$(curl -s -X GET \
-    "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/$TYPE/requests" \
-    -H "Authorization: Bearer $TOKEN" 2>/dev/null || echo "[]")
-
-  echo "$requests" | jq -c '.[]' | while read -r req; do
-    local payload=$(jq -n \
-      --arg id "$(echo "$req" | jq -r .draftRecordId)" \
-      --arg cst "$(echo "$req" | jq -r .changeSetType)" \
-      --arg at "$(echo "$req" | jq -r .actionType)" \
-      '{changeSetId:$id,changeSetType:$cst,actionType:$at}')
-
-    # Sign then commit
+  curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests/bulk-authorize" \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/json" \
+    -d '{"actionTypeIn":["CREATE","DELETE"],"limit":100}' > /dev/null 2>&1
+
+  # 2. Commit everything that is ready. Loop passes so dependent CRs
+  #    (e.g. a role must exist before its assignment) become ready and commit.
+  for pass in 1 2 3 4 5; do
     TOKEN="$(get_token)"
-    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/sign" \
-      -H "Authorization: Bearer $TOKEN" \
-      -H "Content-Type: application/json" -d "$payload"
-
-    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/commit" \
-      -H "Authorization: Bearer $TOKEN" \
-      -H "Content-Type: application/json" -d "$payload"
+    ready=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests?status=PENDING" \
+      -H "Authorization: Bearer $TOKEN" 2>/dev/null \
+      | jq -r '.[] | select(.readyToCommit==true) | .id' 2>/dev/null)
+    [ -z "$ready" ] && break
+    for id in $ready; do
+      TOKEN="$(get_token)"
+      curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests/$id/commit" \
+        -H "Authorization: Bearer $TOKEN" > /dev/null 2>&1
+    done
   done
 }
 
-approve_and_commit clients
+approve_all_pending
 
 # 6. Create admin user
 TOKEN="$(get_token)"
@@ -410,7 +414,7 @@ curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/users" \
 
 # 6b. Approve user creation (user is not queryable until committed with IGA enabled)
 sleep 2
-approve_and_commit users
+approve_all_pending
 
 # 6c. Assign tide-realm-admin role
 TOKEN="$(get_token)"
@@ -461,8 +465,7 @@ done
 
 # 9. Approve role assignment change requests
 sleep 2
-approve_and_commit users
-approve_and_commit roles
+approve_all_pending
 
 # 10. Update CustomAdminUIDomain for enclave approval popups
 #     CustomAdminUIDomain is OPTIONAL and APP-SPECIFIC: only needed when a separate
@@ -539,8 +542,8 @@ curl -s -X GET "$TIDECLOAK_URL/admin/realms/$REALM_NAME/vendorResources/get-inst
 | `POST /admin/realms` | Create realm from JSON template |
 | `POST /admin/realms/{realm}/vendorResources/setUpTideRealm` | Initialize Tide licensing + VRK |
 | `POST /admin/realms/{realm}/tide-admin/toggle-iga` | Enable IGA governance |
-| `POST /admin/realms/{realm}/tide-admin/change-set/sign` | Approve a change request |
-| `POST /admin/realms/{realm}/tide-admin/change-set/commit` | Commit an approved change |
+| `POST /admin/realms/{realm}/iga/change-requests/{id}/authorize` | Approve (sign) a change request. Batch: `POST /iga/change-requests/bulk-authorize`. Replaces legacy `tide-admin/change-set/sign`. |
+| `POST /admin/realms/{realm}/iga/change-requests/{id}/commit` | Commit an approved change. Replaces legacy `tide-admin/change-set/commit`. See `canon/iga-change-requests-api.md`. |
 | `POST /admin/realms/{realm}/tideAdminResources/get-required-action-link` | Generate admin invite link |
 | `GET /admin/realms/{realm}/vendorResources/get-installations-provider` | Download adapter config |
 | `POST /admin/realms/{realm}/vendorResources/sign-idp-settings` | Sign IdP settings with VRK. **ALWAYS required** after any Tide IDP config change (logo, background, backup toggle, custom admin domain, or client origin changes). Without it, the enclave rejects settings as unsigned. Requires active VRK/license. |

package/playbooks/diagnose-missing-roles-or-claims.md

@@ -93,7 +93,7 @@ function hasAnyRole(user: any, role: string): boolean {
 
 1. TideCloak Admin → Users → {user} → Role Mappings
 2. Assign role → {role-name}
-3. If IGA enabled: Approve change-set (requires quorum)
+3. If IGA enabled: authorize + commit the change request (requires quorum; see `canon/iga-change-requests-api.md`)
 4. User logout/login to get new token
 
 **Fix (default roles)**:
@@ -189,7 +189,7 @@ async function forceTokenRefresh() {
 
 ## Symptom: E2EE Role Not Working
 
-**What you see**: `doEncrypt('tag', data)` fails even though user has role.
+**What you see**: `doEncrypt([{ data, tags: ['tag'] }])` fails even though user has role.
 
 **Diagnostic**:
 

package/playbooks/initialize-admin-and-link-account.md

@@ -129,29 +129,32 @@ done
 ### Step 5: Approve user change requests
 
 ```bash
-# Reuse approve_and_commit from bootstrap-realm-from-template
-approve_and_commit() {
-  local TYPE=$1
-  TOKEN="$(get_token)"
-  local requests=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/$TYPE/requests" \
-    -H "Authorization: Bearer $TOKEN" 2>/dev/null || echo "[]")
+# Reuse approve_all_pending from bootstrap-realm-from-template.
+# Current /iga/change-requests/... surface (replaces legacy /tide-admin/change-set/...).
+# Bootstrap = FirstAdmin/Tideless: authorize signs server-side. Spec: canon/iga-change-requests-api.md.
+approve_all_pending() {
+  local TOKEN ready id
 
-  echo "$requests" | jq -c '.[]' | while read -r req; do
-    local id=$(echo "$req" | jq -r .draftRecordId)
-    local cst=$(echo "$req" | jq -r .changeSetType)
-    local at=$(echo "$req" | jq -r .actionType)
-    local payload="{\"changeSetId\":\"$id\",\"changeSetType\":\"$cst\",\"actionType\":\"$at\"}"
+  TOKEN="$(get_token)"
+  curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests/bulk-authorize" \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/json" \
+    -d '{"actionTypeIn":["CREATE","DELETE"],"limit":100}' > /dev/null 2>&1
 
+  for pass in 1 2 3 4 5; do
     TOKEN="$(get_token)"
-    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/sign" \
-      -H "Authorization: Bearer $TOKEN" \
-      -H "Content-Type: application/json" -d "$payload"
-
-    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/commit" \
-      -H "Authorization: Bearer $TOKEN" \
-      -H "Content-Type: application/json" -d "$payload"
+    ready=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests?status=PENDING" \
+      -H "Authorization: Bearer $TOKEN" 2>/dev/null \
+      | jq -r '.[] | select(.readyToCommit==true) | .id' 2>/dev/null)
+    [ -z "$ready" ] && break
+    for id in $ready; do
+      TOKEN="$(get_token)"
+      curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests/$id/commit" \
+        -H "Authorization: Bearer $TOKEN" > /dev/null 2>&1
+    done
   done
 }
+approve_and_commit() { approve_all_pending; }
 
 approve_and_commit users
 approve_and_commit roles
@@ -216,7 +219,7 @@ node -e "const c=require('$ADAPTER_OUTPUT'); console.log('jwk:', !!c.jwk, 'vendo
 | "Could not find configuration for Required Action" | Tide env vars missing from container | Restart container with all required env vars |
 | `tideUserKey` never appears | Admin didn't complete the linking flow | Open invite link in browser, complete the flow |
 | Enclave popups don't work from app | CustomAdminUIDomain not set | Run Step 6 |
-| Adapter JSON missing `jwk` | IGA not enabled | Run `toggle-iga` from `bootstrap-realm-from-template` Step 5 |
+| Adapter JSON missing `jwk` | `setUpTideRealm` did not run / no `tide-vendor-key` component + EdDSA key on the realm (the `jwk` is gated on those, not on IGA) | Re-run `setUpTideRealm` from `bootstrap-realm-from-template` Step 4 and confirm it returned 200 |
 
 ---
 

package/playbooks/protect-api-nextjs.md

@@ -76,7 +76,46 @@ Any FAIL means the API route is not properly protected. Use the implementation b
 
 ---
 
-## Quick Implementation (App Router)
+## Recommended: Use the Shipped `verifyTideCloakToken` Helper
+
+Tide ships a server-side verification helper — you do not have to hand-roll JWKS verification. `@tidecloak/nextjs/server` re-exports `verifyTideCloakToken` from `@tidecloak/verify`:
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest } from 'next/server';
+import { verifyTideCloakToken } from '@tidecloak/nextjs/server';
+import tcConfig from '../../../data/tidecloak.json';
+
+export async function GET(req: NextRequest) {
+  const authHeader = req.headers.get('authorization');
+  if (!authHeader) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+  const token = authHeader.replace(/^(Bearer|DPoP) /, '');
+
+  // Signature (arg order): verifyTideCloakToken(config, token, allowedRoles=[])
+  // config is FIRST. Pass roles to enforce them; [] to just verify the token.
+  const payload = await verifyTideCloakToken(tcConfig, token, ['admin']);
+  if (!payload) {
+    // Returns false on any failure (bad signature, issuer, azp, expiry, or role).
+    return Response.json({ error: 'Forbidden' }, { status: 403 });
+  }
+  return Response.json({ users: [...] });
+}
+```
+
+`verifyTideCloakToken`:
+- verifies the signature against the adapter's embedded `jwk` (local JWKS — no network call),
+- validates the issuer (`auth-server-url` + `/realms/<realm>`) and `azp` (against `config.resource`),
+- checks time claims with a small `clockTolerance`,
+- optionally enforces `allowedRoles` (matches across `realm_access.roles` and `resource_access[client].roles`),
+- returns the decoded payload on success, `false` on failure.
+
+Prefer this for standard API protection. The manual `jose` implementation below is the **under-the-hood alternative** — use it when you need custom behavior the helper does not cover (e.g. app-side DPoP proof re-verification, separate 401-vs-403 semantics, or `iat` future-validation). See [verify-jwt-server-side.md](verify-jwt-server-side.md).
+
+---
+
+## Quick Implementation — Manual (App Router)
 
 This section creates minimal versions of `lib/auth/tidecloakConfig.ts`, `lib/auth/tideJWT.ts`, and `lib/auth/protect.ts`. If you also follow [verify-jwt-server-side.md](verify-jwt-server-side.md), its richer versions **replace** these files (adds DPoP verification, client-role checking, `extractToken`, and `iat` validation).