@tideorg/mcp 1.4.2 → 1.9.1

package/playbooks/setup-iga-admin-panel.md

@@ -12,6 +12,13 @@ Build an admin UI for managing IGA change requests with quorum governance.
 
 **Do not use** if you only need end-user authentication. See [add-auth-nextjs-fresh.md](add-auth-nextjs-fresh.md) instead.
 
+**A custom panel is optional.** The stack already ships two working admin consoles that manage IGA change requests out of the box:
+
+- **tide-console SPA** — a built Vite/React admin UI bundled inside the `tidecloak-key-provider` jar and served by TideCloak.
+- **Legacy keycloak.v2 console** — the stock Keycloak admin UI, which on the shipped build carries a native `tide-change-requests` section.
+
+Build a custom panel only when you need to embed CR governance inside your own product UI. Otherwise use one of the shipped consoles.
+
 ---
 
 ## Prerequisites
@@ -34,190 +41,136 @@ All endpoints below are relative to:
 
 Example: `http://localhost:8080/admin/realms/myrealm`
 
+The consolidated IGA REST surface is rooted at `/admin/realms/{realm}/iga` (server class `IgaAdminResource`). Change requests live under `/iga/change-requests`.
+
+> **Legacy bootstrap-compat surface.** The canonical bootstrap script (`localtest/init/init_tidecloak.sh`) and the `tidecloak-js` `AdminAPI` still call an older `/tide-admin/change-set/{type}/requests`, `/tide-admin/change-set/sign`, and `/tide-admin/change-set/commit` surface. That path still exists for backward compatibility and is fine for scripted bootstrap approval, but the `/iga/*` surface documented below is the current API for a live admin panel. Do not mix the two.
+
 ---
 
 ## Change Request Lifecycle
 
+Current `/iga/change-requests/...` surface (replaces legacy `/tide-admin/change-set/...`, confirmed by Tide 2026-07-07). **Full spec: `canon/iga-change-requests-api.md`.**
+
 ```
-1. Admin creates change (role assignment, group change, etc.)
-   -> Draft created automatically (DRAFT/PENDING)
-2. Admin reviews: GET /tide-admin/change-set/all/requests
-3. Admin approves: POST /tide-admin/change-set/sign/batch
-   -> If Tide multi-admin: returns signing challenge for enclave
-   -> Submit signed result: POST /tideAdminResources/add-review
-4. Once enough approvals: POST /tide-admin/change-set/commit/batch
-5. Or cancel: POST /tide-admin/change-set/cancel/batch
+1. Admin performs a governed change (role assignment, group change, etc.)
+   -> The write returns 202 Accepted; a change request is created (PENDING)
+2. Admin reviews:  GET  /iga/change-requests?status=PENDING
+3. Admin approves: POST /iga/change-requests/{id}/authorize   (body {} optional)
+   -> Tide MultiAdmin mode: sign via the enclave two-phase exchange
+      GET/POST /iga/change-requests/{id}/approval-model
+   -> FirstAdmin / Tideless mode: authorize signs server-side, no popup
+4. Once threshold met: POST /iga/change-requests/{id}/commit  (412 if under threshold)
+5. Or reject:          POST /iga/change-requests/{id}/deny
 ```
 
+`authorize` (simple lane: firstAdmin/Tideless) records an approval and **never commits** — it refuses tide-multiAdmin CRs. `approve` is the multiAdmin enclave lane: it approves AND auto-commits once quorum is met (this is the deployed console "Authorize" button). `commit` is the explicit apply-only step for a CR that already has enough approvals (412 if sub-quorum). Use `bulk-authorize` to act on many at once.
+
 ---
 
 ## Endpoints
 
-### Counts (Lightweight)
+### List / Get
 
 ```
-GET  /tide-admin/change-set/counts
+GET  /iga/change-requests?status=PENDING     # PENDING|APPROVED|DENIED|CANCELLED
+GET  /iga/change-requests/{id}               # single CR (keyed by `id`)
 ```
 
-Use this for dashboard badges and summary views. Avoids fetching full request payloads.
+Each CR carries `id`, `entityType`, `actionType`, `status`, `readyToCommit`, `threshold`, `authorizers[]`, `dependsOn`/`blocked`. Derive dashboard counts from the list (there is no separate counts endpoint on the new surface; no per-type request endpoints and no `all/requests` path either).
 
