@tideorg/mcp 1.4.1 → 1.9.0

package/canon/anti-patterns.md

@@ -112,7 +112,7 @@ const keyPair = await crypto.subtle.generateKey(
 **Correct approach**:
 ```typescript
 // ✅ CORRECT: Delegate to SDK/Fabric
-const ciphertext = await iam.doEncrypt('tag', plaintext);
+const ciphertext = await iam.doEncrypt([{ data: plaintext, tags: ['tag'] }]);
 const signature = await tc.executeSignRequest(signRequest);
 
 // Keys never exist locally; operations use Fabric threshold protocols
@@ -133,7 +133,7 @@ async function offlineDecrypt(ciphertext) {
   if (!navigator.onLine && cachedSessionKey) {
     return decryptLocally(ciphertext, cachedSessionKey);
   }
-  return iam.doDecrypt('tag', ciphertext);
+  return iam.doDecrypt([{ encrypted: ciphertext, tags: ['tag'] }]);
 }
 ```
 
@@ -152,7 +152,7 @@ async function decrypt(ciphertext) {
   if (!navigator.onLine) {
     throw new Error('E2EE requires online Fabric access');
   }
-  return iam.doDecrypt('tag', ciphertext);
+  return iam.doDecrypt([{ encrypted: ciphertext, tags: ['tag'] }]);
 }
 
 // Handle offline state at application level, not E2EE level
@@ -206,8 +206,8 @@ app.post('/api/admin/create-user', async (req, res) => {
     body: JSON.stringify(req.body)
   });
 
-  // Admin must then approve via /tide-admin/change-set/sign/batch
-  // and commit via /tide-admin/change-set/commit/batch
+  // Admin must then approve via /iga/change-requests/{id}/authorize
+  // and commit via /iga/change-requests/{id}/commit (canon/iga-change-requests-api.md)
   return res.json({ status: 'pending_approval' });
 });
 
@@ -254,7 +254,7 @@ app.get('/api/protected', async (req, res) => {
 });
 ```
 
-**Note**: DPoP is required for Tide's full security guarantees **VERIFIED** (vendor confirmation, GAP-032 resolved). ES256 is the default algorithm; EdDSA also supported.
+**Note**: DPoP is not merely "supported" — it is **ENABLED and ENFORCED by default** in the TideCloak SDK (`useDPoP` defaults to `{ mode: 'strict' }`). Treat DPoP as on unless it has been explicitly disabled (`useDPoP: false`). Skipping server-side DPoP handling when the SDK default is in force will break every request. ES256 is the default algorithm; EdDSA also supported. **VERIFIED** (`tidecloak-js: packages/tidecloak-js/src/IAMService.js`).
 
 **Related**: Invariants I-12, [Concepts](concepts.md#dpop-demonstration-of-proof-of-possession)
 
@@ -412,16 +412,13 @@ if (checkSSHPolicy(currentUser, targetServer)) {
 
 **Correct approach**:
 ```typescript
-// ✅ CORRECT: Submit contract to Fabric for distributed execution
-const signRequest = await tc.createTideRequest({
-  contract: sshPolicyContract,  // C# code executed on every ORK
-  modelName: 'DynamicApprovedCustom<SSH>:DynamicApprovedCustom<1>',
-  authFlow: 'Policy:1',
-  authorizer: tc.doken,
-  challengeData: { user: currentUser, destination: targetServer }
-});
+// ✅ CORRECT: Submit contract to Fabric for distributed execution.
+// createTideRequest takes a single pre-encoded Uint8Array (a BaseTideRequest),
+// NOT an object literal. Build the request, encode it, then submit (see AP-53).
+const request = new BaseTideRequest(name, version, 'Policy:1', draft); // draft carries the C# contract
+const initializedBytes = await tc.createTideRequest(request.encode());
 
-const result = await tc.executeSignRequest(signRequest);
+const result = await tc.executeSignRequest(initializedBytes);
 // ORKs have independently evaluated policy; majority approved or rejected
 ```
 
@@ -541,9 +538,10 @@ export async function appFetch(path: string, init?: RequestInit): Promise<Respon
 ```bash
 # ✅ CORRECT: Export Tide adapter with extensions
 curl -X GET \
-  "${TIDECLOAK_URL}/admin/realms/${REALM}/clients/${CLIENT_ID}/vendorResources/get-installations-provider?providerId=keycloak-oidc-keycloak-json" \
+  "${TIDECLOAK_URL}/admin/realms/${REALM}/vendorResources/get-installations-provider?clientId=${CLIENT_ID}&providerId=keycloak-oidc-keycloak-json" \
   -H "Authorization: Bearer ${ADMIN_TOKEN}" \
   > data/tidecloak.json
