@tideorg/mcp 1.4.1 → 1.9.0

package/canon/troubleshooting.md

@@ -147,7 +147,7 @@ For missing Tide adapter (Cause 5):
 ```bash
 # Re-export adapter with Tide 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
 
@@ -176,7 +176,7 @@ For missing `jwk` field (Cause 1):
 ```bash
 # Re-export adapter with Tide extensions (IGA must be enabled)
 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
 
@@ -279,10 +279,10 @@ if (!navigator.onLine) {
 ```javascript
 // Test encrypt/decrypt round-trip
 const plaintext = 'test data';
-const ciphertext = await iam.doEncrypt('test', plaintext);
+const [ciphertext] = await iam.doEncrypt([{ data: plaintext, tags: ['test'] }]);
 console.log('Encrypted:', ciphertext);  // Should complete within 2-5 seconds
 
-const decrypted = await iam.doDecrypt('test', ciphertext);
+const [decrypted] = await iam.doDecrypt([{ encrypted: ciphertext, tags: ['test'] }]);
 console.log('Decrypted:', decrypted);  // Should match plaintext
 assert(decrypted === plaintext);
 ```
@@ -474,15 +474,10 @@ curl -H "Authorization: DPoP $TOKEN" -H "DPoP: $DPOP" https://app.example.com/ap
 curl "${TIDECLOAK_URL}/admin/realms/${REALM}" | jq '.igaEnabled // "not enabled"'
 # Should output: true
 
-# 2. Check pending change-sets
-curl "${TIDECLOAK_URL}/admin/realms/${REALM}/tide-admin/change-set/all/requests" \
+# 2. 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 '.'
-# Look for change-sets in 'PENDING' or 'APPROVED' status
-
-# 3. Check counts (lightweight)
-curl "${TIDECLOAK_URL}/admin/realms/${REALM}/tide-admin/change-set/counts" \
-  -H "Authorization: Bearer ${ADMIN_TOKEN}"
-# Returns: {"users":N,"roles":N,"clients":N,"groups":N,"total":N}
+# Objects keyed by .id, with .status, .readyToCommit
 ```
 
 **Fix**:
@@ -494,25 +489,20 @@ curl -X POST "${TIDECLOAK_URL}/admin/realms/${REALM}/tide-admin/toggle-iga" \
   -H "Authorization: Bearer ${ADMIN_TOKEN}"
 ```
 
-For change-set not approved (Cause 2):
+For a change request not approved (Cause 2):
 ```bash
-# Sign (approve) the change-set
-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":"DRAFT_RECORD_ID","changeSetType":"USER_ROLE","actionType":"CREATE"}]}'
-
-# If MultiAdmin: response has requiresApprovalPopup=true — complete enclave signing
-# Repeat with different admin tokens until quorum reached
+# Authorize (approve) — CR_ID is the .id from the list above; body {} optional
+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 '{}'
+# 409 = you already signed (four-eyes). Tide MultiAdmin: use the {id}/approval-model enclave exchange.
+# Repeat with different admin tokens until threshold reached.
 ```
 
-For change-set not committed (Cause 3):
+For a change request not committed (Cause 3):
 ```bash
-# Commit after quorum approval
-curl -X POST "${TIDECLOAK_URL}/admin/realms/${REALM}/tide-admin/change-set/commit/batch" \
-  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
-  -H "Content-Type: application/json" \
-  -d '{"changeSets":[{"changeSetId":"DRAFT_RECORD_ID","changeSetType":"USER_ROLE","actionType":"CREATE"}]}'
+# Commit after threshold reached (readyToCommit==true); 412 if still short
+curl -X POST "${TIDECLOAK_URL}/admin/realms/${REALM}/iga/change-requests/${CR_ID}/commit" \
+  -H "Authorization: Bearer ${ADMIN_TOKEN}"
 ```
 
 For token not refreshed (Cause 5):
@@ -873,10 +863,10 @@ curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/users?username=admin" \
   -H "Authorization: Bearer $TOKEN" | jq '.[0].id'
 # If null: user change request was not approved
 
-# Check pending user change requests
-curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/users/requests" \
+# Check pending change requests (current /iga/ surface)
+curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests?status=PENDING" \
   -H "Authorization: Bearer $TOKEN" | jq length
-# If > 0: approve them first
+# If > 0: approve them first (authorize + commit — see canon/iga-change-requests-api.md)
 ```
 
 **Fix**: Approve user creation change request between user creation and role assignment:
@@ -925,7 +915,7 @@ jq 'has("jwk") and has("vendorId") and has("homeOrkUrl")' data/tidecloak.json
 
 # 2. Check export endpoint used
 # Correct endpoint:
-# 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={clientId}&providerId=keycloak-oidc-keycloak-json  (realm-level; client is a query param)
 ```
 
 **Fix**:
@@ -933,7 +923,7 @@ jq 'has("jwk") and has("vendorId") and has("homeOrkUrl")' data/tidecloak.json
 ```bash
 # Use correct Tide adapter export endpoint
 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}" \
   -o data/tidecloak.json
 
@@ -1217,8 +1207,8 @@ await tc.executeSignRequest(request, true);
 | `requiresApprovalPopup: true` | Backend cannot auto-approve, must open approval enclave in admin's browser |
 | `Cannot destructure property 'Policy' of 'Models' as it is undefined` | `Models` imported from `@tidecloak/nextjs` (wrong package). Import from `@tideorg/js` instead. See T-15. |
 | `IAMService.createTideRequest is not a function` | `createTideRequest` (and `requestTideOperatorApproval`, `executeSignRequest`) live on `IAMService._tc` (TideCloak), not `IAMService`. See T-16. |
-| `Cannot destructure 'verifyTideCloakToken'` | `@tidecloak/verify` is CJS, use defensive interop pattern |
-| "Could not create tide realm" (email is null) | `setUpTideRealm` expects `Content-Type: application/x-www-form-urlencoded` with `email`, not JSON |
+| `Cannot destructure 'verifyTideCloakToken'` | Very old `@tidecloak/verify` (single-export build); upgrade — current versions ship dual CJS/ESM exports and a plain named import works. Note arg order is `(config, token, allowedRoles?)`. |
+| "Tide realm setup failed" / "Could not set up the Tide realm" | `setUpTideRealm` expects `Content-Type: application/x-www-form-urlencoded` with `email` (`@FormParam`), not JSON. (There is no explicit email-null guard; a missing/blank email surfaces as a downstream setup failure.) |
 | "Could not find configuration for Required Action" | Missing Tide env vars (`SYSTEM_HOME_ORK`, `USER_HOME_ORK`, `THRESHOLD_T`, `THRESHOLD_N`, `PAYER_PUBLIC`) from Docker |
 | AccessDeniedException on H2 | Data directory mounted as project root or wrong permissions; mount `./data` subdirectory and `chown 1000:1000` |
 | `"User has not been given any access to '${tag}'"` | User lacks `_tide_{tag}.selfencrypt` or `.selfdecrypt` role for self-encryption. Fatal — assign role, then re-login. |
@@ -1250,9 +1240,9 @@ curl -s "$TIDECLOAK_URL/admin/realms/$REALM/roles/default-roles-$REALM" \
   -H "Authorization: Bearer $TOKEN" | jq '.composites.realm'
 
 # 3. Check IGA change requests are approved
-curl -s "$TIDECLOAK_URL/admin/realms/$REALM/tide-admin/change-set/roles/requests" \
+curl -s "$TIDECLOAK_URL/admin/realms/$REALM/iga/change-requests?status=PENDING" \
   -H "Authorization: Bearer $TOKEN" | jq length
-# Should be 0. If > 0, approve and commit.
+# Should be 0. If > 0, authorize and commit (canon/iga-change-requests-api.md).
 
 # 4. Check user's JWT has the roles
 # Decode token and check realm_access.roles
@@ -1279,12 +1269,15 @@ curl -s "$TIDECLOAK_URL/admin/realms/$REALM/tide-admin/change-set/roles/requests
 
 **Diagnostics**:
 ```bash
-# 1. Check admin-policy endpoint is reachable
-curl -s "${TIDECLOAK_URL}/realms/${REALM}/tide-policy-resources/admin-policy"
-# Should return base64-encoded bytes, not HTML or error JSON
+# 1. Check the role-policies endpoint is reachable (admin bearer required)
+curl -s -H "Authorization: Bearer ${ADMIN_TOKEN}" \
+  "${TIDECLOAK_URL}/admin/realms/${REALM}/iga/role-policies"
+# Should return a JSON array of records; each carries the signed bytes in its `policy` field.
+# NOTE: the old public GET /realms/{realm}/tide-policy-resources/admin-policy endpoint
+# is NOT present on current main; do not rely on it.
 
 # 2. Check URL construction (common: double slash from trailing slash in auth-server-url)
-echo "${TIDECLOAK_URL}/realms/${REALM}/tide-policy-resources/admin-policy"
+echo "${TIDECLOAK_URL}/admin/realms/${REALM}/iga/role-policies"
 # Must not contain // between host and path (except after protocol)
 
 # 3. Check if addPolicy was called AFTER approval, not before
@@ -1294,15 +1287,18 @@ grep -B 5 "addPolicy" src/
 
 **Fix**:
 
-1. **Fetch admin policy from the correct endpoint** (no auth required):
+1. **Fetch the signed admin policy from the correct endpoint** (server-side, admin bearer token):
    ```
-   GET /realms/{realm}/tide-policy-resources/admin-policy
+   GET /admin/realms/{realm}/iga/role-policies
    ```
-   Not: `GET /admin/realms/{realm}/tide-admin/realm-policy` (returns `{ status: "none" }`).
+   The signed policy bytes live in each record's `policy` field. Not: the public
+   `GET /realms/{realm}/tide-policy-resources/admin-policy` endpoint (not on current main),
+   nor `GET /admin/realms/{realm}/tide-admin/realm-policy` (returns `{ status: "none" }`).
 
-2. **Decode base64 response**:
+2. **Decode the base64 `policy` field**:
    ```js
-   const b64 = await res.text();
+   const records = await res.json();
+   const b64 = records[0].policy;            // signed bytes, base64-encoded
    const raw = Buffer.from(b64, "base64");
    const bytes = new Uint8Array(raw);
    ```
@@ -1318,7 +1314,7 @@ grep -B 5 "addPolicy" src/
 4. **URL normalization**: Strip trailing slashes from `auth-server-url` before constructing endpoint URLs:
    ```js
    const baseUrl = config["auth-server-url"].replace(/\/+$/, "");
-   const adminPolicyUrl = `${baseUrl}/realms/${config.realm}/tide-policy-resources/admin-policy`;
+   const rolePoliciesUrl = `${baseUrl}/admin/realms/${config.realm}/iga/role-policies`;
    ```
 
 **This is a bootstrap/policy-flow failure, not a role issue.** Do not attempt to fix by renaming roles or switching encryption models.
@@ -1453,17 +1449,17 @@ VERIFIED (TIDE_LEARNINGS-001 L-05).
 
 ---
 
-## T-18: IGA Change-Set Approval May Require Admin Console UI
+## T-18: IGA Change-Request Approval May Require Admin Console UI (Tide MultiAdmin)
 
-**Symptom**: REST-based `POST /tide-admin/change-set/sign` succeeds but `POST /tide-admin/change-set/commit` fails with "Could not find authorization signature."
+**Symptom**: REST-based `POST /iga/change-requests/{id}/authorize` succeeds but `commit` fails (or the CR never reaches `readyToCommit`) with "Could not find authorization signature."
 
-**Root cause**: IGA approval is a cryptographic operation requiring the admin's Tide doken and ORK network interaction. In some configurations, the REST-based sign endpoint auto-signs but the commit requires the browser-based SDK (`approveTideRequests()` via the admin console UI).
+**Root cause**: In Tide MultiAdmin mode, approval is a cryptographic operation requiring the admin's Tide doken and ORK interaction — a bare `authorize` is not enough; the admin must complete the two-phase `{id}/approval-model` enclave exchange. FirstAdmin/Tideless mode signs server-side on `authorize`, so bootstrap works headless.
 
-**When this happens**: Typically when the admin has a linked Tide identity and IGA requires the cryptographic round-trip. The bootstrap script's REST-based `approve_and_commit` may work for the initial bootstrap (master admin token) but fail for subsequent operations.
+**When this happens**: Typically once the realm is in Tide MultiAdmin mode (a `tide-realm-admin` exists and IGA requires the cryptographic round-trip). The bootstrap script's `approve_all_pending` works during initial FirstAdmin bootstrap but a headless `authorize` fails for subsequent MultiAdmin operations.
 
-**Fix**: If REST commit fails, approve and commit change requests from the TideCloak admin console UI: `http://localhost:8080/admin/master/console/#/{realm}`. Navigate to the change request section and approve from the UI.
+**Fix**: Complete the enclave step — `GET`/`POST /iga/change-requests/{id}/approval-model` with the SDK/enclave, or approve from the TideCloak admin console UI (`http://localhost:8080/admin/master/console/#/{realm}` → Change Requests).
 
-**Verification**: After approval, `GET /tide-admin/change-set/counts` returns `total: 0`.
+**Verification**: After approval, `GET /iga/change-requests?status=PENDING` returns `[]`.
 
 VERIFIED (TIDE_LEARNINGS-001 L-11).
 
@@ -1483,7 +1479,7 @@ VERIFIED (TIDE_LEARNINGS-001 L-11).
 5. Check TideCloak container logs: `docker logs <container>` for the real error
 
 **Common 500 causes**:
-- ORK PreSign failure (`Provided TideAuthData OR PreviousTokenAuthorization`) — stale realm, recreate it
+- ORK PreSign failure — on a stale realm, recreate it. Actual PreSign error strings on current ORK include: `"Tide user authentication data provided but no valid authentication method found within"` and `"DPoP thumbprint in requested token does not match with what the tide user approved"` (`ork: TidecloakSessionStartTokenSignRequest.cs`). (The older `Provided TideAuthData OR PreviousTokenAuthorization` string is no longer emitted.)
 - Database connection failure
 - Realm misconfiguration after incomplete bootstrap
 
@@ -1492,3 +1488,155 @@ VERIFIED (TIDE_LEARNINGS-001 L-11).
 **Verification**: After fixing the server error, the request returns 200 with proper CORS headers.
 
 VERIFIED (LEARNINGS-ratidefy-batch-001 L-15).
+
+---
+
+## T-20: Admin API Returns 401 Despite Valid Roles (Missing JWT kid)
+
+**Symptom**: Token has all admin roles (`realm-admin`, `manage-users`, `view-users`, etc.), token is not expired, but admin REST API returns `{"error":"HTTP 401 Unauthorized"}`. TideCloak logs show `kid is null, cant find public key: realm={0}`.
+
+**Possible Causes**:
+1. JWT header has no `kid` field — realm's EdDSA signing key configuration is broken
+2. Token signed with ORK threshold EdDSA but no `kid` reference for admin API to look up the verification key
+
+**Diagnostics**:
+
+```bash
+# Decode the JWT header
+echo '<token>' | cut -d. -f1 | base64 -d 2>/dev/null | jq .
+# If output shows {"alg":"EdDSA","typ":"JWT"} with NO "kid" field — that's the problem
+```
+
+**Fix**: Recreate the TideCloak realm. The `kid` issue is a realm-level configuration problem that cannot be fixed on existing tokens. A new realm will issue tokens with proper `kid` in the JWT header.
+
+**Verification**: After recreating the realm, decode a new token's header — it should include `"kid": "some-key-id"`.
+
+VERIFIED (Ratidefy SaaS — ratidefy-sign realm had missing kid, recreated as ratidefy-sign-2).
+
+---
+
+## T-21: Enclave Error "Client origin could not be verified"
+
+**Symptom**: Tide enclave popup appears and immediately closes. Browser console shows `[HEIMDALL] Recieved enclave error: Client origin could not be verified`.
+
+**Possible Causes**:
+1. `CustomAdminUIDomain` not set on Tide IDP
+2. IDP settings not signed after setting `CustomAdminUIDomain`
+3. `client-origin-auth` key in adapter config is malformed or missing the origin URL
+
+**Diagnostics**:
+
+```bash
+# Check CustomAdminUIDomain
+TOKEN=$(curl -s -X POST "$TC_URL/realms/master/protocol/openid-connect/token" \
+  -d "username=admin&password=$PASS&grant_type=password&client_id=admin-cli" | jq -r .access_token)
+curl -s "$TC_URL/admin/realms/$REALM/identity-provider/instances/tide" \
+  -H "Authorization: Bearer $TOKEN" | jq '.config.CustomAdminUIDomain'
+
+# Check adapter config for client-origin-auth key
+# The key MUST include the origin URL: "client-origin-auth-https://myapp.com"
+# NOT a hash/signature as the key suffix
+```
+
+**Fix**:
+1. Set `CustomAdminUIDomain` to the app origin (e.g., `https://myapp.com`)
+2. Sign the IDP settings: `POST /admin/realms/{realm}/vendorResources/sign-idp-settings`
+3. Ensure adapter config `client-origin-auth` key includes the origin URL, not just the signature value
+
+**Verification**: Enclave popup appears and stays open for user interaction.
+
+VERIFIED (Ratidefy SaaS — IDP settings unsigned, client-origin-auth key had signature instead of origin URL).
+
+---
+
+## T-22: IGA Role Assignment Stuck in DRAFT (Unsignable Change Request)
+
+**Symptom**: Role assigned to user via admin API, change request created, but sign/commit returns 200 without actually signing. Role remains in DRAFT state permanently.
+
+**Possible Causes**:
+1. Role assigned before the user linked their Tide account — IGA requires a Tide doken for change request signing
+2. The master admin token can create change requests but cannot sign them without a Tide identity
+
+**Diagnostics**:
+1. Check TideCloak admin → realm → Users → target user → Role Mapping tab
+2. If role shows "DRAFT" badge, the change request was never signed
+3. Check if user has a federated identity (Identity Provider Links tab)
+
+**Fix**: 
+1. Delete the DRAFT change request
+2. Ensure the user links their Tide account first (via invite link)
+3. Then assign the role — the change request can now be signed
+
+**Prevention**: In automated provisioning, split into two phases:
+- Phase A: Create realm, user, generate invite link (no role assignment)
+- Phase B: After user links Tide account, assign role and approve change request
+
+**Verification**: Role shows "ACTIVE" status in TideCloak admin after sign+commit.
+
+VERIFIED (Ratidefy SaaS — provisioner assigned tide-realm-admin before account linking, creating permanent DRAFT).
+
+---
+
+## T-23: ASP.NET Core JWT Validation Fails on Tidecloak EdDSA Tokens
+
+**Symptoms:**
+- `IDX10503: Signature validation failed`
+- `IDX10500: Signature validation failed. No security keys were provided`
+- 401 on every request despite a valid `Authorization: Bearer <token>`
+
+**Cause:** `Microsoft.IdentityModel.Tokens` does not ship EdDSA. The `Tide.Asgard.AspNetCore.Authentication` SDK ships an EdDSA `SignatureProvider` in `Tide.Asgard.Core`, but you have to wire it in by setting `IssuerSigningKey = Utils.GetEd25519IssuerKey(builder.Configuration)`.
+
+The asgard `Example/Program.cs` has that exact line **commented out** at line 17. Copying the Example verbatim leaves you with no EdDSA support; the README form at lines 117-139 is the correct wiring.
+
+**Fix:**
+```csharp
+builder.Services.AddKeycloakWebApiAuthentication(builder.Configuration, options =>
+{
+    options.RequireHttpsMetadata = false;
+    options.TokenValidationParameters.IssuerSigningKey =
+        Utils.GetEd25519IssuerKey(builder.Configuration);
+});
+```
+
+**Verification:** Tokens with `alg=EdDSA` validate. Logs at Debug for `Keycloak.AuthServices` show the validation chain completing.
+
+VERIFIED (asgard `README.md:117-139` vs `Example/Program.cs:17`).
+
+See [playbooks/protect-aspnet-core-asgard.md](../playbooks/protect-aspnet-core-asgard.md).
+
+---
+
+## T-24: ASP.NET Core Token Exchange Throws NotImplementedException
+
+**Symptoms:**
+- `ITokenExchangeService.ExchangeToken(...)` throws `NotImplementedException` from the asgard SDK.
+- Worked before; broke after enabling DPoP on the browser SPA.
+
+**Cause:** `TokenExchangeService.ExchangeToken` inspects the inbound `Authorization` header. Bearer tokens are routed to a fully-implemented path. DPoP-tagged requests are routed to `ExchangeDPoPToken`, which is a stub (`throw new NotImplementedException()` at the top of the method). The same applies to the "Doken" auth scheme (`ExchangeTideDoken` stub). The internal `ValidateExchangeProof` helper is also a stub.
+
+The most common trigger is uncommenting `useDPoP: { mode: "strict", alg: "EdDSA" }` in the SPA's `kc.init({...})` call. The moment the SPA starts sending `Authorization: DPoP <token>` + `DPoP: <proof>` headers, every controller that calls `ExchangeToken` 500s.
+
+**Fix:** Disable browser DPoP until the SDK ships a DPoP-aware exchange path. The DPoP proof-validation service (`DPoPProofValidationService`) is fully implemented for **inbound** DPoP, but its registration helper `.WithDPoP(...)` is commented out — so DPoP today requires manual service wiring on inbound requests AND no DPoP on token exchange.
+
+**Verification:** With `useDPoP` disabled, exchange succeeds. With DPoP on, the 500 is reproducible.
+
+VERIFIED (asgard `TokenExchangeService.cs:28-35` routes to stub at line 93).
+
+---
+
+## T-25: ASP.NET Core 401 with Audience Mismatch
+
+**Symptoms:**
+- 401 on every browser-issued request despite a valid token.
+- Token decodes correctly but `aud` claim does not include the backend client ID.
+
+**Cause:** The browser's public client (`browser-login-page`) issues tokens with itself as the audience. The .NET backend's confidential client (`backend`) rejects tokens that do not list `backend` in `aud`.
+
+**Fix:** Add an audience mapper to the browser client's dedicated client scope.
+
+- Realm -> Clients -> `browser-login-page` -> Client scopes -> `browser-login-page-dedicated` -> Add mapper -> By configuration -> Audience.
+- Name: `backend-mapper`. Included Client Audience: `backend`. Save.
+
+**Verification:** Decode an SPA-issued token (e.g. at jwt.io); confirm `aud` array contains `backend`.
+
+VERIFIED (asgard `README.md:55-62`).

package/canon/version-policy.md

@@ -8,22 +8,20 @@ All other pack files point here. Do not duplicate version numbers in playbooks o
 
 ## Tide SDK Packages
 
-Resolved from npm registry on 2026-03-30. No 0.99.x versions are used.
+Resolved from npm registry on 2026-07-07. npm is the release source of truth. Repo `package.json` version fields lag npm (e.g. `tidecloak-js` source on `main` reads 0.12.15); always confirm against npm, not the checked-out source tree.
 
 | Package | Stable version | Range for templates | Purpose |
 |---------|---------------|--------------------| --------|
-| `@tidecloak/js` | 0.13.26 | `0.13.26` | Core SDK (vanilla JS, IAMService) |
-| `@tidecloak/react` | 0.13.26 | `0.13.26` | React hooks and guard components |
-| `@tidecloak/nextjs` | 0.13.26 | `0.13.26` | Next.js provider and hooks |
-| `@tidecloak/verify` | 0.13.26 | `0.13.26` | Server-side JWT verification (CJS) |
-| `heimdall-tide` | 0.13.26 | `0.13.26` | Policy signing, BasicCustomRequest |
-| `@tideorg/js` | 0.13.26 | `0.13.26` | Models, Contracts (Forseti) |
-| `asgard-tide` | 0.13.26 | `0.13.26` | Signing request builders (`BasicCustomRequest`, `DynamicPayloadCustomRequest`) |
+| `@tidecloak/js` | 0.13.33 | `0.13.33` | Core SDK (vanilla JS, IAMService) |
+| `@tidecloak/react` | 0.13.33 | `0.13.33` | React hooks and guard components |
+| `@tidecloak/nextjs` | 0.13.33 | `0.13.33` | Next.js provider and hooks |
+| `@tidecloak/verify` | 0.13.33 | `0.13.33` | Server-side JWT verification (CJS) |
+| `heimdall-tide` | 0.13.33 | `0.13.33` | Policy signing, BasicCustomRequest |
+| `@tideorg/js` | 0.13.33 | `0.13.33` | Models, Contracts (Forseti). `tide-js` `main` package.json reads 0.13.32; npm latest is 0.13.33. |
+| `asgard-tide` | 0.13.33 | `0.13.33` | Signing request builders (`BasicCustomRequest`, `DynamicPayloadCustomRequest`) |
 
 **Pin to exact version in templates.** Tide packages are pre-1.0. Minor bumps can break. Run `npm view <package> version` before installing to confirm the latest stable.
 
-**Exclude all 0.99.x versions.** If any `@tidecloak/*` package publishes a 0.99.x release, do not adopt it in pack guidance until it is confirmed stable.
-
 ---
 
 ## Framework Packages
@@ -75,7 +73,6 @@ npm view jose version
 
 - **Do not use `latest` tag in package.json.** Pin Tide packages to exact versions. Use caret ranges only for framework packages. This applies to all Tide packages: `@tidecloak/*`, `@tideorg/js`, `heimdall-tide`, `asgard-tide`.
 - **Do not use `-staging` npm tags.** Tags like `0.13.24-staging` are pre-release builds. Always use the stable version listed above. "Use staging" refers to the Docker image (`tideorg/tidecloak-stg-dev`), never to npm package tags. VERIFIED (LEARNINGS-batch-005 L-01, L-02).
-- **Do not use 0.99.x versions** of any `@tidecloak/*` package in templates or guidance.
 - **Do not assume 1.0.0.** All Tide packages are pre-1.0. Do not write `"@tidecloak/nextjs": "^1.0.0"`.
 - **Do not hardcode versions in playbook install snippets.** Playbooks should say `npm install @tidecloak/nextjs` (installs latest) and then instruct the builder to verify with `npm view`. Templates pin the version explicitly.
 - **Docker image and npm versions are independent.** Switching to the staging Docker image (`tidecloak-stg-dev`) does NOT mean switching to staging npm packages. npm packages stay at stable versions.
@@ -86,4 +83,3 @@ npm view jose version
 
 - When a new stable Tide SDK release is published.
 - When a framework major version ships that affects template compatibility.
-- When a 0.99.x Tide package appears and a decision is needed.

package/mcp-server/dist/http.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/mcp-server/dist/http.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import express from "express";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer } from "./server.js";
+const app = express();
+app.use(express.json());
+// Optional Bearer token auth
+const API_TOKEN = process.env.API_TOKEN;
+if (API_TOKEN) {
+    app.use("/mcp", (req, res, next) => {
+        const auth = req.headers.authorization;
+        if (!auth || auth !== `Bearer ${API_TOKEN}`) {
+            res.status(401).json({ error: "Unauthorized" });
+            return;
+        }
+        next();
+    });
+}
+// MCP endpoint — stateless (new server + transport per request)
+app.post("/mcp", async (req, res) => {
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    res.on("close", () => {
+        transport.close();
+        server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+});
+// Handle GET and DELETE for SSE streams (required by protocol)
+app.get("/mcp", async (req, res) => {
+    res.status(405).json({ error: "Method not allowed. Use POST for stateless MCP." });
+});
+app.delete("/mcp", async (req, res) => {
+    res.status(405).json({ error: "Method not allowed. Stateless server — no sessions to delete." });
+});
+// Health check for Azure / load balancers
+app.get("/health", (_, res) => {
+    res.status(200).json({ status: "ok", name: "@tideorg/mcp" });
+});
+const port = parseInt(process.env.PORT || "3000", 10);
+app.listen(port, "0.0.0.0", () => {
+    console.log(`@tideorg/mcp HTTP server listening on port ${port}`);
+    console.log(`MCP endpoint: http://0.0.0.0:${port}/mcp`);
+    console.log(`Health check: http://0.0.0.0:${port}/health`);
+});