-### List Requests
+### Authorize (Sign)
 
 ```
-GET  /tide-admin/change-set/all/requests         # All change requests (single call)
-GET  /tide-admin/change-set/users/requests        # User changes only
-GET  /tide-admin/change-set/roles/requests        # Role changes only
-GET  /tide-admin/change-set/clients/requests      # Client changes only
-GET  /tide-admin/change-set/groups/requests       # Group changes only
+POST /iga/change-requests/{id}/authorize     # body {} optional  → 200/403/409 (409 = four-eyes)
+POST /iga/change-requests/bulk-authorize     # {"actionTypeIn":["CREATE","DELETE"],"limit":100} → 429 if a bulk run is active
 ```
 
-### Sign / Approve
+### Commit / Deny
 
 ```
-POST /tide-admin/change-set/sign/batch            # Approve (sign) changes
+POST /iga/change-requests/{id}/commit        # → 200 (APPROVED) / 412 (under threshold or unmet dependency)
+POST /iga/change-requests/{id}/deny          # → 204
 ```
 
-### Commit / Cancel
+### Enclave Review (Tide MultiAdmin)
 
 ```
-POST /tide-admin/change-set/commit/batch          # Commit approved changes
-POST /tide-admin/change-set/cancel/batch          # Cancel pending changes
+GET  /iga/change-requests/{id}/approval-model   # → { changeRequestId, requestModel(base64) }
+POST /iga/change-requests/{id}/approval-model   # { "requestModel": "<base64 doken>" } → { recorded, authCount, threshold }
 ```
 
-### Enclave Review and Rejection
+The two-phase `approval-model` exchange replaces the legacy `tideAdminResources/add-review`. In FirstAdmin / Tideless mode, `authorize` signs server-side and no enclave step is needed.
+
+### Deprecated: add-review / add-rejection
 
 ```
-POST /tideAdminResources/add-review               # Submit Tide enclave signed review (multipart/form-data)
-POST /tideAdminResources/add-rejection            # Reject a change (multipart/form-data)
+POST /tideAdminResources/add-review               # 410 Gone (deprecated)
+POST /tideAdminResources/add-rejection            # 410 Gone (deprecated)
 ```
 
-**Content-type warning**: Both `add-review` and `add-rejection` use `multipart/form-data`, NOT JSON. All other mutation endpoints (`sign/batch`, `commit/batch`, `cancel/batch`) use `application/json`. If you send JSON to `add-rejection`, the server silently ignores the payload.
+Both endpoints were removed as part of the IGA decoupling and now return **`410 Gone`**. Approval goes through `/iga/change-requests/{id}/authorize` (plus the `approval-model` enclave exchange in Tide MultiAdmin mode) and rejection through `/iga/change-requests/{id}/deny`.
 
-```typescript
-// Rejection example — must use FormData, not JSON
-const formData = new FormData();
-formData.append("changeSetId", draftRecordId);
-formData.append("actionType", actionType);
-formData.append("changeSetType", changeSetType);
-
-await fetch(`${TC_URL}/admin/realms/${realm}/tideAdminResources/add-rejection`, {
-  method: 'POST',
-  headers: { 'Authorization': `Bearer ${adminToken}` },
-  body: formData  // NOT JSON.stringify
-});
-```
-
-### Activity and Comments
+### Comments
 
 ```
-GET  /tide-admin/change-set/{id}/activity         # Activity log + comments
-POST /tide-admin/change-set/{id}/comments         # Add comment to change request
+GET/POST   /iga/change-requests/{id}/comments             # { "comment": "..." } (≤2000 chars)
+PUT/DELETE /iga/change-requests/{id}/comments/{commentId}
 ```
 
----
-
-## Approve (Sign) Request -- Code Example
-
-```typescript
-const response = await fetch(`${TC_URL}/admin/realms/${realm}/tide-admin/change-set/sign/batch`, {
-  method: 'POST',
-  headers: {
-    'Authorization': `Bearer ${adminToken}`,
-    'Content-Type': 'application/json'
-  },
-  body: JSON.stringify({
-    changeSets: [{
-      changeSetId: "draft-record-id",
-      changeSetType: "USER_ROLE",
-      actionType: "CREATE",
-      policyRoleId: "optional-role-uuid",  // omit to use tide-realm-admin policy
-      dynamicData: ["optional-base64"]     // custom Forseti contract input
-    }]
-  })
-});
-
-// If Tide multi-admin mode:
-// response[0].requiresApprovalPopup === true
-// -> decode changeSetDraftRequests (base64)
-// -> present to Tide enclave for admin signing
-// -> submit via POST /tideAdminResources/add-review
-```
+There is no per-request `/activity` endpoint on the current surface; comments are the audit thread.
 
 ---
 
