@tideorg/mcp 1.4.2 → 1.9.0

package/canon/iga-change-requests-api.md

@@ -0,0 +1,211 @@
+# IGA / QEA Change-Requests API (current surface)
+
+The authoritative REST surface for IGA (QEA — Quorum Enforced Authorization) change requests. **VERIFIED** (source: `tide-foundation/tidecloak-iga-extensions` → `docs/qea-iga-api.md`, iga-core; confirmed by Tide 2026-07-07, GAP-065).
+
+**This `/iga/change-requests/...` surface REPLACES the legacy `/tide-admin/change-set/...` surface.** The old surface (documented in the repo-root `CHANGE_REQUESTS_API.md`) is stale — do not use it for new work. Enabling IGA is unchanged: `POST /tide-admin/toggle-iga` (realm attribute `isIGAEnabled="true"`).
+
+For the security/trust implications and the Tide-vs-Tideless mode split, see `canon/feature-mapping.md` (IGA Quorum Approval), `canon/invariants.md` (I-10), and `canon/security-gap-mapping.md` (IGA-model note).
+
+---
+
+## Base path & auth
+
+```
+{keycloak-url}/admin/realms/{realm}/iga/...
+{keycloak-url}/admin/realms/{realm}/iga-tve/...      # TVE diagnostic bundles
+{keycloak-url}/admin/realms/{realm}/tide-admin/...   # toggle-iga, legacy
+```
+
+Header: `Authorization: Bearer $TOKEN` — requires `manage-realm` (some reads are lighter, noted below).
+
+---
+
+## Change-request lifecycle
+
+| Step | Method + path | Body | Success | Notable failures |
+|------|---------------|------|---------|------------------|
+| A governed admin write is captured | (the original admin call, e.g. assign role) | — | **202 Accepted** + `Location` header → the new CR | — |
+| List pending | `GET /iga/change-requests?status=PENDING` | — | 200, array of CR objects | — |
+| Get one | `GET /iga/change-requests/{id}` | — | 200 | 404 |
+| Authorize (sign) — simple lane | `POST /iga/change-requests/{id}/authorize` | `{}` (optional) | 200, updated CR (**does not commit**) | 403 (missing approver role), 409 (not PENDING / already signed / conflicting CR / a MultiAdmin CR) |
+| Approve — MultiAdmin enclave lane | `POST /iga/change-requests/{id}/approve` | enclave approval payload | 200, updated CR (**auto-commits once quorum met**) | 403, 409, 412 |
+| Commit | `POST /iga/change-requests/{id}/commit` | — | 200, CR now APPROVED | 412 (under threshold or unmet dependency) |
+| Edit pending CR | `PUT /iga/change-requests/{id}` | `{"rows":[...]}` | 200, updated CR | 404, 409 (not PENDING) |
+| Deny | `POST /iga/change-requests/{id}/deny` | — | 204 | 404 |
+| Bulk authorize | `POST /iga/change-requests/bulk-authorize` | `{"actionTypeIn":["CREATE","DELETE"],"limit":100}` | 200, `{results:[...], summary:{...}}` | 429 (a bulk run is already in progress — per-realm mutex) |
+
+**`status`** values: `PENDING`, `APPROVED`, `DENIED`, `CANCELLED`.
+
+### `authorize` vs `approve` vs `commit` — do not conflate
+
+Three distinct server operations (source: `IgaAdminResource` on origin/main). The button label in the admin console is **not** the same as the REST verb:
+
+- **`POST .../{id}/authorize`** (`IgaAdminResource:529`) — the **simple lane** (FirstAdmin / Tideless). Records the caller's approval and **NEVER commits**: even when `authCount >= threshold` the server does *not* call `combineFinal()`; commit is a separate explicit step. **Refuses tide-MultiAdmin CRs.**
+- **`POST .../{id}/approve`** (`IgaAdminResource:1096`) — the **MultiAdmin enclave lane**. Consumes the enclave approval and **approves AND auto-commits once quorum is met**. This is what the deployed admin console's **"Authorize" button** calls (button label ≠ REST `/authorize`).
+- **`POST .../{id}/commit`** — explicit **apply-only** step (`412` if still sub-quorum / dependency unmet). Used after a simple-lane `authorize` reaches threshold.
+
+**`PUT /iga/change-requests/{id}`** (`IgaAdminResource:1848`, `updateChangeRequest` → `service.updateRows()`) edits a still-`PENDING` CR's `rows` payload; body `{"rows":[...]}`.
+
+**Bulk-authorize authorizes; it does not commit.** After bulk-authorize, commit the CRs that became `readyToCommit` (see the bootstrap pattern below). ("Bulk Commit" in the admin UI is a client-side loop, not a server endpoint.)
+
+### Two-phase MultiAdmin approval (Tide mode enclave)
+
+In Tide mode (`iga.attestor=tide`) with MultiAdmin, the simple `authorize` lane refuses the CR; approval instead goes through `approve`, which requires an enclave signature obtained via the approval-model exchange:
+
+```
+Phase 1:  GET  /iga/change-requests/{id}/approval-model
+          → 200 {"changeRequestId":"...","requestModel":"<base64>"}
+          (decode requestModel, present to the Tide enclave, admin signs → base64 doken)
+
+Phase 2:  POST /iga/change-requests/{id}/approve   (MultiAdmin enclave lane — approves and auto-commits at quorum)
+          Body: the enclave approval / {"requestModel":"<base64 doken>"}
+          → 200 {"recorded":true,"authCount":N,"threshold":M}
+```
+
+**This is the automation boundary.** In FirstAdmin mode (fresh realm before any `tide-realm-admin`) and in Tideless mode, the simple-lane `authorize` signs server-side with no enclave popup (then `commit` applies), so bootstrap is fully automatable. In Tide MultiAdmin mode a human must sign the enclave challenge for `approve`.
+
+---
+
+## Change-request object (response fields)
+
+```
+id, realmId, entityType, entityId, actionType,
+status,                       # PENDING | APPROVED | DENIED | CANCELLED
+requestedBy, createdAt, resolvedAt, resolvedBy,
+rows,                         # payload replayed on commit
+authorizationCount, authorizers[], threshold,
+readyToCommit,                # boolean — safe to commit now
+requiredApproverRoles, scopeMode,   # scopeMode: "any" | "all"
+dependsOn, blocked, blockedReason   # dependency gating
+```
+
+**Use `id` for all per-CR operations** (this replaces the legacy `draftRecordId`). `entityType`/`actionType` replace the legacy `changeSetType`/`changeSetType`+`actionType` fields, and there is no `{changeSets:[...]}` request envelope anymore — operations are per-`id`.
+
+---
+
+## Comments
+
+```
+GET    /iga/change-requests/{id}/comments                 → 200 array
+POST   /iga/change-requests/{id}/comments   {"comment":"text"}  (≤2000 chars) → 201
+PUT    /iga/change-requests/{id}/comments/{commentId}     → 200 (author only)
+DELETE /iga/change-requests/{id}/comments/{commentId}     → 204 (author or realm admin)
+```
+
+## Manual ADOPT
+
+```
+POST /iga/adopt   {"entityType":"USER","entityId":"..."}   → 201 | 409 (ALREADY_ATTESTED)
+```
+
+## Role policies (M0 admin policy)
+
+```
+GET    /iga/role-policies                         # read: authenticated, no manage-realm
+GET    /iga/role-policies/{id}
+GET    /iga/role-policies/name/tide-realm-admin
+POST   /iga/role-policies   {"name":"...","policy":"<base64>","policySig":"..."}   # 403 if name="tide-realm-admin"
+DELETE /iga/role-policies/{id}
+DELETE /iga/role-policies/name/{name}
+```
+
+## Diagnostics
+
+```
+GET  /iga/change-requests/{id}/diagnostic-bundle
+     → {"diag_kind":"iga_cr_bundle","schema_version":1,"cr":{...},"authorizations":[...],"threshold":N,"approver_role":"..."}
+POST /iga-tve/tve-bundle   {"mode":"synthesize|pasted","clientId":"...","userId":"..."}   (Accept: application/json | application/cbor)
+```
+
+---
+
+## Status codes (summary)
+
+| Code | Meaning |
+|------|---------|
+| 202 | Governed action captured into a CR (`Location` → the CR) |
+| 400 | Malformed body / missing field |
+| 403 | Missing approver role |
+| 404 | Unknown CR or the entity vanished |
+| 409 | CR not PENDING, already signed, or a conflicting CR exists (four-eyes) |
+| 412 | Under threshold, or a dependency is unmet |
+| 429 | `bulk-authorize` already running (per-realm mutex) |
+
+## Threshold & approver resolution
+
+- `ADOPT_*` CRs short-circuit to threshold 1 (no approver-role check).
+- Otherwise the entity-level `iga.threshold` applies **only if that entity also sets `iga.approverRole`** (the coupling rule); else the realm `iga.threshold`; else 1 (clamped `max(1, …)` — the gate can't be disabled).
+- **FirstAdmin** mode (fresh realm, before any `tide-realm-admin`): threshold 1, any `manage-realm` admin signs, server-side VRK, no enclave.
+- **MultiAdmin** (Tide): dynamic floor `max(1, floor(0.7 × active tide-realm-admins))` unless overridden; enclave signature required.
+
+---
+
+## Bootstrap pattern (FirstAdmin / Tideless — fully automatable)
+
+During bootstrap the realm is in FirstAdmin (or Tideless) mode, so `authorize` signs server-side and the whole loop is scriptable. Replace the legacy per-type `sign`+`commit` calls with: **authorize all pending → commit the ready ones, in dependency passes.**
+
+```bash
+# $TC = base url, $REALM = realm, get_token() mints a fresh admin token.
+approve_all_pending() {
+  local TOKEN
+  # 1. Authorize every pending CREATE/DELETE change request in one call.
+  #    FirstAdmin/Tideless: server signs with VRK / records username — no enclave.
+  TOKEN="$(get_token)"
+  curl -s -X POST "$TC/admin/realms/$REALM/iga/change-requests/bulk-authorize" \
+    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+    -d '{"actionTypeIn":["CREATE","DELETE"],"limit":100}' > /dev/null
+
+  # 2. Commit everything that is ready. Loop a few passes so dependent CRs
+  #    (e.g. a role must exist before its assignment) become ready and commit.
+  for pass in 1 2 3 4 5; do
+    TOKEN="$(get_token)"
+    local ready
+    ready=$(curl -s "$TC/admin/realms/$REALM/iga/change-requests?status=PENDING" \
+      -H "Authorization: Bearer $TOKEN" | jq -r '.[] | select(.readyToCommit==true) | .id')
+    [ -z "$ready" ] && break
+    for id in $ready; do
+      TOKEN="$(get_token)"
+      curl -s -X POST "$TC/admin/realms/$REALM/iga/change-requests/$id/commit" \
+        -H "Authorization: Bearer $TOKEN" > /dev/null
+    done
+  done
+}
+```
+
+Call `approve_all_pending` at each stage that produces CRs (after client creation, after user creation, after role assignment) — the same stage points as the legacy script, but it now lists **all** pending CRs at once rather than per type.
+
+**Per-id alternative** (if you prefer not to use bulk-authorize):
+
+```bash
+TOKEN="$(get_token)"
+for id in $(curl -s "$TC/admin/realms/$REALM/iga/change-requests?status=PENDING" \
+              -H "Authorization: Bearer $TOKEN" | jq -r '.[].id'); do
+  TOKEN="$(get_token)"
+  curl -s -X POST "$TC/admin/realms/$REALM/iga/change-requests/$id/authorize" \
+    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}' > /dev/null
+done
+# then the same commit-in-passes loop as above
+```
+
+**Status of the bootstrap pattern: VERIFIED against the API spec; REQUIRES_RUNTIME_VALIDATION against a live iga-core instance.** The endpoint paths, payloads, and status codes are from the canonical `qea-iga-api.md`; the exact loop/ordering has not yet been run end-to-end here. Validate on a live instance and adjust the pass count / dependency handling if a CR stays `blocked`.
+
+---
+
+## Old → new migration map
+
+| Legacy (`/tide-admin/change-set/...`) | Current (`/iga/change-requests/...`) |
+|----------------------------------------|--------------------------------------|
+| `GET .../change-set/{type}/requests` | `GET /iga/change-requests?status=PENDING` |
+| `GET .../change-set/counts` | (derive from the list, or use diagnostics) |
+| `POST .../change-set/sign/batch` `{changeSets:[{changeSetId,changeSetType,actionType}]}` | `POST /iga/change-requests/{id}/authorize` `{}` (per id); batch: `POST /iga/change-requests/bulk-authorize` |
+| `POST .../change-set/commit/batch` `{changeSets:[...]}` | `POST /iga/change-requests/{id}/commit` |
+| `POST .../change-set/cancel/batch` | `POST /iga/change-requests/{id}/deny` |
+| `POST .../tideAdminResources/add-review` (enclave) | `POST /iga/change-requests/{id}/approval-model` |
+| field `draftRecordId` | field `id` |
+| fields `changeSetType` + `actionType` | fields `entityType` + `actionType` |
+| toggle `POST /tide-admin/toggle-iga` | **unchanged** |
+
+## Status Legend
+
+- **VERIFIED** — from the canonical `qea-iga-api.md` (iga-core)
+- **REQUIRES_RUNTIME_VALIDATION** — bootstrap loop not yet exercised end-to-end against a live instance

package/canon/invariants.md

@@ -136,7 +136,7 @@ grep -r "hasRole\|checkRole" server/routes/ | grep -v "after verifyJWT"
 **Rule**: JWT verification must use embedded JWKS from adapter JSON. Do not use `createRemoteJWKSet`. Do not fetch keys from the remote OIDC certs endpoint. If the `jwk` field is missing from `tidecloak.json`, this is a setup/bootstrap failure — stop and fix the export, do not fall back to remote key fetching.
 
 **What this means**:
-- Adapter JSON contains `jwk: { keys: JWK[] }` field (EdDSA public key, only when IGA enabled)
+- Adapter JSON contains `jwk: { keys: JWK[] }` field (EdDSA public key). It is emitted whenever the realm has a Tide vendor key; it is NOT gated on IGA being enabled.
 - Use `createLocalJWKSet(config.jwk)` from `jose`
 - If `config.jwk` is missing, throw an error. The fix is to re-export the adapter from TideCloak with IGA enabled, not to fetch keys remotely.
 - Also validate `azp` matches `config.resource`
@@ -145,6 +145,8 @@ grep -r "hasRole\|checkRole" server/routes/ | grep -v "after verifyJWT"
 
 **Forbidden**: `createRemoteJWKSet` must not be used in Tide verification flows. Do not add it as a fallback. Do not import it. If verification fails with `ERR_JWKS_NO_MATCHING_KEY`, the adapter JSON is stale — re-export it from TideCloak.
 
+**Note on the shipped `@tidecloak/verify`**: the packaged `verifyTideCloakToken` DOES fall back to `createRemoteJWKSet` when `config.jwk` is absent (`tidecloak-js: packages/tidecloak-verify/src/TideJWT.js`). That fallback is exactly the network path this invariant forbids. Therefore the operative rule for Tide apps is: **always pass `config.jwk` so verification uses the local JWKS; never let it fall through to the remote path.** A missing `jwk` is a setup failure to fix at the source, not a code path to rely on. This is intentional security doctrine — the pack is deliberately stricter than the SDK default.
+
 **Required pattern**:
 ```typescript
 import { createLocalJWKSet, jwtVerify } from 'jose';
@@ -186,7 +188,7 @@ grep -r "createRemoteJWKSet" lib/auth/ src/lib/auth/
 
 **Related invariants**: I-03 (Server-Side Verification), I-05 (Adapter JSON Required)
 
-**Note**: The `jwk` field is only present when IGA is enabled on the realm. Validate at startup. If missing, the fix is TideCloak bootstrap (enable IGA, re-export adapter), not remote JWKS.
+**Note**: The `jwk` field is present whenever the realm has a Tide vendor key (it is not gated on IGA). Validate at startup. If missing, the fix is TideCloak bootstrap / re-exporting the adapter, not remote JWKS.
 
 ---
 
@@ -197,7 +199,7 @@ grep -r "createRemoteJWKSet" lib/auth/ src/lib/auth/
 **Canonical filename**: `tidecloak.json`. Do not use `adapter.json`, `keycloak.json`, or other names.
 
 **What this means**:
-- Export adapter JSON from TideCloak admin console via `vendorResources/get-installations-provider?providerId=keycloak-oidc-keycloak-json` (this is the only valid provider ID — `tidecloak-oidc-keycloak-json` does not exist in the codebase)
+- Export adapter JSON from TideCloak via the realm-level endpoint `GET /admin/realms/{realm}/vendorResources/get-installations-provider?clientId={clientId}&providerId=keycloak-oidc-keycloak-json`. The client is a **query parameter** (`clientId=`), NOT a `/clients/{id}/` path segment. `keycloak-oidc-keycloak-json` is the only valid provider ID (`tidecloak-oidc-keycloak-json` does not exist).
 - Store at the correct location for the framework (see below)
 - Load at startup
 - Validate presence of Tide extensions
@@ -429,12 +431,14 @@ grep -r "if.*admin.*skip.*verify" server/
 
 **Rule**: Admin changes to roles, users, clients require quorum approval sealed by VVK threshold signatures. No single admin can act unilaterally. **VERIFIED** (IGA.mdx, SetupIGA.md, keylessh `init-tidecloak.sh`)
 
-**Quorum formula**: `max(1, floor(TotalAdmins * 0.7))` **VERIFIED** (SetupIGA.md)
+**Quorum formula**: `max(1, floor(TotalAdmins * 0.7))` **VERIFIED** (SetupIGA.md). This is the cryptographic quorum in **Tide mode** (`iga.attestor=tide`). In **Tideless mode** (`iga.attestor=simple`/unset) the same quorum count is enforced by TideCloak server logic with a username attestation and no cryptography — see `canon/security-gap-mapping.md` IGA-model note.
+
+> **⚠️ API SURFACE MIGRATION — confirmed by Tide 2026-07-07 (GAP-065).** The change-request endpoints have moved to **`/admin/realms/{realm}/iga/change-requests/...`** (iga-core), which **replaces** the legacy `/tide-admin/change-set/...` paths below. New surface: approve `POST .../iga/change-requests/{id}/authorize` (409 = four-eyes re-sign), commit `POST .../iga/change-requests/{id}/commit` (412 = quorum unmet), reject `POST .../{id}/deny`, batch `POST /iga/change-requests/bulk-authorize`, list `GET /iga/change-requests?status=PENDING`, Tide-mode enclave step `POST .../{id}/approval-model`. Enabling IGA is unchanged (`POST /tide-admin/toggle-iga`). **Full endpoint spec, payloads, and the bootstrap approve/commit loop: `canon/iga-change-requests-api.md`.** Bootstrap scripts and the examples below now use the new surface; verify against the live instance (bootstrap loop is REQUIRES_RUNTIME_VALIDATION).
 
-**Change-set workflow** **VERIFIED** (CHANGE_REQUEST_API.md):
+**Change-request workflow** (legacy surface — see migration banner) **VERIFIED for legacy** (CHANGE_REQUEST_API.md):
 1. Create: Admin action triggers draft creation automatically
-2. Approve: `POST /admin/realms/{realm}/tide-admin/change-set/sign/batch` (MultiAdmin mode returns enclave challenge)
-3. Commit: `POST /admin/realms/{realm}/tide-admin/change-set/commit/batch`
+2. Approve: legacy `POST .../tide-admin/change-set/sign/batch` → new `POST .../iga/change-requests/{id}/authorize` (MultiAdmin/Tide mode returns enclave challenge)
+3. Commit: legacy `POST .../tide-admin/change-set/commit/batch` → new `POST .../iga/change-requests/{id}/commit`
 
 **What this means**:
 - Single admin cannot create, modify, or delete users
@@ -459,19 +463,19 @@ curl "${TIDECLOAK_URL}/admin/realms/${REALM}" | jq '.igaEnabled'
 
 # Attempt admin change without approval
 curl -X POST "${TIDECLOAK_URL}/admin/realms/${REALM}/users" -d '{...}'
-# Should create change-set, not immediate user creation
+# Should return 202 (captured as a change request), not immediate user creation
 
-# Check pending change-sets
-curl "${TIDECLOAK_URL}/admin/realms/${REALM}/tide-admin/change-set/users/requests" \
-  -H "Authorization: Bearer ${ADMIN_TOKEN}"
-# Should list pending change
+# Check pending change requests (current /iga/ surface — see canon/iga-change-requests-api.md)
+curl "${TIDECLOAK_URL}/admin/realms/${REALM}/iga/change-requests?status=PENDING" \
+  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq '.[].id'
+# Should list pending change request ids
 ```
 
 **Consequence of violation**: Single compromised admin can create backdoor accounts, grant unauthorized roles, bypass all governance. IGA enforcement collapses to single-admin trust.
 
 **Related invariants**: I-09 (No Single Bypass)
 
-Change requests have a hardcoded 1-month (2628000s) cryptographic expiry enforced by the Tide enclave. After this window, signing is rejected. No automatic DB cleanup — stale drafts persist until cancelled. Not configurable. **VERIFIED** (vendor confirmation, batch-02 Q-08, A-25 resolved).
+Change requests carry a cryptographic expiry enforced by the Tide enclave; after the window, signing is rejected, and there is no automatic DB cleanup (stale drafts persist until cancelled). Note: `2628000s` (~1 month) is the VRK rotation period (`vrkRotationPeriodSeconds`, `ork` TaskConstants), NOT a per-change-request expiry constant — do not conflate the two. The exact CR expiry is enclave-side and was not confirmed as a hardcoded value in the extension repos on main.
 
 ---
 
@@ -509,15 +513,13 @@ No application-level max payload size **VERIFIED** (vendor confirmation, GAP-013
 
 ## I-12: DPoP Token Binding (Bidirectional Lockstep)
 
-**Rule**: DPoP requires simultaneous configuration on both server and client. If either side is enabled without the other, authentication fails. **VERIFIED** (session-002)
+**Rule**: DPoP is **ENABLED and ENFORCED by default** in the TideCloak SDK. `useDPoP` defaults to `{ mode: 'strict' }` in `IAMService` — it is opt-OUT, not opt-in. Disabling it requires setting `useDPoP: false` (or `{ mode: 'auto' }`) explicitly, and in strict mode init fails if the realm does not advertise DPoP support. **VERIFIED** (`tidecloak-js: packages/tidecloak-js/src/IAMService.js` — "DPoP is enabled and ENFORCED by default across all TideCloak SDKs").
 
-**Bidirectional lockstep**:
-- **Server-side** (realm template): `"dpop.bound.access.tokens": "true"` on the OIDC client. This tells TideCloak to bind tokens with DPoP.
-- **Client-side** (provider config): `useDPoP: { mode: 'strict', alg: 'ES256' }` inside the config object. This tells the SDK to generate DPoP proofs.
-- **Both must be set simultaneously.**
-  - Server on, client off → token endpoint returns 400 "DPoP proof is missing" (no hint the fix is client-side). VERIFIED (session-002).
-  - Client on, server off → proofs generated but ignored by TideCloak.
-- `useDPoP` goes inside the config object, NOT as a JSX prop on `TideCloakProvider`. VERIFIED (session-002).
+**Server/client must agree (lockstep)**:
+- **Server-side** (realm template): `"dpop.bound.access.tokens": "true"` on the OIDC client, and the realm must advertise `dpop_signing_alg_values_supported`. Because the client defaults to strict, a realm that does not advertise DPoP makes SDK init fail.
+- **Client-side** (provider config): the SDK default is `useDPoP: { mode: 'strict', alg: 'ES256' }`. To weaken/disable, set `useDPoP` explicitly. `useDPoP` goes inside the config object, NOT as a JSX prop on the provider. VERIFIED (session-002).
+  - Server off, client left at default strict → init fails ("server does not advertise DPoP support"). Set `useDPoP: false` or enable DPoP on the realm.
+  - Server on, client set to `false` → proofs not generated; token endpoint returns 400 "DPoP proof is missing".
 
 **`tide_dpop_auth.html` required** (when DPoP is enabled):
 - Copy `tide_dpop_auth.html` to `public/`. This file is loaded by the Tide enclave during login to prove DPoP key possession to the ORKs. **Do not modify it** — its content is integrity-checked.
@@ -572,10 +574,10 @@ DPoP is required for Tide's full security guarantees **VERIFIED** (vendor confir
 **Rule**: Adapter JSON must include Tide extensions (`jwk`, `vendorId`, `homeOrkUrl`). Generic Keycloak adapter is insufficient. **VERIFIED** (keylessh `tidecloakConfig.ts`)
 
 **What this means**:
-- Export adapter from TideCloak via `vendorResources/get-installations-provider?providerId=keycloak-oidc-keycloak-json` (the only valid provider ID)
+- Export adapter from TideCloak via the realm-level `GET /admin/realms/{realm}/vendorResources/get-installations-provider?clientId={clientId}&providerId=keycloak-oidc-keycloak-json` (client is a query param; `keycloak-oidc-keycloak-json` is the only valid provider ID)
 - Do not use generic Keycloak adapter export
 - Do not manually construct adapter JSON without Tide extensions
-- `jwk` field is only present when IGA is enabled on the realm
+- `jwk` field is emitted whenever the realm has a Tide vendor key (NOT gated on IGA)
 
 **Required Tide extensions**:
 - `jwk: { keys: JWK[] }` - Embedded JWKS for local JWT verification
@@ -597,7 +599,7 @@ jq '.jwk.keys | length' data/tidecloak.json
 
 **Related invariants**: I-04 (Embedded JWKS), I-05 (Adapter JSON Required)
 
-**Note**: The `jwk` field is only present when IGA is enabled. Validate at startup.
+**Note**: The `jwk` field is present whenever the realm has a Tide vendor key (not gated on IGA). Validate at startup.
 
 ---
 
@@ -651,17 +653,12 @@ Vendor guidance: universally required. Declare in realm.json template.
 - Compromised ORK cannot override policy
 - No client-side or server-side policy bypass
 
-**Contract submission** **VERIFIED** (keylessh `tideSsh.ts`):
+**Contract submission**: `tc.createTideRequest` takes a single **pre-encoded `Uint8Array`** (a `BaseTideRequest` you build and `.encode()`), NOT a `{ contract, modelName, authFlow, ... }` object. Build the request first, then submit its encoding (see AP-53). The C# contract source is carried inside the request's draft.
 ```typescript
-const signRequest = await tc.createTideRequest({
-  contract: "using System; ...",  // C# code
-  modelName: "BasicCustom<APP>:BasicCustom<1>",
-  authFlow: "Policy:1",
-  authorizer: tc.doken,
-  challengeData: { ... }
-});
-
-const result = await tc.executeSignRequest(signRequest);
+// Build a BaseTideRequest (name, version, authFlow, draft), then encode it.
+const request = new BaseTideRequest(name, version, "Policy:1", draft);
+const initializedBytes = await tc.createTideRequest(request.encode());
+const result = await tc.executeSignRequest(initializedBytes);
 ```
 
 **Verification**:
@@ -679,7 +676,7 @@ grep -r "bypassPolicy\|skipPolicy" src/ server/
 
 **Related invariants**: I-02 (Threshold), I-09 (No Single Bypass)
 
-**Sandbox model** **VERIFIED** (vendor confirmation, GAP-008 resolved): Five-layer security (Roslyn compilation, IL vetting with namespace block-list, AssemblyLoadContext isolation, VmHost process isolation, gas metering at 50,000 gas default). Block-list: `System.IO`, `System.Net`, `System.Diagnostics`, `System.Threading`, `System.Reflection`, `System.Runtime.InteropServices`, `System.Reflection.Emit`, `Microsoft.Win32`, plus `System.Console` and `System.Runtime.CompilerServices.Unsafe`. Non-deterministic calls blocked by default. Gas metering: `Claim(key)` = 5 gas, `Log(message)` = 25-30 gas, `OutOfGasException` when exhausted.
+**Sandbox model** **VERIFIED** (vendor confirmation, GAP-008 resolved): Five-layer security (Roslyn compilation, IL vetting with namespace block-list, AssemblyLoadContext isolation, VmHost process isolation, gas metering at 50,000 gas default). Block-list: `System.IO`, `System.Net`, `System.Diagnostics`, `System.Threading`, `System.Reflection`, `System.Runtime.InteropServices`, `System.Reflection.Emit`, `Microsoft.Win32`, plus `System.Console` and `System.Runtime.CompilerServices.Unsafe`. Non-deterministic calls blocked by default. Gas metering: `Claim(key)` = 5 gas, `Log(message)` = 25 gas, `OutOfGasException` when exhausted.
 
 **Remaining open questions**: Contract debugging opaque **PARTIALLY_RESOLVED** (GAP-018).
 
@@ -785,6 +782,7 @@ curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/auth/redirect
 |--------|----------|----------|------------------------|
 | App state | Fresh app (no auth) | Existing app (has auth) | Does the project have an existing auth system? |
 | Infrastructure | Generated app (has init script) | Manual / BYO TideCloak | Does `package.json` have an `"init"` script? Is TideCloak already running? |
+| TideCloak hosting | Self-hosted (Docker/K8s) | Partner-hosted (Skycloak, managed) | Does the team want to run auth infra, or use a managed instance? See `canon/hosting-options.md`. Does not change app wiring; changes bootstrap. |
 | Encryption model | Self-encryption (private, user-bound) | Policy-governed VVK (shared, cross-user) | Do other users need to decrypt the same ciphertext? |
 | App scope | Single-user private app | Organisation / team / shared app | Are there multiple users who share data or resources? |
 | Task type | Diagnosis (something is broken) | Setup (something needs building) | Is the app partially working, or not started? |