+# Note: realm-level endpoint; the client is a query param (clientId=), NOT a /clients/{id}/ path segment.
 
 # Verify Tide extensions present
 jq 'has("jwk") and has("vendorId") and has("homeOrkUrl")' data/tidecloak.json
@@ -742,7 +740,7 @@ const isAdmin = jwt.realm_access.roles.includes('admin');
 
 if (canEncryptSSN) {
   // Allow SSN encryption only
-  await iam.doEncrypt('ssn', plaintext);
+  await iam.doEncrypt([{ data: plaintext, tags: ['ssn'] }]);
 }
 
 if (isAdmin) {
@@ -816,12 +814,12 @@ if (claims.realm_access.roles.includes('admin')) {
 
 **Correct approach**:
 ```typescript
-// ✅ CORRECT: Always verify signature against embedded JWKS
-import TideJWT from "@tidecloak/verify";
-const _mod = (TideJWT as any)?.default ?? TideJWT;
-const { verifyTideCloakToken } = _mod;
+// ✅ CORRECT: Always verify signature against embedded JWKS.
+// Named import works (the package ships dual CJS/ESM exports on current versions).
+import { verifyTideCloakToken } from "@tidecloak/verify";
 
-const verified = await verifyTideCloakToken(token, tidecloakConfig);
+// Argument order is (config, token, allowedRoles?) — CONFIG FIRST, then the token.
+const verified = await verifyTideCloakToken(tidecloakConfig, token);
 // Only trust claims from verified token
 ```
 
@@ -883,7 +881,7 @@ app.get('/api/records/:id', async (req, res) => {
 **Correct approach**:
 ```typescript
 // ✅ CORRECT: Decrypt only in the browser via SDK
-const plaintext = await iam.doDecrypt('medical', ciphertext);
+const plaintext = await iam.doDecrypt([{ encrypted: ciphertext, tags: ['medical'] }]);
 // Plaintext never leaves the browser
 // Server stores and serves only ciphertext
 ```
@@ -897,12 +895,12 @@ const plaintext = await iam.doDecrypt('medical', ciphertext);
 **What it looks like**:
 ```typescript
 // ❌ WRONG: No tag
-const encrypted = await iam.doEncrypt('', plaintext);
+const encrypted = await iam.doEncrypt([{ data: plaintext, tags: [] }]);
 
 // ❌ WRONG: Same tag for everything
-const encSSN = await iam.doEncrypt('data', ssn);
-const encMedical = await iam.doEncrypt('data', medicalRecord);
-const encNotes = await iam.doEncrypt('data', internalNotes);
+const encSSN = await iam.doEncrypt([{ data: ssn, tags: ['data'] }]);
+const encMedical = await iam.doEncrypt([{ data: medicalRecord, tags: ['data'] }]);
+const encNotes = await iam.doEncrypt([{ data: internalNotes, tags: ['data'] }]);
 ```
 
 **Why it's wrong**:
@@ -916,9 +914,9 @@ const encNotes = await iam.doEncrypt('data', internalNotes);
 **Correct approach**:
 ```typescript
 // ✅ CORRECT: Meaningful tags per sensitivity level
-const encSSN = await iam.doEncrypt('ssn', ssn);           // _tide_ssn.selfdecrypt
-const encMedical = await iam.doEncrypt('medical', record); // _tide_medical.selfdecrypt
-const encNotes = await iam.doEncrypt('notes', notes);      // _tide_notes.selfdecrypt
+const encSSN = await iam.doEncrypt([{ data: ssn, tags: ['ssn'] }]);           // _tide_ssn.selfdecrypt
+const encMedical = await iam.doEncrypt([{ data: record, tags: ['medical'] }]); // _tide_medical.selfdecrypt
+const encNotes = await iam.doEncrypt([{ data: notes, tags: ['notes'] }]);      // _tide_notes.selfdecrypt
 // Each tag has separate encrypt/decrypt roles with different user assignments
 ```
 
@@ -932,11 +930,11 @@ const encNotes = await iam.doEncrypt('notes', notes);      // _tide_notes.selfde
 ```typescript
 // ❌ WRONG: Encrypt with doEncrypt, expect other users to doDecrypt
 // User A encrypts
-const ciphertext = await iam.doEncrypt('shared', data);
+const ciphertext = await iam.doEncrypt([{ data, tags: ['shared'] }]);
 await api.saveSharedDoc(ciphertext);
 
 // User B tries to decrypt (FAILS even with _tide_shared.selfdecrypt role)
-const plaintext = await iam.doDecrypt('shared', ciphertext);
+const plaintext = await iam.doDecrypt([{ encrypted: ciphertext, tags: ['shared'] }]);
 ```
 
 **Why it's wrong**:
@@ -962,9 +960,10 @@ const ciphertext = await iam.doEncrypt(data, signedPolicyBytes);
 
 **What it looks like**:
 ```csharp
-// ❌ WRONG: Checking voucher gate role in contract
-public override bool ValidateExecutor(UserContext user) {
-    return user.HasRole("_tide_medical.selfdecrypt");
+// ❌ WRONG: Checking voucher gate role in contract (also: role lives on the doken, not a "user")
+public PolicyDecision ValidateExecutor(ExecutorContext ctx) {
+    return ctx.Doken.HasRole("_tide_medical.selfdecrypt")
+        ? PolicyDecision.Allow() : PolicyDecision.Deny("no");
 }
 ```
 
@@ -978,9 +977,11 @@ public override bool ValidateExecutor(UserContext user) {
 
 **Correct approach**:
 ```csharp
-// ✅ CORRECT: Check a regular realm role
-public override bool ValidateExecutor(UserContext user) {
-    return user.HasRole("shared-data-access");
+// ✅ CORRECT: Check a regular realm role on the executor's doken (DokenDto.HasRole),
+// not a "user" object. The role check target is the doken, per Ork.Forseti.Sdk.
+public PolicyDecision ValidateExecutor(ExecutorContext ctx) {
+    return ctx.Doken.HasRole("shared-data-access")
+        ? PolicyDecision.Allow() : PolicyDecision.Deny("not allowed");
 }
 // Voucher gate roles (_tide_*) are assigned separately to enable the ORK operation
 ```
@@ -1137,31 +1138,23 @@ if (useTideCloak().hasClientRole('tide-realm-admin', 'realm-management')) {
 
 ---
 
-## AP-30: Using Named ESM Imports with @tidecloak/verify
-
-**What it looks like**:
-```typescript
-// ❌ WRONG: Named ESM import from CJS package
-import { verifyTideCloakToken } from "@tidecloak/verify";
-// Error: does not provide an export named 'verifyTideCloakToken'
-```
-
-**Why it's wrong**:
-- `@tidecloak/verify` is a CJS package, not ESM
-- Named imports fail because CJS modules export a single `module.exports` object
-- CJS interop varies by runtime (tsx, node, bundlers wrap `.default` differently)
+## AP-30: (Resolved) @tidecloak/verify Import Style
 
-**Consequence**: Import error at startup. Server-side JWT verification completely broken.
+**Status**: The old CJS-only interop workaround is **no longer required** on current versions. `@tidecloak/verify` now ships a proper dual `exports` map (`import` → ESM, `require` → CJS), so a plain named import works in both ESM and CJS callers.
 
 **Correct approach**:
 ```typescript
-// ✅ CORRECT: Default import with CJS interop
-import TideJWT from "@tidecloak/verify";
-const _mod = (TideJWT as any)?.default ?? TideJWT;
-const { verifyTideCloakToken } = _mod;
+// ✅ CORRECT: Plain named import (works in ESM and CJS on current versions)
+import { verifyTideCloakToken } from "@tidecloak/verify";
+// CJS callers: const { verifyTideCloakToken } = require("@tidecloak/verify");
+
+// Argument order is (config, token, allowedRoles?) — config FIRST (see AP-20).
+const payload = await verifyTideCloakToken(tidecloakConfig, token);
 ```
 
-**Related**: AP-01
+Do NOT reintroduce the `const _mod = (TideJWT as any)?.default ?? TideJWT` dance — it targeted an older single-export build. If a named import genuinely fails, you are on a very old version; upgrade rather than adding interop shims.
+
+**Related**: AP-01, AP-20
 
 ---
 
@@ -1298,7 +1291,7 @@ volumes:
 ```bash
 # ❌ WRONG: Skip license activation, jump to IGA
 curl -X POST "$KC_URL/admin/realms" -d '{"realm":"myrealm","enabled":true}'
-curl -X POST "$KC_URL/admin/realms/myrealm/vendorResources/toggle-iga"
+curl -X POST "$KC_URL/admin/realms/myrealm/tide-admin/toggle-iga"
 # Missing: setUpTideRealm, approve/commit, user creation, invite link...
 ```
 
@@ -1313,9 +1306,9 @@ curl -X POST "$KC_URL/admin/realms/myrealm/vendorResources/toggle-iga"
 ```bash
 # ✅ CORRECT: Follow exact sequence
 # 1. Create realm
-# 2. POST /vendorResources/setUpTideRealm (with email)
-# 3. POST /vendorResources/toggle-iga
-# 4. Approve + commit client change requests
+# 2. POST /admin/realms/{realm}/vendorResources/setUpTideRealm (form-urlencoded, with email)
+# 3. POST /admin/realms/{realm}/tide-admin/toggle-iga   (NOT /vendorResources/toggle-iga)
+# 4. Approve + commit client change requests (iga/change-requests/{id}/authorize|commit)
 # 5. Create admin user + assign tide-realm-admin
 # 6. Generate invite link + wait for account linking
 # 7. Approve + commit user change requests
@@ -2054,7 +2047,7 @@ After `executeSignRequest`, the result is the VVK signature array. Do not store
 
 ## AP-56: Wrong Forseti Contract Namespace
 
-Do not use `using Tide.Ork.Classes.Forseti;` or `using Tide.Forseti;` — these namespaces do not exist. The correct namespace is `using Ork.Forseti.Sdk;`. The contract class must be named `Contract` and implement `IAccessPolicy`. Method signatures use context objects: `ValidateData(DataContext ctx)`, `ValidateApprovers(ApproversContext ctx)`, `ValidateExecutor(ExecutorContext ctx)`. Use `PolicyDecision.Allow()` not `PolicyDecision.Approve()`. VERIFIED (ripple-learnings L-13).
+Do not use `using Tide.Ork.Classes.Forseti;` or `using Tide.Forseti;` — these namespaces do not exist. The correct namespace is `using Ork.Forseti.Sdk;`. The contract class must implement `IAccessPolicy`; the class NAME is not fixed — the ORK resolves the entry type from the request's stored `EntryType` (`asm.GetType(req.EntryType)`), so `Contract` is only a convention, not a requirement. Method signatures use context objects: `ValidateData(DataContext ctx)` (always called), `ValidateApprovers(ApproversContext ctx)` (when approvalType == EXPLICIT), `ValidateExecutor(ExecutorContext ctx)` (when executorType == PRIVATE). Use `PolicyDecision.Allow()` not `PolicyDecision.Approve()`. VERIFIED (`ork: Ork.Forseti.Sdk/Contracts/IAccessPolicy.cs`, entry-type resolution in `Ork.Forseti.VmHost/Program.cs`).
 
 ---
 

package/canon/concepts.md

@@ -103,29 +103,28 @@ Agent-operable definitions of Tide's cryptographic model and architecture.
 
 **How it works**:
 1. Admin proposes change (create user, modify role, etc.) → draft created automatically for 18 specific admin API actions **VERIFIED** (vendor confirmation, GAP-041 resolved). Not every mutating endpoint creates a draft — many operations (updating user attributes, updating realm settings, creating groups, managing identity providers) execute immediately. Master realm and IGA-disabled realms are always exempt.
-2. Change-set enters approval queue with `draftRecordId`, `changeSetType`, `actionType`
+2. The change request enters the approval queue keyed by `id`, with `entityType`, `actionType`
 3. Required quorum of admins approve: `max(1, floor(TotalAdmins * 0.7))` **VERIFIED** (SetupIGA.md)
-4. Approved change is sealed by VVK threshold signatures (Authorization Proofing)
+4. Approved change is sealed by VVK threshold signatures (Authorization Proofing) — in Tide mode; Tideless mode records a username attestation (no crypto)
 5. Change is committed to realm
 6. VVK ORKs verify future JWT claims against these proofs
 
-**Change-set lifecycle** **VERIFIED** (CHANGE_REQUEST_API.md):
+**Change-request lifecycle** **VERIFIED** (qea-iga-api.md):
 ```
-DRAFT → PENDING → APPROVED → ACTIVE
-                → DENIED
-         (cancel at any stage)
+PENDING → APPROVED (committed) → (ACTIVE)
+        → DENIED
+        → CANCELLED
 ```
 
-**Change-set API endpoints** **VERIFIED** (CHANGE_REQUEST_API.md, all exemplar init scripts):
+**Change-request API endpoints** — current `/iga/change-requests/...` surface (replaces legacy `/tide-admin/change-set/...`, GAP-065). **Full spec: `canon/iga-change-requests-api.md`.**
 ```
-GET  /admin/realms/{realm}/tide-admin/change-set/counts                → lightweight counts
-GET  /admin/realms/{realm}/tide-admin/change-set/all/requests          → all change requests
-GET  /admin/realms/{realm}/tide-admin/change-set/{type}/requests       → by type (users, roles, clients, groups)
-POST /admin/realms/{realm}/tide-admin/change-set/sign/batch            → approve (sign)
-POST /admin/realms/{realm}/tide-admin/change-set/commit/batch          → commit approved changes
-POST /admin/realms/{realm}/tide-admin/change-set/cancel/batch          → cancel pending changes
-POST /admin/realms/{realm}/tideAdminResources/add-review               → submit enclave-signed review (multipart)
-POST /admin/realms/{realm}/tideAdminResources/add-rejection            → reject (multipart/form-data, NOT JSON)
+GET  /admin/realms/{realm}/iga/change-requests?status=PENDING          → list (objects keyed by id)
+GET  /admin/realms/{realm}/iga/change-requests/{id}                    → one change request
+POST /admin/realms/{realm}/iga/change-requests/{id}/authorize          → approve (sign), body {} optional
+POST /admin/realms/{realm}/iga/change-requests/bulk-authorize          → batch approve
+POST /admin/realms/{realm}/iga/change-requests/{id}/commit             → commit (412 if under threshold)
+POST /admin/realms/{realm}/iga/change-requests/{id}/deny               → reject
+GET/POST /admin/realms/{realm}/iga/change-requests/{id}/approval-model → Tide-mode enclave two-phase sign
 ```
 
 **Signing modes** **VERIFIED** (CHANGE_REQUEST_API.md):
@@ -154,11 +153,11 @@ POST /admin/realms/{realm}/tideAdminResources/add-rejection            → rejec
 **Official name**: "Hermetic E2EE" is marketing. Use "threshold E2EE".
 
 **How it works** **VERIFIED** (vendor confirmation, GAP-009 resolved):
-1. User calls `doEncrypt(tag, plaintext)` in browser
+1. User calls `doEncrypt([{ data: plaintext, tags: [tag] }])` in browser
 2. A fresh random encryption key is generated per call (<32B: fresh ElGamal scalar; >=32B: fresh 32-byte AES key via `crypto.getRandomValues()`). No key reuse across calls.
 3. Data encrypted locally; the per-call key is ElGamal-encrypted via threshold across ORKs
 4. Ciphertext (TideMemory envelope) stored in application
-5. User calls `doDecrypt(tag, ciphertext)` → Fabric threshold-decrypts the per-call key → plaintext recovered locally
+5. User calls `doDecrypt([{ encrypted: ciphertext, tags: [tag] }])` → Fabric threshold-decrypts the per-call key → plaintext recovered locally
 6. Separately, a session key (`t.ssk`) in the doken authenticates the user to ORKs but does NOT encrypt data. Lives in ORK enclave iframe; destroyed on tab close/logout. Adapters have no encryption key state to manage.
 
 **Tag-based role enforcement** **VERIFIED** (e2ee.md):
@@ -319,13 +318,17 @@ useDPoP: { mode: 'strict', alg: 'EdDSA' }
 
 **DPoP enablement**: DPoP is configured per-client in TideCloak via the client attribute `"dpop.bound.access.tokens": "true"`. This is NOT a realm-wide setting. **VERIFIED** (test-cases realm.json)
 
-**DPoP client SDK**: DPoP requires the `TideCloak` class (not `IAMService`) with `enableDpop: true` in init options:
+**DPoP client SDK**: DPoP is enabled and enforced by default across the TideCloak SDKs. Configure it via the `useDPoP` option (there is no `enableDpop` flag — that option does not exist in the current SDK). Use the `TideCloak` class (not `IAMService`) for the DPoP-signing client:
 ```typescript
 const tc = new TideCloak({ url, realm, clientId, vendorId, homeOrkUrl, ... });
-await tc.init({ onLoad: "check-sso", pkceMethod: "S256", enableDpop: true });
+// useDPoP defaults to { mode: 'strict' }; pass it explicitly to set alg or relax the mode:
+//   useDPoP: false                       → disable DPoP entirely
+//   useDPoP: { mode: 'auto' }            → use DPoP only when the realm advertises it
+//   useDPoP: { mode: 'strict', alg: 'ES256' } → require DPoP (default), pin the algorithm
+await tc.init({ onLoad: "check-sso", pkceMethod: "S256", useDPoP: { mode: "strict", alg: "ES256" } });
 // tc.secureFetch() auto-attaches DPoP headers
 ```
-**VERIFIED** (test-cases `DPoPAuthProvider.tsx`)
+**VERIFIED** (tidecloak-js `IAMService.js` on `main` — `useDPoP` default `{ mode: 'strict' }`)
 
 **Server-side verification pattern** **VERIFIED** (keylessh `server/auth.ts`, test-cases `dpop-protected/route.ts`):
 1. Extract `Authorization: DPoP <token>` (NOT `Bearer`)
@@ -368,7 +371,7 @@ Alternative: use `oauth2-dpop` npm package + `jose` for simpler verification. **
 **Agent implication**:
 - `jwk` field is only present when IGA is enabled on the realm. Validate its presence at startup.
 - Adapter JSON enables local JWT verification. Do not use `createRemoteJWKSet` or fetch JWKS remotely. If `jwk` is missing, re-export adapter with IGA enabled. (I-04)
-- Export via vendor endpoint: `GET /admin/realms/{realm}/clients/{client-id}/vendorResources/get-installations-provider?providerId=keycloak-oidc-keycloak-json` **VERIFIED** (vendor confirmation, GAP-044 resolved). There is a single provider ID: `keycloak-oidc-keycloak-json`. The string `tidecloak-oidc-keycloak-json` does not exist in the codebase and should not be used.
+- Export via vendor endpoint: `GET /admin/realms/{realm}/vendorResources/get-installations-provider?clientId={client-uuid}&providerId=keycloak-oidc-keycloak-json` **VERIFIED** (vendor confirmation, GAP-044 resolved). This is the **realm-level** endpoint; the client is passed as the `clientId={uuid}` query param, NOT as a `/clients/{id}/` path segment (the per-client path returns a minimal adapter missing `jwk`). There is a single provider ID: `keycloak-oidc-keycloak-json`. The string `tidecloak-oidc-keycloak-json` does not exist in the codebase and should not be used.
 - The config loader must select the `client-origin-auth-{window.location.origin}` entry and pass it to the SDK as `clientOriginAuth`. If no matching entry exists, enclave initialization will fail. **VERIFIED** (vendor confirmation, GAP-048 resolved)
 
 **Common confusion**: Adapter JSON is NOT standard Keycloak format. Do not use generic Keycloak adapter parsers.
@@ -442,7 +445,7 @@ Discovered in keylessh; not in API documentation.
 | `POST /admin/realms/{realm}/vendorResources/setUpTideRealm` | Initialize Tide features (email + terms) | `init-tidecloak.sh` |
 | `POST /admin/realms/{realm}/tide-admin/toggle-iga` | Enable/disable IGA | `init-tidecloak.sh` |
 | `POST /admin/realms/{realm}/users/{user-id}/tideAdminResources/get-required-action-link` | Generate account linking URL | `init-tidecloak.sh` |
-| `GET /admin/realms/{realm}/clients/{client-id}/vendorResources/get-installations-provider?providerId=keycloak-oidc-keycloak-json` | Download adapter JSON with Tide extensions. Only valid providerId: `keycloak-oidc-keycloak-json`. `tidecloak-oidc-keycloak-json` does not exist. | `init-tidecloak.sh`, vendor confirmation (GAP-044 resolved) |
+| `GET /admin/realms/{realm}/vendorResources/get-installations-provider?clientId={client-uuid}&providerId=keycloak-oidc-keycloak-json` | Download adapter JSON with Tide extensions. Realm-level endpoint; client passed as `clientId={uuid}` query param (NOT a `/clients/{id}/` path segment). Only valid providerId: `keycloak-oidc-keycloak-json`. `tidecloak-oidc-keycloak-json` does not exist. | `init-tidecloak.sh`, vendor confirmation (GAP-044 resolved) |
 
 **PARTIALLY_RESOLVED** (GAP-029): Most endpoint paths observed. `setUpTideRealm` fully documented (vendor confirmation, batch-02 Q-03). `get-required-action-link` request/response schema still missing.
 
@@ -661,11 +664,13 @@ Also add the `@tidecloak/react` ESM alias. See `canon/framework-matrix.md` for t
 
 **Anti-pattern**: Destructuring `{ ApprovalType, ExecutionType }` from `Models.Policy` instead of `Models`. `Models.Policy` is the Policy class itself. This gives `undefined`, causing `Cannot read properties of undefined (reading 'IMPLICIT')`.
 
-### `@tideorg/js` Export Reference (v0.13.26)
+### `@tideorg/js` Export Reference (v0.13.33)
 
-`@tideorg/js` exports 7 namespaces. Only `Models` and `Contracts` are needed for app-level policy work. The others are internal SDK plumbing.
+`@tideorg/js` exports 8 namespaces. Only `Models` and `Contracts` are needed for app-level policy work. The others are internal SDK plumbing.
 
-**Top-level namespaces**: `Models`, `Contracts`, `Clients`, `Cryptide`, `Flow`, `Math`, `Tools` (also aliased as `Utils`).
+**Top-level namespaces**: `Models`, `Contracts`, `Clients`, `Cryptide`, `Errors`, `Flow`, `Math`, `Tools` (also aliased as `Utils`).
+
+**Top-level convenience re-exports** (alongside the namespaces): `TideError` and `TideJsErrorCodes` (from `Errors`), and `RecentRequestsBuffer` (from `Clients`). The `Errors` namespace carries the SDK's structured error-reporting surface. **VERIFIED** (tide-js `index.ts` on `main`).
 
 #### Models (app-facing — used in policy signing)
 
@@ -733,24 +738,31 @@ Key class: `Flow.SigningFlows.dVVKSigningFlow2Step` — two-step VVK signing. Me
 
 ## Admin Policy Endpoint
 
-**What it is**: The correct endpoint for fetching the signed admin policy needed in step 3 of policy signing. Two endpoints exist; one is wrong. **VERIFIED** (operational exemplars: forseti-crypto-quickstart, keylessh)
+**What it is**: How to fetch the signed admin policy needed in step 3 of policy signing. **VERIFIED** (custom-contracts.md; LEARNINGS-ratidefy-batch-001 L-22)
 
 **Endpoints**:
 ```
 WRONG:   GET /admin/realms/{realm}/tide-admin/realm-policy
          Returns: { status: "none" } even when the policy exists
 
-CORRECT: GET /realms/{realm}/tide-policy-resources/admin-policy
-         Returns: base64-encoded bytes (does not require admin credentials)
+WRONG:   GET /realms/{realm}/tide-policy-resources/admin-policy
+         This public endpoint does NOT exist on current main.
+
+CORRECT: GET /admin/realms/{realm}/iga/role-policies   (server-side, admin bearer token)
+         Returns: an array of role-policy records; the signed policy bytes
+         live in each record's `policy` field (base64), alongside `policySig`.
 ```
 
-**Response handling**: The correct endpoint returns base64 text, not raw binary. Decode on backend:
+**Response handling**: Fetch server-side with an admin bearer token, pick the `admin-policy` record, and decode its `policy` field. Proxy the bytes to the browser:
 ```js
-// Backend proxy
-const b64 = await tcRes.text();
-const raw = Buffer.from(b64, "base64");
-const bytes = Array.from(new Uint8Array(raw));
-res.json({ policyBytes: bytes });
+// Backend proxy (admin token required)
+const rpUrl = `${authServerUrl}/admin/realms/${realm}/iga/role-policies`;
+const rolePolicies = await fetch(rpUrl, {
+  headers: { Authorization: `Bearer ${adminToken}` },
+}).then(r => r.json());
+const adminPolicyB64 = rolePolicies.find(p => p.name === 'admin-policy')?.policy;
+const raw = Buffer.from(adminPolicyB64, "base64");
+res.json({ policyBytes: Array.from(new Uint8Array(raw)) });
 
 // Frontend
 const data = await res.json();

package/canon/custom-contracts.md

@@ -259,7 +259,7 @@ Gas limit is 50,000. Exceeding it throws `OutOfGasException` and the operation f
 ### Step 1: Upload Contract to TideCloak (Optional)
 
 ```
-PUT /admin/realms/{realm}/tide-admin/forseti-contracts
+POST /admin/realms/{realm}/iga/forseti-contracts
 Content-Type: application/json
 Authorization: Bearer <admin-token>
 
@@ -269,7 +269,7 @@ Authorization: Bearer <admin-token>
 }
 ```
 
-The ORK compiles the contract in its sandbox and stores it. The contract ID is `SHA512(source code)`.
+The ORK compiles the contract in its sandbox and stores it. The response carries the stored contract's `contractHash` (`SHA512(source code)`).
 
 Note: This endpoint may not be available on all TideCloak images. If it returns 404/405, the contract is deployed through the policy signing flow (Step 3) instead — the contract source is included in the contract transport.
 
@@ -305,11 +305,15 @@ Important:
 
 Policy deployment requires the realm's **admin policy** to authorize the operation. The admin policy is pre-signed during realm setup (IGA bootstrap) and must be attached to every policy creation request. VERIFIED (LEARNINGS-ratidefy-batch-001 L-22).
 
-**Fetch the admin policy** (server-side — endpoint does not support CORS):
+**Fetch the admin policy** (server-side, admin bearer token — the signed policy is stored as a role policy). The public `tide-policy-resources/admin-policy` endpoint is not present on current main; retrieve the signed policy bytes from the admin IGA surface instead:
 ```typescript
-// Server-side: proxy this to the browser, or pre-download as static file
-const adminPolicyUrl = `${authServerUrl}/realms/${realm}/tide-policy-resources/admin-policy`;
-const adminPolicyB64 = await fetch(adminPolicyUrl).then(r => r.text());
+// Server-side (admin token required): read the signed role/admin policy.
+const rpUrl = `${authServerUrl}/admin/realms/${realm}/iga/role-policies`;
+const rolePolicies = await fetch(rpUrl, {
+  headers: { Authorization: `Bearer ${adminToken}` },
+}).then(r => r.json());
+// Each record carries `policy` (base64 signed bytes) + `policySig`.
+const adminPolicyB64 = rolePolicies.find(p => p.name === 'admin-policy')?.policy;
 const adminPolicyBytes = Uint8Array.from(atob(adminPolicyB64), c => c.charCodeAt(0));
 ```
 
@@ -358,7 +362,7 @@ const signedPolicyBytes = policy.toBytes();  // Store THESE bytes
 - Use `tc.createTideRequest()` → `tc.requestTideOperatorApproval()` → `tc.executeSignRequest()` — the React context's `initializeTideRequest` does not expose the approve/execute steps. VERIFIED (LEARNINGS-ratidefy-batch-001 L-24).
 - `initializeTideRequest` returns a **new object** — it does NOT mutate in place. If using it, capture the return value (AP-59).
 - Store `policy.toBytes()` (with signature attached), NOT `request.encode()` (AP-57).
-- Admin policy is fetched from `/realms/{realm}/tide-policy-resources/admin-policy`. This endpoint has no CORS — fetch server-side and proxy to browser (see RB-008). VERIFIED (LEARNINGS-ratidefy-batch-001 L-22).
+- Admin policy is fetched server-side (admin bearer) from `/admin/realms/{realm}/iga/role-policies` — the signed bytes live in each record's `policy` field. The old public `tide-policy-resources/admin-policy` endpoint is not present on current main; proxy the fetched bytes to the browser (see RB-008).
 
 ### Step 4: Use the Signed Policy
 
@@ -506,7 +510,7 @@ Available: `System`, `System.Linq`, `System.Collections.Generic`, `System.Text`,
 - **Wrong context properties**: Use `ctx.Dokens` (not `ctx.Approvers`) in `ValidateApprovers`, `ctx.Doken` (not `ctx.Executor`) in `ValidateExecutor`. Wrap with `DokenDto.WrapAll(ctx.Dokens)` and `new DokenDto(ctx.Doken)`. VERIFIED (LEARNINGS-ratidefy-batch-001 L-23).
 - **Params as plain object**: Use `[['Role', 'admin']]` not `{ Role: 'admin' }` (AP-54)
 - **Store request.encode() as policy**: Use `policy.toBytes()` not `request.encode()` (AP-57). Related: AP-55 (don't store raw VVK sig either)
-- **Missing admin policy**: Policy deployment requires the realm's admin policy attached to the request. Fetch from `/realms/{realm}/tide-policy-resources/admin-policy` (AP, LEARNINGS-ratidefy-batch-001 L-22)
+- **Missing admin policy**: Policy deployment requires the realm's admin policy attached to the request. Fetch (admin bearer) from `/admin/realms/{realm}/iga/role-policies` (`policy` field). The old `tide-policy-resources/admin-policy` endpoint is not on current main. (AP, LEARNINGS-ratidefy-batch-001 L-22)
 - **JSON to createTideRequest**: Pass `Uint8Array` from `signRequest.encode()` (AP-53)
 - **Import BasicCustomRequest from wrong package**: Use `asgard-tide`, not `@tideorg/js` or `@tidecloak/js` (LEARNINGS-ratidefy-batch-001 L-11)
 - **Import from @tidecloak/nextjs**: Use `@tidecloak/js` for Models, `heimdall-tide` for PolicySignRequest, `asgard-tide` for BasicCustomRequest