-## TypeScript Client (KcAdminClient) Usage
+## TypeScript Client Usage
+
+There is no `@keycloak/keycloak-admin-client` `KcAdminClient.tideUsersExt` extension on `tidecloak-js` main. The change-request surface is a hand-rolled fetch client, `AdminAPI` (`packages/tidecloak-js/src/AdminAPI.js`), exposed through `@tidecloak/react`. It targets the legacy bootstrap-compat `/tide-admin/change-set/*` endpoints:
 
 ```typescript
-import KcAdminClient from "@keycloak/keycloak-admin-client";
+import { AdminAPI } from "@tidecloak/react";
 
-const client = new KcAdminClient({ baseUrl: "http://localhost:8080" });
-await client.auth({
-  username: "admin",
-  password: "admin",
-  grantType: "password",
-  clientId: "admin-cli"
-});
+const api = new AdminAPI({ baseUrl, realm, token });
 
-// Counts
-const counts = await client.tideUsersExt.getChangeSetCounts();
+// List (combines user + role change requests)
+const pending = await api.getPendingChangeSets();
+const userCrs = await api.getUserChangeRequests();
+const roleCrs = await api.getRoleChangeRequests();
 
-// All requests
-const all = await client.tideUsersExt.getAllChangeSetRequests();
+// Approve a single change set (sent as FormData, single object — not { changeSets: [...] })
+await api.approveChangeSet({ changeSetId, actionType, changeSetType });
 
-// Approve
-await client.tideUsersExt.approveDraftChangeSet({
-  changeSets: [{ changeSetId: "id", changeSetType: "USER_ROLE", actionType: "CREATE" }]
-});
+// Multi-admin: approve with an enclave signature
+await api.approveChangeSetWithSignature(/* signed payload */);
 
 // Commit
-await client.tideUsersExt.commitDraftChangeSet({
-  changeSets: [{ changeSetId: "id", changeSetType: "USER_ROLE", actionType: "CREATE" }]
-});
-
-// Activity and comments
-const activity = await client.tideUsersExt.getChangeSetActivity({ id: "draft-id" });
-await client.tideUsersExt.addChangeSetComment({ id: "draft-id", comment: "LGTM" });
+await api.commitChangeSet({ changeSetId, actionType, changeSetType });
 ```
 
+There are no `getChangeSetCounts`, `getAllChangeSetRequests`, `getChangeSetActivity`, or `addChangeSetComment` methods. For a panel built on the current `/iga/*` surface, call the `/iga/change-requests/*` endpoints (see the **Endpoints** section above and `canon/iga-change-requests-api.md`) directly with `fetch` rather than via this SDK.
+
 ---
 
 ## Policy Management Endpoints
 
 ```
-PUT  /tide-admin/forseti-contracts               # Create/update Forseti contract
-GET  /tide-admin/forseti-contracts               # List contracts
-POST /tide-admin/policy-templates                # Create policy template
-GET  /tide-admin/policy-templates                # List templates
-PUT  /tide-admin/ssh-policies                    # Attach policy to role
-GET  /tide-admin/ssh-policies                    # List role policies
-POST /tide-iga-provider/role-policy/{roleId}/init-cert  # Store signed policy on role (JSON: initCert required, initCertSig optional; no doken field)
-GET  /tide-admin/role-policies                   # Roles with policy status
+GET  /iga/forseti-contracts                      # List contracts
+GET  /iga/forseti-contracts/{id}                 # Get one contract
+POST /iga/forseti-contracts                      # Create a Forseti contract (POST, not PUT)
+DELETE /iga/forseti-contracts/{id}               # Delete a contract
+GET  /iga/role-policies                          # Roles with policy status
 ```
 
+Create is `POST /iga/forseti-contracts` (there is no PUT). Policy-template, SSH-policy, and `role-policy/{roleId}/init-cert` endpoints are not part of the current surface.
+
 ---
 
