@tideorg/mcp 1.4.1 → 1.9.0

package/playbooks/setup-forseti-e2ee.md

@@ -289,24 +289,27 @@ const executeTideRequest = async (request, waitForAll = false) => {
 WRONG:  GET /admin/realms/{realm}/tide-admin/realm-policy
         -> { status: "none" } (even when the policy exists)
 
-CORRECT: GET /realms/{realm}/tide-policy-resources/admin-policy
-         -> base64-encoded bytes (public, no auth required)
+WRONG:  GET /realms/{realm}/tide-policy-resources/admin-policy
+        -> does NOT exist on current main (the public policy endpoint was removed)
+
+CORRECT: GET /admin/realms/{realm}/iga/role-policies   (admin bearer required)
+         -> JSON; the signed admin policy bytes are in the `policy` field
 ```
 
-The correct endpoint does not require master admin credentials. Proxy through your backend.
+The correct endpoint is an admin API route and **requires an admin bearer token**. Proxy through your backend so the browser never holds the admin credential.
 
-**CORS: Browser cannot fetch this endpoint directly.** TideCloak and the app are on different origins. Direct browser fetch returns an opaque/blocked response. Create a same-origin API route that proxies the request server-side. VERIFIED (session-001).
+**CORS: Browser cannot fetch this endpoint directly.** TideCloak and the app are on different origins, and this is a privileged admin API. Direct browser fetch returns an opaque/blocked response (and would leak the admin bearer). Create a same-origin API route that proxies the request server-side with the admin token. VERIFIED (session-001).
 
 **If the proxy route is protected with `withAuth` (correct per I-03), the client must use authenticated fetch** (e.g., `appFetch` or `secureFetch` with Bearer header). A bare `fetch()` without Authorization returns 401. The resulting empty/error response produces undefined policy bytes, causing `PolicyAuthorizationFlowException: "Model does not have a policy passed with it"` at signing time. VERIFIED (LEARNINGS-batch-009 L-08).
 
 **There is no REST API for deploying Forseti contracts.** Do not try `PUT` or `POST` to `/tide-admin/forseti-contracts` — these endpoints do not exist on the dev image (404/405). Contract deployment happens via `PolicySignRequest.addForsetiContractToUpload(contractSource)` in the browser signing flow (Step 4). VERIFIED (session-001).
 
-**The response is base64-encoded, not raw binary.** You must decode before using:
+**The signed bytes arrive as a base64 string in the `policy` field, not raw binary.** Read the `policy` field and decode before using:
 
 ```js
-// Backend proxy
-const b64 = await tcRes.text();
-const raw = Buffer.from(b64, "base64");
+// Backend proxy (holds the admin bearer)
+const json = await tcRes.json();
+const raw = Buffer.from(json.policy, "base64");
 const bytes = Array.from(new Uint8Array(raw));
 res.json({ policyBytes: bytes });
 
@@ -315,12 +318,12 @@ const data = await res.json();
 const adminPolicyBytes = new Uint8Array(data.policyBytes);
 ```
 
-**Common mistake:** Treating the base64 string as raw bytes (passing each character's char code as a byte value). If admin policy bytes start with `[65, 81, 65, 65, ...]` (ASCII for "AQAA..."), you are passing base64 text as byte values instead of decoding it. The ORK will fail with `Index out of range` because the policy structure is garbage.
+**Common mistake:** Treating the base64 `policy` string as raw bytes (passing each character's char code as a byte value). If admin policy bytes start with `[65, 81, 65, 65, ...]` (ASCII for "AQAA..."), you are passing base64 text as byte values instead of decoding it. The ORK will fail with `Index out of range` because the policy structure is garbage.
 
-**Common mistake:** Malformed URL from trailing slash in `auth-server-url`. The adapter JSON `auth-server-url` may include a trailing slash (e.g., `http://localhost:8080/`). Constructing the admin policy URL without stripping it produces `http://localhost:8080//realms/...` (double slash), which returns HTML or 404 instead of policy bytes. Always normalize:
+**Common mistake:** Malformed URL from trailing slash in `auth-server-url`. The adapter JSON `auth-server-url` may include a trailing slash (e.g., `http://localhost:8080/`). Constructing the admin policy URL without stripping it produces `http://localhost:8080//admin/realms/...` (double slash), which returns HTML or 404 instead of policy bytes. Always normalize:
 ```js
 const baseUrl = config["auth-server-url"].replace(/\/+$/, "");
-const adminPolicyUrl = `${baseUrl}/realms/${config.realm}/tide-policy-resources/admin-policy`;
+const adminPolicyUrl = `${baseUrl}/admin/realms/${config.realm}/iga/role-policies`;
 ```
 
 ---
@@ -528,50 +531,29 @@ These are prep steps. None produce VVK-signed bytes.
 
 Role assignments that produce VVK-signed UserContexts MUST be manually approved through the approval enclave in the admin's browser. You cannot automate this from a backend script.
 
-What happens when you try to auto-approve:
-
-```
-POST /tide-admin/change-set/sign
-Response: { "requiresApprovalPopup": true, "changeSetDraftRequests": "base64..." }
-```
-
-The `requiresApprovalPopup: true` response means the backend CANNOT complete the signing. The VVK-signed UserContext binds a specific user's `tideUserKey` to specific roles. This signing must happen through the ORK threshold network via the Tide enclave running in the admin's browser.
-
-**Always use `/batch` endpoints for approval:**
+This is Tide MultiAdmin mode: the VVK-signed UserContext binds a specific user's `tideUserKey` to specific roles, and the signing must happen through the ORK threshold network via the Tide enclave in the admin's browser. The backend CANNOT complete it — a bare `authorize` on such a CR requires the two-phase `approval-model` enclave exchange. (Endpoints: current `/iga/change-requests/...` surface — see `canon/iga-change-requests-api.md`.)
 
 ```js
-// 1. Backend creates IGA draft (role assignment)
+// 1. Backend performs the governed change (role assignment) → 202, a CR is created
 POST /admin/realms/{realm}/users/{userId}/role-mappings/realm
 
-// 2. Frontend fetches pending requests
-GET /admin/realms/{realm}/tide-admin/change-set/users/requests
+// 2. Frontend fetches pending CRs
+GET /admin/realms/{realm}/iga/change-requests?status=PENDING   // objects keyed by `id`
 
-// 3. Frontend calls sign/batch (one call for all selected)
-POST /admin/realms/{realm}/tide-admin/change-set/sign/batch
-{ changeSets: [{ changeSetId, changeSetType, actionType, policyRoleId? }] }
+// 3. For each CR, fetch the enclave challenge (Tide MultiAdmin)
+GET /admin/realms/{realm}/iga/change-requests/{id}/approval-model
+//   → { changeRequestId, requestModel: "base64..." }
 
-// 4. Collect all that need enclave, pass to ONE approval popup
-const enclaveRequests = results
-  .filter(r => r.requiresApprovalPopup)
-  .map(r => ({ id: r.changesetId, request: base64ToBytes(r.changeSetDraftRequests) }));
+// 4. Collect the challenges, pass to ONE enclave approval popup
+const enclaveRequests = pending.map(cr => ({ id: cr.id, request: base64ToBytes(cr.requestModel) }));
 const approvals = await tc.requestTideOperatorApproval(enclaveRequests);
 
-// 5. Submit each signed review via add-review (FormData, NOT JSON)
-POST /admin/realms/{realm}/tideAdminResources/add-review
-
-// 6. Commit all in batch
-POST /admin/realms/{realm}/tide-admin/change-set/commit/batch
-{ changeSets: [{ changeSetId, changeSetType, actionType }] }
-```
+// 5. Submit each signed doken back to the same endpoint
+POST /admin/realms/{realm}/iga/change-requests/{id}/approval-model
+{ "requestModel": "<base64 doken>" }   // → { recorded, authCount, threshold }
 
-**The add-review endpoint uses FormData, not JSON:**
-
-```js
-const formData = new FormData();
-formData.append("changeSetId", id);
-formData.append("actionType", actionType);
-formData.append("changeSetType", changeSetType);
-formData.append("requests", btoa(String.fromCharCode(...signedBytes)));
+// 6. Commit each CR once ready (readyToCommit === true)
+POST /admin/realms/{realm}/iga/change-requests/{id}/commit   // 412 if still under threshold
 ```
 
 After commit: the user must refresh their token (or re-login) for the new role to appear in their doken. Use `IAMService.forceUpdateToken()` or `useTideCloak().forceRefreshToken()`.
@@ -656,8 +638,8 @@ The forseti-crypto-quickstart is the reference implementation that works against
 - [ ] `modelId` is `["PolicyEnabledEncryption:1", "PolicyEnabledDecryption:1"]` (array, not string)
 - [ ] `PolicySignRequest` imported from `heimdall-tide`
 - [ ] `BaseTideRequest.decode()` called on `createTideRequest` result before approval
-- [ ] Admin policy fetched from `GET /realms/{realm}/tide-policy-resources/admin-policy` (not the admin API endpoint)
-- [ ] Admin policy bytes are base64-decoded (not raw char codes)
+- [ ] Admin policy fetched (admin bearer) from `GET /admin/realms/{realm}/iga/role-policies`; signed bytes read from the `policy` field (the public `tide-policy-resources/admin-policy` endpoint does not exist on main)
+- [ ] Admin policy bytes are base64-decoded from the `policy` field (not raw char codes)
 - [ ] Approval popup opens and admin approves
 - [ ] `executeSignRequest` called with `waitForAll = true`
 - [ ] `policy.signature = signatures[0]` assigned before `policy.toBytes()`
@@ -701,8 +683,8 @@ The forseti-crypto-quickstart is the reference implementation that works against
 
 ### `{ status: "none" }` when fetching admin policy
 
-**Cause:** Using the wrong endpoint `GET /admin/realms/{realm}/tide-admin/realm-policy`.
-**Fix:** Use `GET /realms/{realm}/tide-policy-resources/admin-policy`.
+**Cause:** Using the wrong endpoint `GET /admin/realms/{realm}/tide-admin/realm-policy`. (The old public `GET /realms/{realm}/tide-policy-resources/admin-policy` endpoint no longer exists on main either.)
+**Fix:** Use `GET /admin/realms/{realm}/iga/role-policies` with an admin bearer token and read the signed bytes from the `policy` field.
 
 ### Admin policy bytes start with `[65, 81, 65, 65, ...]`
 

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.