@tideorg/mcp 1.4.2 → 1.9.1

package/canon/feature-mapping.md

@@ -102,55 +102,6 @@ if [ -n "$USER_KEY" ]; then echo "Linked"; fi
 
 ---
 
-## Server-Side Delegation
-
-### Delegation Token Exchange
-
-**SDK surface**:
-- `TideDelegation` class from `@tidecloak/server`
-- `createTideFetch` from `@tidecloak/js`
-- `requireDelegation()` and `handleDelegation()` Express middleware
-- `req.delegation.fetch()` helper for admin API calls
-
-**What it does**: Lets your server call TideCloak admin APIs on behalf of authenticated users without using master admin credentials.
-
-**What is actually Tide-specific**:
-- Two-hop chain of trust: browser DPoP key -> delegation request -> server ephemeral key
-- DelegationToken:1 signing model validated by ORK network
-- DPoP approval via ORK enclave (session key signs server's JKT)
-- Threshold EdDSA signing of delegation token
-
-**What is standard OAuth2**:
-- Token exchange (RFC 8693) with `act` claim
-- DPoP (RFC 9449) binding for proof-of-possession
-
-**Agent implication**:
-- Use `@tidecloak/server` for server-side admin calls. Do not use master admin credentials.
-- `createTideFetch` handles the 419 interrupt pattern transparently on the browser side
-- Delegation tokens are short-lived (max 600s), cached per user session
-- Scoped delegation via `requested_roles` can restrict roles in the delegation token
-
-**Verification**:
-```javascript
-// Server: admin route with delegation
-app.get('/api/admin/users',
-  authenticate, requireAdmin,
-  getDelegation().requireDelegation(),
-  async (req, res) => {
-    const users = await req.delegation.fetch(adminUrl + '/users');
-    res.json(users);
-  }
-);
-
-// Browser: transparent delegation
-const appFetch = createTideFetch(window.fetch);
-const users = await appFetch('/api/admin/users');
-```
-
-**Full reference**: See `canon/delegation.md` and `playbooks/setup-server-delegation.md`.
-
----
-
 ## Authorization Features
 
 ### Role-Based Route Protection (Client-Side)
@@ -316,8 +267,8 @@ curl -H "Authorization: DPoP $TOKEN" -H "DPoP: $PROOF" https://api.example.com/p
 ### Encrypt / Decrypt (Self-Encryption)
 
 **SDK surface**:
-- `doEncrypt(tag, plaintext)` → ciphertext
-- `doDecrypt(tag, ciphertext)` → plaintext
+- `doEncrypt([{ data: plaintext, tags: [tag] }])` → array of ciphertexts
+- `doDecrypt([{ encrypted: ciphertext, tags: [tag] }])` → array of plaintexts
 
 **What it looks like**: Standard E2EE with application-side key management.
 
@@ -344,14 +295,14 @@ curl -H "Authorization: DPoP $TOKEN" -H "DPoP: $PROOF" https://api.example.com/p
 **Workflow**:
 1. Admin creates roles: `_tide_ssn.selfencrypt`, `_tide_ssn.selfdecrypt`
 2. Admin assigns roles to users via IGA approval
-3. User calls `doEncrypt('ssn', '123-45-6789')` → ciphertext stored in app DB
-4. User calls `doDecrypt('ssn', ciphertext)` → Fabric checks JWT for `_tide_ssn.selfdecrypt` role → threshold-decrypts session key → plaintext returned
+3. User calls `doEncrypt([{ data: '123-45-6789', tags: ['ssn'] }])` → ciphertext stored in app DB
+4. User calls `doDecrypt([{ encrypted: ciphertext, tags: ['ssn'] }])` → Fabric checks JWT for `_tide_ssn.selfdecrypt` role → threshold-decrypts session key → plaintext returned
 
 **Verification**:
 ```javascript
-const ciphertext = await iam.doEncrypt('test', 'secret data');
+const [ciphertext] = await iam.doEncrypt([{ data: 'secret data', tags: ['test'] }]);
 assert(ciphertext !== 'secret data');
-const plaintext = await iam.doDecrypt('test', ciphertext);
+const [plaintext] = await iam.doDecrypt([{ encrypted: ciphertext, tags: ['test'] }]);
 assert(plaintext === 'secret data');
 ```
 
@@ -365,13 +316,15 @@ assert(plaintext === 'secret data');
 
 ### IGA Quorum Approval
 
+> **⚠️ API SURFACE MIGRATION — confirmed by Tide 2026-07-07 (GAP-065).** The change-request endpoints have moved to iga-core's **`/admin/realms/{realm}/iga/change-requests/...`** surface, which **replaces** the legacy `/tide-admin/change-set/...` surface shown below. New shape: the mutating write is captured (HTTP 202 + a change-request id); approve per-id with `POST .../iga/change-requests/{id}/authorize` (200/403/409 — 409 = four-eyes re-sign) then `POST .../iga/change-requests/{id}/commit` (200/403/409/412/404 — 412 = quorum unmet); reject with `POST .../{id}/deny`; batch with `POST /iga/change-requests/bulk-authorize`; list with `GET /iga/change-requests?status=PENDING`; in Tide mode the enclave step is `GET`/`POST .../{id}/approval-model`. Enabling IGA is unchanged: `POST /tide-admin/toggle-iga` (realm attr `isIGAEnabled="true"`). **Also note the two-mode split** (`iga.attestor`): Tide (`=tide`, cryptographic VVK/VRK→ORK sealing) vs Tideless (`=simple`/unset, username attestation, server-enforced, NO crypto). See `canon/security-gap-mapping.md` (SG-07/SG-14/SG-16 + IGA-model note). **Full endpoint spec + payloads + the bootstrap approve/commit loop: `canon/iga-change-requests-api.md`.** The workflow and verification examples below now use the new surface; the legacy `/tide-admin/change-set/...` paths are retained only in the old→new mapping for reference.
+
 **What it is**: Admin changes require multi-admin approval sealed by VVK threshold signatures. **VERIFIED** (IGA.mdx, SetupIGA.md, keylessh `init-tidecloak.sh`)
 
-**Change-set workflow** **VERIFIED** (CHANGE_REQUEST_API.md, all exemplar init scripts):
+**Change-request workflow** (legacy surface shown — see migration banner above; new surface is `/iga/change-requests/...`) **VERIFIED for legacy** (CHANGE_REQUEST_API.md, all exemplar init scripts):
 1. **Create**: Admin action triggers draft creation automatically (DRAFT/PENDING)
-2. **Approve**: `POST /admin/realms/{realm}/tide-admin/change-set/sign/batch`
-3. **Enclave** (MultiAdmin mode): decode `changeSetDraftRequests`, present to enclave, submit via `POST .../tideAdminResources/add-review`
-4. **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`
+3. **Enclave** (MultiAdmin / Tide mode): decode `changeSetDraftRequests`, present to enclave, submit via legacy `POST .../tideAdminResources/add-review` → new `POST .../iga/change-requests/{id}/approval-model`
+4. **Commit**: legacy `POST .../tide-admin/change-set/commit/batch` → new `POST .../iga/change-requests/{id}/commit`
 
 **Quorum formula**: `max(1, floor(TotalAdmins * 0.7))` **VERIFIED** (SetupIGA.md). Note: this is the IGA admin quorum, distinct from the SSH policy `threshold` (per-role signing approval count).
 
@@ -394,21 +347,20 @@ assert(plaintext === 'secret data');
 - Change requests have a 1-month (2628000s) cryptographic expiry enforced by the Tide enclave. No automatic DB cleanup — stale drafts persist until cancelled. Not configurable. **VERIFIED** (vendor confirmation, batch-02 Q-08, A-25 resolved)
 - **Draft-triggering scope** **VERIFIED** (vendor confirmation, GAP-041 resolved): When IGA is enabled on a non-master realm, 18 specific admin API actions create change-set drafts. Not all mutating endpoints create drafts. Operations fall into two categories: DRAFT (requires quorum sign/commit) and ACTIVE (auto-approved, audit-only). Role creation gets ACTIVE status — no sign/commit needed. Role assignment to users gets DRAFT status — sign/commit required.
 
-**Verification**:
+**Verification** (current `/iga/change-requests/...` surface — see `canon/iga-change-requests-api.md`):
 ```bash
-# List pending user change-sets
-curl "${TIDECLOAK_URL}/admin/realms/${REALM}/tide-admin/change-set/users/requests" \
-  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq '.[].draftRecordId'
-# Sign (approve)
-curl -X POST "${TIDECLOAK_URL}/admin/realms/${REALM}/tide-admin/change-set/sign/batch" \
-  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
-  -H "Content-Type: application/json" \
-  -d '{"changeSets":[{"changeSetId":"...","changeSetType":"USER_ROLE","actionType":"CREATE"}]}'
-# Commit
-curl -X POST "${TIDECLOAK_URL}/admin/realms/${REALM}/tide-admin/change-set/commit/batch" \
+# List pending change requests (all types, single call)
+curl "${TIDECLOAK_URL}/admin/realms/${REALM}/iga/change-requests?status=PENDING" \
+  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq '.[].id'
+# Authorize (approve) one CR — body optional; FirstAdmin/Tideless signs server-side
+curl -X POST "${TIDECLOAK_URL}/admin/realms/${REALM}/iga/change-requests/${CR_ID}/authorize" \
   -H "Authorization: Bearer ${ADMIN_TOKEN}" \
-  -H "Content-Type: application/json" \
-  -d '{"changeSets":[{"changeSetId":"...","changeSetType":"USER_ROLE","actionType":"CREATE"}]}'
+  -H "Content-Type: application/json" -d '{}'
+# Commit (409/412 if not PENDING / under threshold or unmet dependency)
+curl -X POST "${TIDECLOAK_URL}/admin/realms/${REALM}/iga/change-requests/${CR_ID}/commit" \
+  -H "Authorization: Bearer ${ADMIN_TOKEN}"
+# Batch approve during bootstrap:
+#   POST .../iga/change-requests/bulk-authorize  -d '{"actionTypeIn":["CREATE","DELETE"],"limit":100}'
 ```
 
 **Common confusion**: IGA docs read as "approval workflow" without emphasizing threshold signatures. This is NOT procedural approval; it is cryptographic enforcement.
@@ -472,10 +424,10 @@ assert(result.signature !== null);  // ORKs approved and signed
 
 **Export endpoint** **VERIFIED** (vendor confirmation, GAP-044 resolved):
 ```
-GET /admin/realms/{realm}/clients/{client-id}/vendorResources/get-installations-provider?providerId=keycloak-oidc-keycloak-json
+GET /admin/realms/{realm}/vendorResources/get-installations-provider?clientId={client-uuid}&providerId=keycloak-oidc-keycloak-json
 ```
 
-There is a single provider ID: `keycloak-oidc-keycloak-json`. The string `tidecloak-oidc-keycloak-json` does not exist in the codebase. TideCloak enriches the adapter JSON via this vendor endpoint by post-processing the standard provider output to inject Tide-specific fields.
+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. TideCloak enriches the adapter JSON via this vendor endpoint by post-processing the standard provider output to inject Tide-specific fields.
 
 **Loading locations** **VERIFIED** (keylessh configs):
 - File: `data/tidecloak.json`
@@ -527,7 +479,7 @@ Content-Type: application/x-www-form-urlencoded
 Params: email (string, required), isRagnarokEnabled (boolean, optional, defaults true)
 Response: 200 with raw licensing JSON as text/plain
 ```
-The endpoint creates the Tide IDP, `tide-vendor-key` component, provisions a free-tier license via the ORK network, and generates the initial VVK/VRK keys. Exactly two parameters — no hidden or undocumented ones. Sending JSON body causes `"Could not create tide realm (email is null)"`.
+The endpoint creates the Tide IDP, `tide-vendor-key` component, provisions a free-tier license via the ORK network, and generates the initial VVK/VRK keys. Exactly two parameters — no hidden or undocumented ones. Sending a JSON body (instead of `x-www-form-urlencoded`) causes the setup to fail with `"Tide realm setup failed"` / `"Could not set up the Tide realm"`.
 
 **Tide realm defaults** **VERIFIED** (keylessh `realm.json`):
 - Default roles: `_tide_enabled`, `offline_access`, `uma_authorization`

package/canon/framework-matrix.md

@@ -300,13 +300,11 @@ export function loadTideConfig(): TideConfig {
 
 **Alternative pattern** **VERIFIED** (keylessh exemplar):
 
-The `@tidecloak/verify` package provides a higher-level verification function. It is CJS — never use named ESM imports.
+The `@tidecloak/verify` package provides a higher-level verification function. It ships a proper dual `exports` map (`import` → ESM, `require` → CJS), so a plain named import works in both ESM and CJS callers.
 
 ```typescript
-// @tidecloak/verify is CJS — use defensive interop pattern
-import TideJWT from '@tidecloak/verify';
-const _mod = (TideJWT as any)?.default ?? TideJWT;
-const { verifyTideCloakToken } = _mod;
+// @tidecloak/verify ships dual exports — use a plain named import
+import { verifyTideCloakToken } from '@tidecloak/verify';
 
 // config = parsed tidecloak.json adapter config
 // token = raw JWT string (without "Bearer " prefix)
@@ -314,14 +312,12 @@ const { verifyTideCloakToken } = _mod;
 const payload = await verifyTideCloakToken(config, token, allowedRoles);
 ```
 
-**Anti-pattern**: `import { verifyTideCloakToken } from "@tidecloak/verify"` fails with `does not provide an export named 'verifyTideCloakToken'`. The package is CJS. Always use the default import with defensive interop.
+**Note**: Older docs wrapped this in a defensive `const _mod = (TideJWT as any)?.default ?? TideJWT` interop dance against a single-export build. That is no longer required — the package now ships a dual `exports` map, so the plain named import above works. Do not reintroduce the dance; if a named import genuinely fails, you are on a very old version and should upgrade.
 
 **Express middleware using `@tidecloak/verify`:**
 
 ```typescript
-import TideJWT from '@tidecloak/verify';
-const _mod = (TideJWT as any)?.default ?? TideJWT;
-const { verifyTideCloakToken } = _mod;
+import { verifyTideCloakToken } from '@tidecloak/verify';
 
 async function authenticate(req, res, next) {
   const token = req.headers.authorization?.substring(7);
@@ -434,7 +430,7 @@ export function EncryptedForm() {
 
   async function handleSubmit(plaintext: string) {
     // Encrypt before sending to server
-    const ciphertext = await doEncrypt('ssn', plaintext);
+    const [ciphertext] = await doEncrypt([{ data: plaintext, tags: ['ssn'] }]);
     await fetch('/api/users', {
       method: 'POST',
       body: JSON.stringify({ ssn: ciphertext }),
@@ -443,7 +439,7 @@ export function EncryptedForm() {
 
   async function handleLoad(ciphertext: string) {
     // Decrypt after receiving from server
-    const plaintext = await doDecrypt('ssn', ciphertext);
+    const [plaintext] = await doDecrypt([{ encrypted: ciphertext, tags: ['ssn'] }]);
     console.log(plaintext);
   }
 
@@ -628,7 +624,9 @@ import { TideCloakContextProvider } from '@tidecloak/react';
 import App from './App';
 
 // Config file must be in public/tidecloak.json — do NOT import as a JS module
-const initOptions = { enableDpop: true };  // DPoP required for Tide security; ES256 is the default algorithm
+// DPoP is on by default (useDPoP defaults to { mode: 'strict' }). Pass useDPoP to pin the alg
+// or relax the mode. There is no `enableDpop` flag. ES256 is the default algorithm.
+const initOptions = { useDPoP: { mode: 'strict', alg: 'ES256' } };
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
@@ -651,7 +649,7 @@ import { useTideCloak, Authenticated, Unauthenticated } from '@tidecloak/react';
 
 function App() {
   return (
-    <TideCloakContextProvider configUrl="/tidecloak.json" initOptions={{ enableDpop: true }}>
+    <TideCloakContextProvider configUrl="/tidecloak.json" initOptions={{ useDPoP: { mode: 'strict', alg: 'ES256' } }}>
       <AppContent />
     </TideCloakContextProvider>
   );
@@ -973,7 +971,7 @@ const users = await response.json();
 ```typescript
 // Encrypt
 const plaintext = 'sensitive data';
-const ciphertext = await iam.doEncrypt('ssn', plaintext);
+const [ciphertext] = await iam.doEncrypt([{ data: plaintext, tags: ['ssn'] }]);
 
 // Send to server
 await iam.secureFetch('/api/users', {
@@ -984,7 +982,7 @@ await iam.secureFetch('/api/users', {
 // Decrypt
 const response = await iam.secureFetch('/api/users/123');
 const data = await response.json();
-const plaintext = await iam.doDecrypt('ssn', data.ssn);
+const [plaintext] = await iam.doDecrypt([{ encrypted: data.ssn, tags: ['ssn'] }]);
 ```
 
 ---
@@ -1100,17 +1098,66 @@ Every Tide-enabled app must have a working page at its configured `redirectUri`.
 
 ---
 
+## .NET / ASP.NET Core (via asgard)
+
+ASP.NET Core APIs integrate with TideCloak through the **Tide.Asgard.AspNetCore** SDK rather than stock `Microsoft.AspNetCore.Authentication.OpenIdConnect`. The asgard SDK supplies the EdDSA `SignatureProvider` (Microsoft.IdentityModel.Tokens does not ship EdDSA) and an OAuth 2.0 Token Exchange client tuned for Tidecloak.
+
+Out of scope for the current pack priority (Next.js > React > Vanilla per [AGENTS.md](../AGENTS.md)). This section exists so an agent asked about C# / ASP.NET Core routes the work to the right playbook instead of inventing OIDC wiring.
+
+### Packages
+
+| Package | Source | Purpose | Status |
+|---------|--------|---------|--------|
+| `Tide.Asgard.AspNetCore.Authentication` (v0.1.0) | `github.com/tide-foundation/asgard` — consume via `<ProjectReference>` until NuGet publication is verified | JWT bearer wiring, Ed25519 issuer-key extraction (`Utils.GetEd25519IssuerKey`), Token Exchange client (`AddTokenExchange`, `ITokenExchangeService`) | VERIFIED |
+| `Tide.Asgard.Core` (v0.1.0) | Same repo | EdDSA `SignatureProvider` / `SecurityKey` on top of `Microsoft.IdentityModel.Tokens 8.15.0` and `BouncyCastle.Cryptography 2.6.2` | VERIFIED |
+| `Tide.Asgard.AspNetCore.DPoP` | Same repo, no `<PackageId>` | DPoP proof-validation primitives. Validator is implemented (~540 lines), but `.WithDPoP(...)` registration is commented out at HEAD | OBSERVED_PATTERN |
+
+### Wiring (canonical form)
+
+Use the README form, not the Example's `Program.cs` — the Example has the `IssuerSigningKey` line commented out:
+
+```csharp
+builder.Services.AddKeycloakWebApiAuthentication(builder.Configuration, options =>
+{
+    options.RequireHttpsMetadata = false;
+    options.TokenValidationParameters.IssuerSigningKey =
+        Utils.GetEd25519IssuerKey(builder.Configuration);
+});
+
+builder.Services.AddTokenExchange(builder.Configuration); // optional, RFC 8693
+```
+
+`appsettings.json` must put the backend client's adapter config under a section literally named `Keycloak` — the section name is hardcoded in `Keycloak.AuthServices` and in `AddTokenExchange(IConfiguration)`.
+
+### What the SDK does NOT do
+
+- **Policy / contract signing or testing.** The TypeScript `asgard-tide` npm package (different artifact, same repo) handles wire-format models. There is no C# equivalent in the .NET SDK.
+- **Forseti contract enforcement.** Forseti contracts run as C# inside the ORK sandbox, not in your .NET API. See [custom-contracts.md](custom-contracts.md).
+- **Browser DPoP** is plumbed but not active. `useDPoP` on the SPA crashes Token Exchange (the DPoP path throws `NotImplementedException`).
+
+### Full procedure
+
+See [playbooks/protect-aspnet-core-asgard.md](../playbooks/protect-aspnet-core-asgard.md).
+
+### Status note
+
+PUC-092, PUC-093, PUC-094, PUC-095 in `notes/pack-update-candidates.md` planned ASP.NET Core docs around stock OpenIdConnect middleware. The asgard SDK supersedes those plans for the JWT-validation and token-exchange paths. The playbook references that supersession explicitly.
+
+---
+
 ## Key Dependencies
 
 | Package | Stable version | Purpose |
 |---------|---------------|---------|
-| `@tidecloak/js` | 0.13.26 | Core SDK (vanilla JS) |
-| `@tidecloak/react` | 0.13.26 | React hooks and guards |
-| `@tidecloak/nextjs` | 0.13.26 | Next.js provider and hooks |
-| `@tidecloak/verify` | 0.13.26 | Server-side JWT verification (CJS) |
-| `heimdall-tide` | 0.13.26 | Policy signing, BasicCustomRequest |
-| `@tideorg/js` | 0.13.26 | Models, Contracts (Forseti) |
-| `asgard-tide` | 0.13.26 | Vendor validation |
+| `@tidecloak/js` | 0.13.33 | Core SDK (vanilla JS) |
+| `@tidecloak/react` | 0.13.33 | React hooks and guards |
+| `@tidecloak/nextjs` | 0.13.33 | Next.js provider and hooks |
+| `@tidecloak/verify` | 0.13.33 | Server-side JWT verification (CJS) |
+| `heimdall-tide` | 0.13.33 | Policy signing, BasicCustomRequest |
+| `@tideorg/js` | 0.13.33 | Models, Contracts (Forseti) |
+| `asgard-tide` | 0.13.33 | Vendor validation |
+| `Tide.Asgard.AspNetCore.Authentication` (.NET) | 0.1.0 | ASP.NET Core JWT bearer + Token Exchange. NuGet publication unverified — consume via `<ProjectReference>` from `github.com/tide-foundation/asgard`. See [.NET / ASP.NET Core](#net--aspnet-core-via-asgard). |
+| `Tide.Asgard.Core` (.NET) | 0.1.0 | EdDSA `SignatureProvider` for `Microsoft.IdentityModel.Tokens`. Same repo, same caveat. |
 
 All Tide packages are pre-1.0. Pin to exact versions in templates. See [canon/version-policy.md](version-policy.md) for the full version policy.
 

package/canon/hosting-options.md

@@ -0,0 +1,111 @@
+# Hosting Options: Self-Hosted vs Partner-Hosted TideCloak
+
+Where the TideCloak instance runs is an infrastructure decision, separate from how the app integrates with it. This file covers the two options, the trust model of each, and the Skycloak partner-hosted path.
+
+**This is a pre-build branch (I-17).** Resolve where TideCloak will run before running bootstrap — the setup steps differ. It does **not** change the application wiring (SDK, provider, adapter JSON, JWT verification are identical either way).
+
+---
+
+## The two options
+
+| | Self-hosted | Partner-hosted (Skycloak) |
+|---|---|---|
+| Who runs TideCloak | You (Docker/Kubernetes/VM) | Skycloak, in their cloud |
+| Setup playbook | `deploy-tidecloak-docker` / `start-tidecloak-dev` | `provision-tidecloak-skycloak` |
+| Admin access | Master admin user/password you create | Admin Console SSO (Skycloak account); no admin password issued |
+| Automation identity | Bootstrap master-admin token | Per-cluster OAuth2 confidential client `skycloak-automation-<cluster-id>` |
+| You manage | OS, container, DB, upgrades, backups, TLS | Nothing — fully managed |
+| Best for | Full control, air-gapped, existing infra | Teams who don't want to run auth infra |
+
+Both terminate at the **same** application integration: adapter JSON with `jwk`/`vendorId`/`homeOrkUrl`, server-side JWT verification, DPoP. Choosing hosted does not weaken any invariant — it changes who operates the broker, not how the app enforces security.
+
+---
+
+## Trust model — why partner-hosting TideCloak is compatible with Tide
+
+This is the load-bearing point, and it must be stated honestly: **hosting the TideCloak broker with a partner is an availability and metadata trust, not an integrity trust** — *because of* Tide's threshold model, not despite it.
+
+**What the host CANNOT do** (guaranteed by Tide's invariants, regardless of who runs TideCloak):
+- **Forge tokens.** JWT signing is threshold VVK across the ORK network; a compromised TideCloak server cannot mint valid tokens (I-09, I-02). This is the whole point of Tide — the broker is not the trust root.
+- **Decrypt your data.** E2EE session keys are threshold-decrypted by the Fabric; plaintext never exists on the TideCloak server or any single ORK (I-11).
+- **Extract keys.** Keys never exist in whole form anywhere the host can reach (I-01).
+
+**What the host CAN do** (the honest caveats — surface these, do not bury them):
+- **Availability.** They operate the broker; they can take it down, throttle it, or lose it. This is a normal managed-service dependency.
+- **Metadata.** They see login timing, realm/client configuration, user identifiers, and IP-level traffic. They do not see passwords (threshold PRISM) or E2EE plaintext, but they see *who authenticates when*.
+- **Admin-path position.** With Admin Console SSO, Skycloak's account system sits in the admin-authentication path. Anyone who compromises the Skycloak account that fronts the console reaches the admin console (subject to whatever governs admin actions inside the realm — see next point).
+- **Tideless IGA is software-enforced by the host.** If the realm runs IGA in **Tideless mode** (`iga.attestor=simple`/unset), the admin-change quorum is enforced by TideCloak's own server logic — which the host operates. A malicious or compromised host could bypass it. **In Tide mode** (`iga.attestor=tide`, licensed), governance approvals are sealed cryptographically (VRK→Midgard→ORK) and the host cannot forge them. **For a partner-hosted deployment where governance integrity matters, use Tide mode.** (See I-10; the Tide/Tideless split is tracked in `GAP_REGISTER.md` GAP-065.)
+
+**One-line summary for a user**: "You can let Skycloak host TideCloak without handing them the ability to impersonate your users or read your data — those require the ORK threshold, which the host doesn't control. What you're trusting them for is uptime and the metadata they can see."
+
+---
+
+## Skycloak API reference
+
+**INFERRED/VERIFIED tags** below reflect the public docs at `https://skycloak.io/docs/api/` as of 2026-07 (`API-Version: 2026-06-01.beta`). The provisioning *procedure* is in `playbooks/provision-tidecloak-skycloak.md`.
+
+**Base URL**: `https://api.skycloak.io` **VERIFIED** (docs).
+
+**Authentication** **VERIFIED** (docs):
+- Header `API-Key: <key>` — created in the Skycloak dashboard (Workspace → API keys), shown once, treat as a secret.
+- Header `API-Version: 2026-06-01.beta` — **required** on every request.
+- Scopes: write includes read (e.g. `clusters:write` implies `clusters:read`). Credentials retrieval needs `clusters:credentials:read`. Missing scope → `403` with `API key does not have the required scope: <scope>`.
+- Separately, an **OAuth2 client-credentials** path exists for cluster-level automation (Terraform/CI) — distinct from the Public API key. Each cluster provisions a confidential automation client `skycloak-automation-<cluster-id>` in the `master` realm.
+
+**Endpoints** **VERIFIED** (docs; request/response field names below are **INFERRED** — confirm against the live response, they are not fully specified in the public docs):
+
+| Method | Path | Purpose | Scope |
+|---|---|---|---|
+| GET | `/clusters` | List clusters | `clusters:read` |
+| POST | `/clusters` | Create a cluster (async) | `clusters:write` |
+| GET | `/clusters/{id}` | Get cluster status | `clusters:read` |
+| GET | `/clusters/{id}/credentials` | Get cluster/automation credentials | `clusters:credentials:read` |
+
+**Create-cluster inputs** **VERIFIED** (feature docs; exact JSON field names **INFERRED**):
+- **Identity platform**: `Keycloak` or **`TideCloak`** — choose TideCloak for a Tide deployment. This is the field that makes the cluster a Tide broker.
+- **Name**: descriptive identifier.
+- **Version**: a latest-stable Keycloak/TideCloak version.
+- **Size**: `Small` (DEV, 1 site), `Medium` (STAGING, 2 sites), `Large` (PROD, 3 sites).
+- **Location/region**: US East Coast, Canada, Europe, Australia. Trial workspaces provision in the US; non-US regions need Developer plan or higher.
+
+**Lifecycle** **VERIFIED** (docs): creation is asynchronous. Cluster goes `provisioning`/"Creating" → `available` or `failed` (~2–4 min; email on completion). **Poll `GET /clusters/{id}` until status is `available` before bootstrapping.**
+
+**Result** **VERIFIED** (docs): cluster is reachable at `https://<cluster-id>.app.skycloak.io`. **No Keycloak admin username/password is issued** — admin console is reached via Admin Console SSO (Skycloak account); programmatic admin access uses the `skycloak-automation-<cluster-id>` OAuth2 client.
+
+**Errors** **VERIFIED** (docs): RFC 9457 Problem Details JSON (`type`, `title`, `detail`, `status`, `instance`; validation adds an `errors[]` array with `field`/`detail`/`code`/`value`). Notable codes: `402 Payment Required` (action not on current plan), `403` (scope), `409` (name/state conflict), `422` (validation), `429` (rate limit, with `Retry-After`).
+
+---
+
+## The critical open question (verify before promising a turnkey Tide setup)
+
+Skycloak lists TideCloak as a cluster identity platform, but the public docs do **not** confirm that a hosted TideCloak cluster exposes the full **Tide vendor surface** the pack's bootstrap depends on:
+- `POST /admin/realms/{realm}/vendorResources/setUpTideRealm` (creates Tide IDP, `tide-vendor-key`, provisions the free-tier license, generates VVK/VRK)
+- IGA toggle and the change-request/change-set governance API
+- Adapter export enriched with `jwk`/`vendorId`/`homeOrkUrl`
+- Whether Tide **licensing** (the Stripe free-tier flow) is handled by Skycloak or still required from the operator
+
+**Status: STILL_UNRESOLVED** — tracked in `GAP_REGISTER.md` (GAP-066). Until confirmed against a live hosted TideCloak cluster, treat the hosted path as: *provisioning is VERIFIED via Skycloak's API; the Tide-realm bootstrap on top of it is ASSUMED to use the same vendor endpoints and must be verified on the actual instance.* Do not tell a user the hosted path is fully turnkey for Tide until this is confirmed. If the vendor endpoints are absent, the honest answer is that Skycloak hosts the broker but Tide-realm setup needs the partner's Tide-specific provisioning (raise with the Tide/Skycloak teams).
+
+---
+
+## Verification
+
+A hosting-choice step is done when:
+1. The self-host vs hosted branch was resolved **before** bootstrap (I-17).
+2. If hosted: the cluster reports `available` and is reachable at its `*.app.skycloak.io` URL.
+3. The trust-model caveats (availability, metadata, admin-path, Tideless-IGA) were stated to the operator, not just the benefits.
+4. The adapter JSON exported from the hosted instance still contains `jwk`, `vendorId`, `homeOrkUrl` (I-05, I-13) — same requirement as self-hosted. If it doesn't, GAP-066 applies.
+
+## Anti-patterns
+
+- **AP-HOST-1** — Presenting partner-hosting as a security *downgrade* ("now a third party holds your auth"). It isn't, because of the threshold model — but state the real caveats (availability, metadata, Tideless-IGA), don't overcorrect into either fear or false comfort.
+- **AP-HOST-2** — Claiming the hosted Tide path is fully turnkey before GAP-066 is resolved. Provisioning the cluster is verified; the Tide-realm bootstrap on top is not.
+- **AP-HOST-3** — Putting the Skycloak API key or the `skycloak-automation-*` client secret in application code or the repo. These are operator/bootstrap secrets (like master admin creds, AP-41) — never in app runtime.
+- **AP-HOST-4** — Hardcoding `API-Version` omission. Every Skycloak API call needs the `API-Version` header or it fails.
+
+## Status Legend
+
+- **VERIFIED** — from Skycloak public docs or Tide canon that carries its own sourcing
+- **INFERRED** — strongly implied but not explicitly specified (e.g. exact JSON field names)
+- **ASSUMED** — operator guidance where sources are silent (e.g. Tide vendor endpoints on hosted clusters)
+- **STILL_UNRESOLVED** — open gap (GAP-066)