-## ChangeSetType Values
-
-**VERIFIED** (vendor confirmation, GAP-041 resolved). Full enum (14 values):
-
-| Value | Description | Draft Status |
-|-------|-------------|-------------|
-| `DEFAULT_ROLES` | Default role assignment | ACTIVE (auto) |
-| `USER` | User creation | DRAFT |
-| `USER_ROLE` | User-to-role assignment | DRAFT |
-| `USER_GROUP_MEMBERSHIP` | User-to-group membership | DRAFT |
-| `ROLE` | Role definition change | ACTIVE (auto, creation) / DRAFT (deletion if users assigned) |
-| `COMPOSITE_ROLE` | Composite role change | DRAFT |
-| `CLIENT` | Client configuration change | DRAFT (when users exist) |
-| `CLIENT_DEFAULT_USER_CONTEXT` | Client scope mappings | DRAFT |
-| `CLIENT_FULLSCOPE` | Client full-scope toggle | DRAFT |
-| `GROUP` | Group definition change | — |
-| `GROUP_ROLE` | Group-to-role assignment | DRAFT |
-| `GROUP_MOVE` | Group hierarchy change | DRAFT |
-| `REALM_LICENSING` | Realm license change | DRAFT |
-| `POLICY` | Policy change (derived from USER_ROLE) | DRAFT |
-
-**ACTIVE vs DRAFT**: Role creation and default-role assignment get ACTIVE status (recorded for audit but non-blocking — no sign/commit needed). All other actions get DRAFT status requiring quorum sign/commit. Master realm and IGA-disabled realms are always exempt.
+## Change Request Taxonomy
+
+The current surface does not use a `ChangeSetType` enum. Each change request carries two free-form String columns on `IgaChangeRequestEntity`:
+
+- **`entityType`** — one of: `USER`, `REALM`, `ROLE`, `GROUP`, `CLIENT`, `CLIENT_SCOPE`, `ORGANIZATION`, `COMPOSITE_ROLE`, `CLIENT_SCOPE_CLIENT`, `CLIENT_SCOPE_ROLE`, `PROTOCOL_MAPPER`, `REALM_DEFAULT_SCOPE`, `SCOPE_MAPPING`.
+- **`actionType`** — a free-form verb such as `CREATE`, `SET`, `UPDATE`, `ASSIGN`, or an `ADOPT_*` variant.
+
+Read both values back from the `GET /iga/change-requests` response; do not hardcode a fixed enum. Some change requests (e.g. role creation and default-role adoption) commit automatically as part of the login-closure converge and never need an explicit authorize/commit; the rest require quorum authorize/commit. The master realm and IGA-disabled realms are exempt from governance entirely.
 
 ## Status Values
 
@@ -235,13 +188,13 @@ GET  /tide-admin/role-policies                   # Roles with policy status
 
 A working IGA admin panel must include:
 
-1. **Pending list** -- Display all change requests in `DRAFT` or `PENDING` status. Use `GET /tide-admin/change-set/all/requests` and filter by status.
+1. **Pending list** -- Display change requests via `GET /iga/change-requests?status=PENDING` (keyed by `id`).
 
-2. **Approve button** -- Triggers `POST /tide-admin/change-set/sign/batch` with selected change set IDs.
+2. **Approve button** -- Triggers `POST /iga/change-requests/{id}/authorize` per selected CR (or `POST /iga/change-requests/bulk-authorize` for a batch).
 
-3. **Enclave popup** -- When `requiresApprovalPopup === true` in the sign response, decode `changeSetDraftRequests` (base64) and present the Tide enclave iframe for the admin to complete threshold signing. Submit the signed result via `POST /tideAdminResources/add-review`.
+3. **Enclave popup** -- In Tide MultiAdmin mode, complete the two-phase enclave exchange: `GET /iga/change-requests/{id}/approval-model` → sign in the enclave → `POST /iga/change-requests/{id}/approval-model` with the base64 doken. In FirstAdmin/Tideless mode, `authorize` signs server-side and no popup is needed.
 
-4. **Batch support** -- The sign, commit, and cancel endpoints accept arrays. The UI should support selecting multiple change requests and acting on them in a single call.
+4. **Batch support** -- Use `POST /iga/change-requests/bulk-authorize` (`{"actionTypeIn":[...],"limit":N}`) to approve many CRs at once; commit each ready CR (`readyToCommit === true`).
 
 5. **Role check** -- Only users with admin roles should see the panel. Verify the admin token includes the required realm-admin or delegated role before rendering the UI. This is UI gating only; the server enforces authorization on every API call.
 
@@ -251,22 +204,21 @@ A working IGA admin panel must include:
 
 ### Lifecycle
 
-- [ ] Creating a role assignment produces a DRAFT change request visible via `GET .../all/requests`
-- [ ] Signing a change request transitions status from DRAFT/PENDING toward APPROVED
-- [ ] In multi-admin mode, signing returns `requiresApprovalPopup === true` and enclave flow completes
-- [ ] Committing an APPROVED change request applies the change and sets status to ACTIVE
-- [ ] Cancelling a PENDING change request removes it from the pending list
+- [ ] A governed write returns 202 and a change request appears via `GET /iga/change-requests?status=PENDING`
+- [ ] `POST .../{id}/authorize` records an approval (409 if the same admin re-signs)
+- [ ] In Tide MultiAdmin mode, the `approval-model` enclave exchange completes and increments `authCount`
+- [ ] Committing a ready CR (`readyToCommit`) applies the change (APPROVED); 412 while under threshold
+- [ ] `POST .../{id}/deny` removes it from the pending list (DENIED)
 
 ### Endpoints
 
-- [ ] `GET .../counts` returns correct totals matching the full request list
-- [ ] `GET .../all/requests` returns all change types (user, role, client, group)
-- [ ] `POST .../sign/batch` accepts an array and processes all items
-- [ ] `POST .../commit/batch` and `POST .../cancel/batch` work with arrays
-- [ ] `POST /tideAdminResources/add-review` accepts the enclave-signed payload
-- [ ] `POST /tideAdminResources/add-rejection` rejects and sets status to DENIED
-- [ ] `GET .../{id}/activity` returns audit trail with timestamps
-- [ ] `POST .../{id}/comments` persists and appears in activity
+- [ ] `GET /iga/change-requests?status=PENDING` returns all pending CRs across types
+- [ ] `POST /iga/change-requests/{id}/authorize` records the approval
+- [ ] `POST /iga/change-requests/bulk-authorize` authorizes a batch (429 if a bulk run is active)
+- [ ] `POST /iga/change-requests/{id}/commit` applies the change; 412 under threshold
+- [ ] `POST /iga/change-requests/{id}/deny` sets status to DENIED
+- [ ] `GET/POST /iga/change-requests/{id}/comments` persist and read back
+- [ ] `POST /tideAdminResources/add-review` and `/add-rejection` return `410 Gone` (deprecated — do not use)
 
 ### Authorization
 
@@ -278,33 +230,33 @@ A working IGA admin panel must include:
 
 ## Common Failures
 
-### Sign Response Ignored in Multi-Admin Mode
+### Enclave Step Skipped in Tide MultiAdmin Mode
 
-**Symptom**: Approve button appears to succeed but change request stays in PENDING.
+**Symptom**: Approve appears to succeed but the change request stays in PENDING and `authCount` does not increase.
 
-**Cause**: The `requiresApprovalPopup` flag was not checked. In multi-admin mode, signing returns a challenge that must be completed through the Tide enclave.
+**Cause**: In Tide MultiAdmin mode, a bare `authorize` is not enough — the admin must sign the enclave challenge via the two-phase `approval-model` exchange.
 
-**Fix**: After calling `sign/batch`, check `response[0].requiresApprovalPopup`. If `true`, decode `changeSetDraftRequests`, present the enclave iframe, and submit the signed result via `POST /tideAdminResources/add-review`.
+**Fix**: `GET /iga/change-requests/{id}/approval-model`, decode `requestModel`, sign it in the Tide enclave, then `POST /iga/change-requests/{id}/approval-model` with `{ "requestModel": "<base64 doken>" }`. (FirstAdmin/Tideless mode signs server-side on `authorize` — no enclave step.)
 
 ---
 
-### Committing Before Enough Approvals
+### Committing Before Enough Approvals (412)
 
-**Symptom**: `POST .../commit/batch` returns an error or silently fails.
+**Symptom**: `POST /iga/change-requests/{id}/commit` returns **412 Precondition Failed**.
 
-**Cause**: The change request has not reached APPROVED status. Quorum threshold not met.
+**Cause**: The CR is under threshold, or a dependency has not committed yet.
 
-**Fix**: Check the status before committing. Only commit change requests with status `APPROVED`. If still `PENDING`, more admin approvals are needed.
+**Fix**: Only commit CRs where `readyToCommit === true`. If still short, collect more approvals; if `blocked`, commit the CR named in `dependsOn` first (see the commit-in-passes loop in `canon/iga-change-requests-api.md`).
 
 ---
 
-### Wrong ChangeSetType in Payload
+### Re-signing the Same CR (409)
 
-**Symptom**: 400 Bad Request or unexpected behavior when signing/committing.
+**Symptom**: `POST /iga/change-requests/{id}/authorize` returns **409 Conflict**.
 
-**Cause**: The `changeSetType` in the request body does not match the actual type of the draft record.
+**Cause**: Four-eyes enforcement — the same admin cannot sign a CR twice, or the CR is no longer PENDING.
 
-**Fix**: Read the `changeSetType` from the `GET .../all/requests` response and pass it back exactly. Do not hardcode a type.
+**Fix**: Have a *different* admin authorize, or refresh the list; do not retry the same admin's signature.
 
 ---
 
@@ -314,31 +266,21 @@ A working IGA admin panel must include:
 
 **Cause**: Admin token not included or expired.
 
-**Fix**: Obtain a fresh admin token before each batch of calls. If using `KcAdminClient`, call `client.auth(...)` and handle token refresh.
-
----
-
-### Rejection Silently Fails
-
-**Symptom**: Clicking "Reject" appears to succeed, but the change request stays in PENDING. No error returned.
-
-**Cause**: The rejection endpoint (`POST /tideAdminResources/add-rejection`) expects `multipart/form-data`. If you send `Content-Type: application/json`, the server accepts the request but ignores the payload fields.
-
-**Fix**: Use `FormData`, not `JSON.stringify`. Do not set `Content-Type` manually — the browser sets the correct multipart boundary automatically. See the code example in the Endpoints section above.
+**Fix**: Obtain a fresh admin token before each batch of calls and handle token refresh.
 
 ---
 
-### Counts Out of Sync with List
+### Calling a Deprecated add-review / add-rejection Endpoint
 
-**Symptom**: Dashboard badge shows a different number than the actual list.
+**Symptom**: `POST /tideAdminResources/add-review` or `/add-rejection` returns `410 Gone`.
 
-**Cause**: `GET .../counts` and `GET .../all/requests` called at different times; a change was created or committed between calls.
+**Cause**: Both endpoints were removed in the IGA decoupling. They are no longer functional.
 
-**Fix**: Refresh counts after any mutation (sign, commit, cancel). Do not cache counts across operations.
+**Fix**: Approve via `POST /iga/change-requests/{id}/authorize` (passing the enclave-signed approval in the body) and reject via `POST /iga/change-requests/{id}/deny`.
 
 ---
 
 ## References
 
-- Source: `sources/docs/CHANGE_REQUEST_API.md` (normative), operational exemplars (keylessh, forseti-crypto-quickstart, tidecloak-test-cases)
-- Content-type asymmetry confirmed by: CHANGE_REQUEST_API.md, forseti-crypto-quickstart `tidecloakApi.ts` (uses FormData for `add-review`)
+- Current surface: `IgaAdminResource` (`tidecloak-iga-extensions` iga-core) — `/iga/change-requests/*`, `/iga/forseti-contracts`, `/iga/role-policies`.
+- Legacy bootstrap-compat surface: `/tide-admin/change-set/*`, still used by `localtest/init/init_tidecloak.sh` and the `tidecloak-js` `AdminAPI` client.

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

@@ -21,7 +21,26 @@ Complete guide to implementing server-side JWT verification for Tide.
 
 ---
 
-## Complete Implementation
+## Recommended First: the Shipped `verifyTideCloakToken` Helper
+
+Before hand-rolling anything, know that Tide ships a one-call verifier. `@tidecloak/verify` exports `verifyTideCloakToken`, re-exported via `@tidecloak/nextjs/server`:
+
+```typescript
+import { verifyTideCloakToken } from '@tidecloak/nextjs/server'; // or '@tidecloak/verify'
+import tcConfig from '../data/tidecloak.json';
+
+// Arg order: (config, token, allowedRoles=[]) — config FIRST.
+const payload = await verifyTideCloakToken(tcConfig, token, ['admin']);
+// payload = decoded claims on success, `false` on any failure.
+```
+
+It does local-JWKS signature verification (embedded `jwk`), issuer + `azp` validation, time-claim checks with `clockTolerance`, and optional role enforcement across realm and client roles. For the majority of API-protection needs this is all you require — see [protect-api-nextjs.md](protect-api-nextjs.md).
+
+The complete manual implementation below is the **"under the hood" alternative**. Reach for it when you need something `verifyTideCloakToken` does not do: app-side DPoP proof re-verification, distinct 401 vs 403 responses, `iat` future-dating rejection, or an Express integration.
+
+---
+
+## Complete Implementation (Manual)
 
 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.
 

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

@@ -48,7 +48,7 @@ Copy-paste this prompt to an AI coding agent to scaffold a customer portal with
 > **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.
+> 1. Run `npm view @tidecloak/nextjs version` to get the current stable version. Pin it exactly (e.g., `"0.13.33"`). 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.

package/prompts/security-gap-analysis.md

@@ -0,0 +1,55 @@
+# Prompt: Security Gap Analysis of an Existing System
+
+Copy-paste this to an AI coding agent to audit an existing application for identity, key-management, authorization, and data-exposure gaps — and map each gap to the Tide capability that removes it. Works on systems with no Tide involvement at all.
+
+This is an **advisory, read-only** analysis. It does not modify the target.
+
+---
+
+## The Prompt
+
+> Perform a security gap analysis of this system. You are acting as the **Security Analyst** role from the Tide agent pack. Do not modify any code. Produce a report; do not begin remediation until I approve it.
+>
+> **First, confirm scope**: state exactly what you will inspect (repo, running instance, config) and that this is my own system or an authorized engagement. Read-only.
+>
+> **Load the doctrine**: read `canon/security-gap-mapping.md` (the SG-01 … SG-18 gap table) and `skills/tide-security-analyst/SKILL.md`. If you have the Tide MCP server, call `tide_security_analysis` to load them at once.
+>
+> **Two tiers**: run the **static** sweep (code/config/schema) always. Only run the **runtime confirmation** tier — sending live probes to confirm findings — if I confirm I own or am authorized to test the target, and then strictly per `canon/security-runtime-probes.md` (non-destructive, no exploitation, my own test account only). If I have not authorized live testing, stay static-only and keep findings tagged INFERRED.
+>
+> **Inventory the trust architecture first** (before pattern-matching), answering from the code/config:
+> 1. Identity — how are users authenticated, where do credentials live?
+> 2. Authority — how are tokens/sessions signed, who holds the signing key?
+> 3. Authorization — where is the access decision made: client, server, or both?
+> 4. Data — what sensitive data exists, and who can read it in the clear?
+>
+> **Run the full gap sweep**: work through SG-01 … SG-12 exhaustively. For each, run the detection commands from `canon/security-gap-mapping.md` against the target and record hits. Do NOT sample APIs (SG-05) — enumerate every route and diff against the routes that actually verify. Also collect anything matching the "Out of scope" table.
+>
+> **Every finding must have**:
+> - A named **trust concentration** — the single party or artifact that, once compromised, defeats the control. "Uses passwords" is not a finding; "password verification collapses to one database + one server process" is.
+> - **Evidence** — a file:line, config value, schema column, or HTTP observation — tagged VERIFIED (observed), INFERRED (implied by code), or ASSUMED (my statement, unconfirmed).
+> - A **severity** (CRITICAL / HIGH / MEDIUM / INFO) based on blast radius under a single compromise.
+> - The **Tide replacement**, cited from `canon/feature-mapping.md` or `canon/invariants.md`, with its sourcing tag.
+> - The **remediation playbook sequence** (verify each playbook exists via `tide_list playbooks`).
+> - The **limits** — the honesty note: what the Tide replacement does NOT cover.
+>
+> **Be honest**: include a non-empty "Not Addressed by Tide" section for anything you find that Tide doesn't fix (injection, XSS, CSRF, vulnerable dependencies, rate limiting, infra hardening). Never present Tide as fixing these. An honest analysis is more credible than an inflated one.
+>
+> **Report in the format** defined in `skills/tide-security-analyst/SKILL.md` (Report Format section): trust-architecture summary, findings most-severe-first, gap interactions, out-of-scope section, then a recommended remediation sequence with the execution role to engage first (per I-18).
+>
+> **Do not**: modify code, run TideCloak bootstrap, install the SDK, or start fixing anything. Report only. When I approve findings, hand off to the execution roles (Setup → Application → Security → IAM/Policy → Reviewer).
+
+---
+
+## Acceptance Criteria
+
+- [ ] Scope and authorization confirmed before inspection
+- [ ] Trust architecture (identity / authority / authorization / data) documented
+- [ ] All of SG-01 … SG-18 checked, not sampled (or non-applicability stated per SG)
+- [ ] Every finding names a trust concentration and carries evidence with a confidence tag
+- [ ] Runtime tier run only if authorized; probed findings carry a Runtime confirmation line; unprobed findings stay INFERRED
+- [ ] Every Tide-replacement claim cites `canon/feature-mapping.md` or `canon/invariants.md`
+- [ ] Every remediation names a playbook that exists in `playbooks/`
+- [ ] Non-empty "Not Addressed by Tide" section (or explicit "none found in scope")
+- [ ] No finding claims Tide fixes an out-of-scope gap class
+- [ ] Remediation sequence provided with first execution role named
+- [ ] No code was modified; the analysis is read-only

package/reference-apps/encrypted-communication/anti-patterns.md

@@ -10,7 +10,7 @@ Scenario-specific mistakes for encrypted communication apps using the hybrid Tid
 
 **Why it fails**: The private key is the root of trust for all E2E operations. If stored in plaintext, a database breach or XSS attack exposes all encrypted communications.
 
-**Fix**: Always encrypt the private key with `doEncrypt(privateKeyBytes, tag)` before storing. Always decrypt with `doDecrypt()` on login. Never persist the decrypted private key outside of in-memory variables.
+**Fix**: Always encrypt the private key with `doEncrypt([{ data: privateKeyBytes, tags: [tag] }])` before storing. Always decrypt with `doDecrypt()` on login. Never persist the decrypted private key outside of in-memory variables.
 
 ---
 
@@ -118,6 +118,6 @@ Scenario-specific mistakes for encrypted communication apps using the hybrid Tid
 
 **Mistake**: Installing a 0.99.x pre-release version of the Tide SDK.
 
-**Why it fails**: 0.99.x versions are unstable pre-releases. The stable version is 0.13.26 (per pack version policy).
+**Why it fails**: 0.99.x versions are unstable pre-releases. The stable version is 0.13.33 (per pack version policy).
 
-**Fix**: Pin `@tidecloak/react` to `0.13.26`. See `canon/version-policy.md`.
+**Fix**: Pin `@tidecloak/react` to `0.13.33`. See `canon/version-policy.md`.

package/reference-apps/encrypted-communication/bootstrap-sequence.md

@@ -117,12 +117,12 @@
 
 23. Implement first-login flow:
     - Generate keypair client-side
-    - Encrypt private key with `doEncrypt(privateKeyBytes, tag)`
+    - Encrypt private key with `doEncrypt([{ data: privateKeyBytes, tags: [tag] }])`
     - Store encrypted private key + public key via protected API
 
 24. Implement returning-login flow:
     - Fetch encrypted key material via protected API
-    - Decrypt private key with `doDecrypt(encryptedPrivateKey, tag)`
+    - Decrypt private key with `doDecrypt([{ encrypted: encryptedPrivateKey, tags: [tag] }])`
     - Private key available in memory for runtime E2E operations
 
 25. Implement runtime E2E operations using the external crypto library (not Tide).

package/reference-apps/encrypted-communication/scenario.md

@@ -77,14 +77,14 @@ On **first login** for a new user:
 1. User authenticates via TideCloak SSO
 2. App checks database for existing encrypted key material
 3. No keys found → app generates a new asymmetric keypair client-side (e.g., `crypto_box_keypair()`)
-4. App encrypts the private key using `doEncrypt(privateKeyBytes, tag)` (Tide self-encryption)
+4. App encrypts the private key using `doEncrypt([{ data: privateKeyBytes, tags: [tag] }])` (Tide self-encryption)
 5. App stores the encrypted private key and the public key in the database via a protected API endpoint
 6. Private key is now available in memory for runtime E2E operations
 
 On **returning login**:
 1. User authenticates via TideCloak SSO
 2. App fetches encrypted key material from database
-3. App decrypts the private key using `doDecrypt(encryptedPrivateKey, tag)` (Tide self-encryption)
+3. App decrypts the private key using `doDecrypt([{ encrypted: encryptedPrivateKey, tags: [tag] }])` (Tide self-encryption)
 4. Private key is now available in memory for runtime E2E operations
 
 **Runtime E2E operations** (not Tide — handled by external crypto library):

package/reference-apps/git-pr-signing-service/bootstrap-sequence.md

@@ -27,11 +27,11 @@ All steps must complete before the service can sign merge commits. Order matters
    - `POST /admin/realms/{realm}/tide-admin/toggle-iga` with form-urlencoded `isIGAEnabled=true`.
    - Must happen after licensing.
 
-## Phase 3: Approve initial change-sets
+## Phase 3: Approve initial change requests
 
-6. **Approve client change-sets**
-   - List: `GET /admin/realms/{realm}/tide-admin/change-set/clients/requests`.
-   - For each: sign (`POST .../change-set/sign`) then commit (`POST .../change-set/commit`).
+6. **Approve initial change requests** (current `/iga/change-requests/...` surface — see `canon/iga-change-requests-api.md`)
+   - List: `GET /admin/realms/{realm}/iga/change-requests?status=PENDING` (objects keyed by `id`).
+   - Approve: `POST .../iga/change-requests/bulk-authorize` (`{"actionTypeIn":["CREATE","DELETE"],"limit":100}`), then `POST .../iga/change-requests/{id}/commit` for each `readyToCommit` CR. FirstAdmin bootstrap signs server-side.
 
 ## Phase 4: Admin user setup
 
@@ -50,11 +50,11 @@ All steps must complete before the service can sign merge commits. Order matters
 10. **Wait for account linking**
     - Poll `GET /admin/realms/{realm}/users/{userId}` until `attributes.tideUserKey` and `attributes.vuid` are present for each admin.
 
-## Phase 5: Approve user change-sets
+## Phase 5: Approve user change requests
 
-11. **Approve user change-sets**
-    - List: `GET /admin/realms/{realm}/tide-admin/change-set/users/requests`.
-    - For each: sign then commit.
+11. **Approve user change requests**
+    - List: `GET /admin/realms/{realm}/iga/change-requests?status=PENDING`.
+    - Authorize then commit (see Phase 3 / `canon/iga-change-requests-api.md`).
 
 ## Phase 6: IDP settings and adapter export