@tideorg/mcp 1.4.2 → 1.9.1

package/playbooks/bootstrap-realm-from-template.md

@@ -79,6 +79,14 @@ This activates the Tide license and generates the VRK. No manual "Manage License
 
 **Critical:** Content-Type must be `application/x-www-form-urlencoded`. JSON causes failure.
 
+**Form parameters** (`setUpTideRealm` on `main`):
+
+| Param | Required | Default | Notes |
+|-------|----------|---------|-------|
+| `email` | Yes (for licensing) | — | Used to request the free-tier license. Ignored only when `skipLicense=true`. |
+| `isRagnarokEnabled` | No | `true` | Enables realm offboarding (Ragnarok). The endpoint already defaults it to `true`; passing `isRagnarokEnabled=true` explicitly is harmless and matches the default. |
+| `skipLicense` | No | `false` | When `true`, skips license activation (`email` unused) and returns early. Leave at the default for normal bootstrap. |
+
 ### Step 5: Enable IGA
 
 ```bash
@@ -94,28 +102,35 @@ curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/toggle-iga"
 Realm creation + Tide setup generates change requests that must be approved before proceeding.
 
 ```bash
-approve_and_commit() {
-  local TYPE=$1
-  TOKEN="$(get_token)"
-  local requests=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/$TYPE/requests" \
-    -H "Authorization: Bearer $TOKEN" 2>/dev/null || echo "[]")
+# Current /iga/change-requests/... surface (replaces legacy /tide-admin/change-set/...).
+# Bootstrap runs in FirstAdmin/Tideless mode, so authorize signs server-side (no enclave).
+# Full spec: canon/iga-change-requests-api.md.
+approve_all_pending() {
+  local TOKEN ready id
 
-  echo "$requests" | jq -c '.[]' | while read -r req; do
-    local id=$(echo "$req" | jq -r .draftRecordId)
-    local cst=$(echo "$req" | jq -r .changeSetType)
-    local at=$(echo "$req" | jq -r .actionType)
-    local payload="{\"changeSetId\":\"$id\",\"changeSetType\":\"$cst\",\"actionType\":\"$at\"}"
+  # 1. Authorize all pending CREATE/DELETE change requests in one call.
+  TOKEN="$(get_token)"
+  curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests/bulk-authorize" \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/json" \
+    -d '{"actionTypeIn":["CREATE","DELETE"],"limit":100}' > /dev/null 2>&1
 
+  # 2. Commit ready CRs; loop passes so dependent CRs become ready.
+  for pass in 1 2 3 4 5; do
     TOKEN="$(get_token)"
-    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/sign" \
-      -H "Authorization: Bearer $TOKEN" \
-      -H "Content-Type: application/json" -d "$payload"
-
-    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/commit" \
-      -H "Authorization: Bearer $TOKEN" \
-      -H "Content-Type: application/json" -d "$payload"
+    ready=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests?status=PENDING" \
+      -H "Authorization: Bearer $TOKEN" 2>/dev/null \
+      | jq -r '.[] | select(.readyToCommit==true) | .id' 2>/dev/null)
+    [ -z "$ready" ] && break
+    for id in $ready; do
+      TOKEN="$(get_token)"
+      curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests/$id/commit" \
+        -H "Authorization: Bearer $TOKEN" > /dev/null 2>&1
+    done
   done
 }
+# Legacy call sites pass a type arg the new list-all surface ignores.
+approve_and_commit() { approve_all_pending; }
 
 approve_and_commit clients
 ```
@@ -135,7 +150,7 @@ approve_and_commit clients
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| "Could not create tide realm" | JSON sent to `setUpTideRealm` instead of form data | Use `application/x-www-form-urlencoded` |
+| "Tide realm setup failed" / "Could not set up the Tide realm" | JSON sent to `setUpTideRealm` instead of form data | Use `application/x-www-form-urlencoded` |
 | "email is null or empty" | Missing email parameter | Add `--data-urlencode "email=..."` |
 | 404 on setUpTideRealm | Wrong path (`/tide-admin/setUpTideRealm`) | Correct path: `/vendorResources/setUpTideRealm` |
 | Realm import fails | Placeholders not replaced in template | Verify `sed` replaced all three: `REALM_NAME`, `CLIENT_NAME`, `CLIENT_APP_URL` |

package/playbooks/deploy-tidecloak-docker.md

@@ -372,34 +372,38 @@ curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/toggle-iga"
   -H "Content-Type: application/x-www-form-urlencoded" \
   --data-urlencode "isIGAEnabled=true"
 
-# 5. Auto-approve client change requests (created during realm setup)
-approve_and_commit() {
-  local TYPE=$1
+# 5. Auto-approve change requests created during realm setup.
+#    Uses the current /iga/change-requests/... surface (replaces the legacy
+#    /tide-admin/change-set/... surface). During bootstrap the realm is in
+#    FirstAdmin/Tideless mode, so authorize signs server-side (no enclave).
+#    See canon/iga-change-requests-api.md.
+approve_all_pending() {
+  local TOKEN ready id
+
+  # 1. Authorize every pending CREATE/DELETE change request in one call.
   TOKEN="$(get_token)"
-  local requests=$(curl -s -X GET \
-    "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/$TYPE/requests" \
-    -H "Authorization: Bearer $TOKEN" 2>/dev/null || echo "[]")
-
-  echo "$requests" | jq -c '.[]' | while read -r req; do
-    local payload=$(jq -n \
-      --arg id "$(echo "$req" | jq -r .draftRecordId)" \
-      --arg cst "$(echo "$req" | jq -r .changeSetType)" \
-      --arg at "$(echo "$req" | jq -r .actionType)" \
-      '{changeSetId:$id,changeSetType:$cst,actionType:$at}')
-
-    # Sign then commit
+  curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests/bulk-authorize" \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/json" \
+    -d '{"actionTypeIn":["CREATE","DELETE"],"limit":100}' > /dev/null 2>&1
+
+  # 2. Commit everything that is ready. Loop 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)"
-    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/sign" \
-      -H "Authorization: Bearer $TOKEN" \
-      -H "Content-Type: application/json" -d "$payload"
-
-    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/commit" \
-      -H "Authorization: Bearer $TOKEN" \
-      -H "Content-Type: application/json" -d "$payload"
+    ready=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests?status=PENDING" \
+      -H "Authorization: Bearer $TOKEN" 2>/dev/null \
+      | jq -r '.[] | select(.readyToCommit==true) | .id' 2>/dev/null)
+    [ -z "$ready" ] && break
+    for id in $ready; do
+      TOKEN="$(get_token)"
+      curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests/$id/commit" \
+        -H "Authorization: Bearer $TOKEN" > /dev/null 2>&1
+    done
   done
 }
 
-approve_and_commit clients
+approve_all_pending
 
 # 6. Create admin user
 TOKEN="$(get_token)"
@@ -410,7 +414,7 @@ curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/users" \
 
 # 6b. Approve user creation (user is not queryable until committed with IGA enabled)
 sleep 2
-approve_and_commit users
+approve_all_pending
 
 # 6c. Assign tide-realm-admin role
 TOKEN="$(get_token)"
@@ -461,8 +465,7 @@ done
 
 # 9. Approve role assignment change requests
 sleep 2
-approve_and_commit users
-approve_and_commit roles
+approve_all_pending
 
 # 10. Update CustomAdminUIDomain for enclave approval popups
 #     CustomAdminUIDomain is OPTIONAL and APP-SPECIFIC: only needed when a separate
@@ -539,8 +542,8 @@ curl -s -X GET "$TIDECLOAK_URL/admin/realms/$REALM_NAME/vendorResources/get-inst
 | `POST /admin/realms` | Create realm from JSON template |
 | `POST /admin/realms/{realm}/vendorResources/setUpTideRealm` | Initialize Tide licensing + VRK |
 | `POST /admin/realms/{realm}/tide-admin/toggle-iga` | Enable IGA governance |
-| `POST /admin/realms/{realm}/tide-admin/change-set/sign` | Approve a change request |
-| `POST /admin/realms/{realm}/tide-admin/change-set/commit` | Commit an approved change |
+| `POST /admin/realms/{realm}/iga/change-requests/{id}/authorize` | Approve (sign) a change request. Batch: `POST /iga/change-requests/bulk-authorize`. Replaces legacy `tide-admin/change-set/sign`. |
+| `POST /admin/realms/{realm}/iga/change-requests/{id}/commit` | Commit an approved change. Replaces legacy `tide-admin/change-set/commit`. See `canon/iga-change-requests-api.md`. |
 | `POST /admin/realms/{realm}/tideAdminResources/get-required-action-link` | Generate admin invite link |
 | `GET /admin/realms/{realm}/vendorResources/get-installations-provider` | Download adapter config |
 | `POST /admin/realms/{realm}/vendorResources/sign-idp-settings` | Sign IdP settings with VRK. **ALWAYS required** after any Tide IDP config change (logo, background, backup toggle, custom admin domain, or client origin changes). Without it, the enclave rejects settings as unsigned. Requires active VRK/license. |

package/playbooks/diagnose-missing-roles-or-claims.md

@@ -93,7 +93,7 @@ function hasAnyRole(user: any, role: string): boolean {
 
 1. TideCloak Admin → Users → {user} → Role Mappings
 2. Assign role → {role-name}
-3. If IGA enabled: Approve change-set (requires quorum)
+3. If IGA enabled: authorize + commit the change request (requires quorum; see `canon/iga-change-requests-api.md`)
 4. User logout/login to get new token
 
 **Fix (default roles)**:
@@ -189,7 +189,7 @@ async function forceTokenRefresh() {
 
 ## Symptom: E2EE Role Not Working
 
-**What you see**: `doEncrypt('tag', data)` fails even though user has role.
+**What you see**: `doEncrypt([{ data, tags: ['tag'] }])` fails even though user has role.
 
 **Diagnostic**:
 

package/playbooks/initialize-admin-and-link-account.md

@@ -129,29 +129,32 @@ done
 ### Step 5: Approve user change requests
 
 ```bash
-# Reuse approve_and_commit from bootstrap-realm-from-template
-approve_and_commit() {
-  local TYPE=$1
-  TOKEN="$(get_token)"
-  local requests=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/$TYPE/requests" \
-    -H "Authorization: Bearer $TOKEN" 2>/dev/null || echo "[]")
+# Reuse approve_all_pending from bootstrap-realm-from-template.
+# Current /iga/change-requests/... surface (replaces legacy /tide-admin/change-set/...).
+# Bootstrap = FirstAdmin/Tideless: authorize signs server-side. Spec: canon/iga-change-requests-api.md.
+approve_all_pending() {
+  local TOKEN ready id
 
-  echo "$requests" | jq -c '.[]' | while read -r req; do
-    local id=$(echo "$req" | jq -r .draftRecordId)
-    local cst=$(echo "$req" | jq -r .changeSetType)
-    local at=$(echo "$req" | jq -r .actionType)
-    local payload="{\"changeSetId\":\"$id\",\"changeSetType\":\"$cst\",\"actionType\":\"$at\"}"
+  TOKEN="$(get_token)"
+  curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests/bulk-authorize" \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/json" \
+    -d '{"actionTypeIn":["CREATE","DELETE"],"limit":100}' > /dev/null 2>&1
 
+  for pass in 1 2 3 4 5; do
     TOKEN="$(get_token)"
-    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/sign" \
-      -H "Authorization: Bearer $TOKEN" \
-      -H "Content-Type: application/json" -d "$payload"
-
-    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/commit" \
-      -H "Authorization: Bearer $TOKEN" \
-      -H "Content-Type: application/json" -d "$payload"
+    ready=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests?status=PENDING" \
+      -H "Authorization: Bearer $TOKEN" 2>/dev/null \
+      | jq -r '.[] | select(.readyToCommit==true) | .id' 2>/dev/null)
+    [ -z "$ready" ] && break
+    for id in $ready; do
+      TOKEN="$(get_token)"
+      curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/iga/change-requests/$id/commit" \
+        -H "Authorization: Bearer $TOKEN" > /dev/null 2>&1
+    done
   done
 }
+approve_and_commit() { approve_all_pending; }
 
 approve_and_commit users
 approve_and_commit roles
@@ -216,7 +219,7 @@ node -e "const c=require('$ADAPTER_OUTPUT'); console.log('jwk:', !!c.jwk, 'vendo
 | "Could not find configuration for Required Action" | Tide env vars missing from container | Restart container with all required env vars |
 | `tideUserKey` never appears | Admin didn't complete the linking flow | Open invite link in browser, complete the flow |
 | Enclave popups don't work from app | CustomAdminUIDomain not set | Run Step 6 |
-| Adapter JSON missing `jwk` | IGA not enabled | Run `toggle-iga` from `bootstrap-realm-from-template` Step 5 |
+| Adapter JSON missing `jwk` | `setUpTideRealm` did not run / no `tide-vendor-key` component + EdDSA key on the realm (the `jwk` is gated on those, not on IGA) | Re-run `setUpTideRealm` from `bootstrap-realm-from-template` Step 4 and confirm it returned 200 |
 
 ---
 

package/playbooks/protect-api-nextjs.md

@@ -76,7 +76,46 @@ Any FAIL means the API route is not properly protected. Use the implementation b
 
 ---
 
-## Quick Implementation (App Router)
+## Recommended: Use the Shipped `verifyTideCloakToken` Helper
+
+Tide ships a server-side verification helper — you do not have to hand-roll JWKS verification. `@tidecloak/nextjs/server` re-exports `verifyTideCloakToken` from `@tidecloak/verify`:
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest } from 'next/server';
+import { verifyTideCloakToken } from '@tidecloak/nextjs/server';
+import tcConfig from '../../../data/tidecloak.json';
+
+export async function GET(req: NextRequest) {
+  const authHeader = req.headers.get('authorization');
+  if (!authHeader) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+  const token = authHeader.replace(/^(Bearer|DPoP) /, '');
+
+  // Signature (arg order): verifyTideCloakToken(config, token, allowedRoles=[])
+  // config is FIRST. Pass roles to enforce them; [] to just verify the token.
+  const payload = await verifyTideCloakToken(tcConfig, token, ['admin']);
+  if (!payload) {
+    // Returns false on any failure (bad signature, issuer, azp, expiry, or role).
+    return Response.json({ error: 'Forbidden' }, { status: 403 });
+  }
+  return Response.json({ users: [...] });
+}
+```
+
+`verifyTideCloakToken`:
+- verifies the signature against the adapter's embedded `jwk` (local JWKS — no network call),
+- validates the issuer (`auth-server-url` + `/realms/<realm>`) and `azp` (against `config.resource`),
+- checks time claims with a small `clockTolerance`,
+- optionally enforces `allowedRoles` (matches across `realm_access.roles` and `resource_access[client].roles`),
+- returns the decoded payload on success, `false` on failure.
+
+Prefer this for standard API protection. The manual `jose` implementation below is the **under-the-hood alternative** — use it when you need custom behavior the helper does not cover (e.g. app-side DPoP proof re-verification, separate 401-vs-403 semantics, or `iat` future-validation). See [verify-jwt-server-side.md](verify-jwt-server-side.md).
+
+---
+
+## Quick Implementation — Manual (App Router)
 
 This section creates minimal versions of `lib/auth/tidecloakConfig.ts`, `lib/auth/tideJWT.ts`, and `lib/auth/protect.ts`. If you also follow [verify-jwt-server-side.md](verify-jwt-server-side.md), its richer versions **replace** these files (adds DPoP verification, client-role checking, `extractToken`, and `iat` validation).
 

package/playbooks/protect-aspnet-core-asgard.md

@@ -0,0 +1,313 @@
+# Protect an ASP.NET Core API with TideCloak (via Tide.Asgard.AspNetCore)
+
+Wire TideCloak authentication into an ASP.NET Core resource server using the **Tide.Asgard.AspNetCore** SDK. Validates Tidecloak-issued EdDSA JWTs locally and performs RFC 8693 OAuth Token Exchange when your API needs to call another protected service.
+
+This playbook supersedes the stock `Microsoft.AspNetCore.Authentication.OpenIdConnect` approach floated in PUC-092 / PUC-093. The asgard SDK ships Tide-specific helpers (`Utils.GetEd25519IssuerKey`, `AddTokenExchange`, EdDSA `SignatureProvider`) that remove most of the manual JWKS wiring the OIDC path required.
+
+---
+
+> ## Current Status (temporary — 2026-05-14)
+>
+> The asgard .NET SDK only works against TideCloak realms where **IGA is OFF**. This is a hard constraint at present, not a recommendation.
+>
+> Implications:
+> - Use the **staging** TideCloak Docker image: `tideorg/tidecloak-stg-dev`. The non-staging dev image does not give you the auth flow the asgard SDK targets.
+> - Run the realm in **BYOiD-only mode** (license applied, IGA not toggled on). This is documented as a valid deployment mode in [canon/concepts.md](../canon/concepts.md) — "BYOiD-only (license + no IGA)".
+> - **No `tide-realm-admin` role assignment is needed** for the admin user. That role is part of the IGA quorum machinery and only relevant when IGA is on. With IGA off, normal Keycloak admin permissions are sufficient.
+> - **No `toggle-iga` call** during realm setup. Stop the canonical bootstrap order (license → IGA → E2EE) at the licence step.
+> - E2EE is not available in this mode (E2EE requires IGA). Asgard .NET today is auth + token-exchange only, so this matches the SDK's surface.
+>
+> When the SDK adds IGA support, this section will be removed and the prerequisites updated. Tracking note: [notes/asgard-dotnet-current-status.md](../notes/asgard-dotnet-current-status.md).
+
+---
+
+## When to Use
+
+- You have an ASP.NET Core (.NET 10) API that needs to validate JWTs issued by Tidecloak.
+- Your front end is a Tide-aware SPA (uses `@tidecloak/js`) and your backend is C#.
+- You need server-to-server token exchange (RFC 8693) — e.g. your API calls a downstream protected service on behalf of the user.
+
+## When NOT to Use
+
+- Your stack is Next.js / React / Vanilla JS — use [protect-api-nextjs.md](protect-api-nextjs.md) / [verify-jwt-server-side.md](verify-jwt-server-side.md) instead.
+- You need browser-side **DPoP**: the asgard `.WithDPoP(...)` registration is commented out at HEAD (see [Common Failures](#common-failures)).
+- You need to **build, sign, or test Tide Policies / contracts** server-side from .NET. The asgard .NET SDK does not include the TS `asgard-tide` wire-format library; policy signing today lives in the JS stack (`heimdall-tide` + `@tidecloak/js`).
+
+## Status classifications
+
+- `Tide.Asgard.AspNetCore.Authentication` v0.1.0 — **VERIFIED** against `sources/asgard-sdk/aspnet/Tide.Asgard.AspNetCore/Tide.Asgard.AspNetCore/`.
+- `Tide.Asgard.Core` v0.1.0 — **VERIFIED**. Provides EdDSA `SignatureProvider` over `Microsoft.IdentityModel.Tokens 8.15.0` and `BouncyCastle.Cryptography 2.6.2`.
+- `Tide.Asgard.AspNetCore.DPoP` — **OBSERVED_PATTERN**. Built and ProjectReferenced by the Example, but no `<PackageId>` is set and the registration helper `.WithDPoP(...)` is commented out. Validation primitives exist; usage requires manual service registration.
+
+---
+
+## Prerequisites
+
+- **.NET 10 SDK** (preview-tier). Every csproj pins `<TargetFramework>net10.0</TargetFramework>`.
+- TideCloak running using the **staging** Docker image (`tideorg/tidecloak-stg-dev`) — see Current Status above and [deploy-tidecloak-docker.md](deploy-tidecloak-docker.md).
+- A realm licensed via `setUpTideRealm`, with **IGA NOT toggled on** (BYOiD-only mode). Do NOT run `toggle-iga` for an asgard-.NET-backed app today.
+- An admin user able to manage the realm. **No `tide-realm-admin` role assignment is required** — that role is IGA-specific and not in play here. A standard Keycloak realm admin is sufficient.
+- The asgard repo is already vendored under `sources/asgard-sdk/` in this pack — the .NET SDK is **consumed via `<ProjectReference>`**, not NuGet. INFERRED: NuGet publication is not yet verified for `0.1.0`.
+- Your ASP.NET Core project ready to authenticate.
+
+---
+
+## Files to Inspect
+
+- `sources/asgard-sdk/aspnet/Tide.Asgard.AspNetCore/Tide.Asgard.AspNetCore.Example/Program.cs` — canonical wiring (note: README form and Example form **differ**, see Step 3).
+- `sources/asgard-sdk/aspnet/Tide.Asgard.AspNetCore/Tide.Asgard.AspNetCore/Utils.cs` — `GetEd25519IssuerKey` extension.
+- `sources/asgard-sdk/aspnet/Tide.Asgard.AspNetCore/Tide.Asgard.AspNetCore/ServiceCollectionExtensions.cs` — `AddTokenExchange` overloads.
+- `sources/asgard-sdk/aspnet/Tide.Asgard.AspNetCore/Tide.Asgard.AspNetCore/TokenExchange/TokenExchangeService.cs` — exchange implementation; only the **Bearer** path works.
+- `sources/asgard-sdk/README.md` — official .NET wiring guide (the README is exclusively about the .NET SDK; the TypeScript `asgard-tide` package is not documented there).
+
+## Files to Edit
+
+- `*.csproj` — add `<ProjectReference>` to the asgard projects.
+- `Program.cs` — register authentication and (optionally) token exchange.
+- `appsettings.json` — paste the **backend** client's adapter config under a `Keycloak` key.
+- Controllers — add `[Authorize]`; inject `ITokenExchangeService` only where needed.
+
+---
+
+## Step 1: Configure two Tidecloak clients
+
+In your realm, create one **public** client for the browser SPA and one **confidential** client for the .NET backend. The audience mapper is mandatory — without it the backend rejects browser-issued tokens with 401.
+
+| Client | Type | Settings | Why |
+|---|---|---|---|
+| `browser-login-page` | Public | Set valid redirect URIs and web origins matching your SPA host (e.g. `http://localhost:3000`). | SPA login. |
+| `backend` | Confidential | **Client authentication** ON. **Standard Token Exchange** ON (only if Step 5 needed). | Backend JWT validation + token exchange. |
+
+Then add an **Audience mapper** to the browser client:
+
+- In your realm -> Clients -> `browser-login-page` -> Client scopes -> `browser-login-page-dedicated` -> Add mapper -> By configuration -> Audience.
+- Name: `backend-mapper`. Included Client Audience: `backend`. Save.
+
+> If your realm uses Tide for user authentication, create your licence **before** creating any clients. VERIFIED (`sources/asgard-sdk/README.md` line 35).
+
+> **Do NOT toggle IGA on** for this realm. The asgard .NET SDK does not work against IGA-enabled realms today — see Current Status above. Stop the canonical bootstrap order at the licence step; skip `toggle-iga`.
+
+## Step 2: Add the asgard projects to your .NET solution
+
+Until NuGet publication is verified, vendor the asgard repo into your workspace and reference the projects directly:
+
+```xml
+<!-- Your.Api.csproj -->
+<ItemGroup>
+  <ProjectReference Include="..\asgard\aspnet\Tide.Asgard.AspNetCore\Tide.Asgard.AspNetCore\Tide.Asgard.AspNetCore.Authentication.csproj" />
+  <!-- Optional, only if you plan to register DPoP services manually -->
+  <ProjectReference Include="..\asgard\aspnet\Tide.Asgard.AspNetCore\Tide.Asgard.AspNetCore.DPoP\Tide.Asgard.AspNetCore.DPoP.csproj" />
+</ItemGroup>
+```
+
+Transitive package dependencies that get pulled in:
+
+| Package | Version | Source |
+|---|---|---|
+| `Keycloak.AuthServices.Authentication` | 2.9.0 | Authentication.csproj |
+| `Keycloak.AuthServices.Authorization` | 2.9.0 | Authentication.csproj |
+| `Microsoft.AspNetCore.Authentication.JwtBearer` | 10.0.7 | Authentication.csproj |
+| `BouncyCastle.Cryptography` | 2.6.2 | Core.csproj |
+| `Microsoft.IdentityModel.Tokens` | 8.15.0 | Core.csproj |
+
+## Step 3: Paste the backend adapter config into `appsettings.json`
+
+Download the **backend** client's adapter config: realm -> Clients -> `backend` -> top-right **Action** -> **Download adapter config**. Paste under a `Keycloak` key. The section name is fixed — `Keycloak.AuthServices` reads it by default and `AddTokenExchange(IConfiguration)` hardcodes the same name (`ServiceCollectionExtensions.cs` line 117).
+
+```json
+{
+  "Logging": { "LogLevel": { "Default": "Information", "Keycloak.AuthServices": "Debug" } },
+  "AllowedHosts": "*",
+  "Keycloak": {
+    "realm": "<your-realm>",
+    "auth-server-url": "https://<your-tidecloak-host>",
+    "ssl-required": "external",
+    "resource": "backend",
+    "credentials": { "secret": "<from-credentials-tab>" },
+    "confidential-port": 0,
+    "jwk": {
+      "keys": [
+        {
+          "kid": "<from-realm-keys>",
+          "kty": "OKP",
+          "alg": "EdDSA",
+          "use": "sig",
+          "crv": "Ed25519",
+          "x": "<base64url-public-key>"
+        }
+      ]
+    },
+    "homeOrkUrl": "https://<your-home-ork>"
+  }
+}
+```
+
+> Do not commit real client secrets. The asgard example commits a demo secret in two places (`appsettings.json` and `README.md`), which the NuGet README inherits because `Authentication.csproj` packs the root README. **Use user secrets (`dotnet user-secrets`) or environment variables in real apps.** VERIFIED footgun.
+
+## Step 4: Register authentication in `Program.cs`
+
+Use the **README form**, not the Example form. The Example `Program.cs` has the `IssuerSigningKey` line commented out (`sources/asgard-sdk/.../Example/Program.cs:17`); copying it gives you a runtime that cannot validate Tidecloak's EdDSA tokens.
+
+```csharp
+using Keycloak.AuthServices.Authentication;
+using Tide.Asgard.AspNetCore.Authentication;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddControllers();
+
+builder.Services
+    .AddKeycloakWebApiAuthentication(builder.Configuration, options =>
+    {
+        options.RequireHttpsMetadata = false; // set true in production
+        options.TokenValidationParameters.IssuerSigningKey =
+            Utils.GetEd25519IssuerKey(builder.Configuration);
+    });
+
+var app = builder.Build();
+app.UseAuthentication();
+app.UseAuthorization();
+app.MapControllers();
+app.Run();
+```
+
+What this does:
+
+- `AddKeycloakWebApiAuthentication` wires JWT Bearer validation against the `Keycloak` section.
+- `Utils.GetEd25519IssuerKey` walks `Keycloak:jwk:keys[]` for `crv=Ed25519` and returns a `SecurityKey` backed by the EdDSA `SignatureProvider` in `Tide.Asgard.Core`. Tidecloak signs tokens with EdDSA — the stock Microsoft stack does not ship EdDSA, so this step is required.
+- `GetEd25519IssuerKey` is an extension method on both `IConfiguration` (`Utils.cs:18`) and `IConfigurationSection` (`Utils.cs:25`). Either form works; the static call shown above is the most common.
+
+## Step 5: (Optional) Wire Token Exchange
+
+Only needed if your API calls another protected service on behalf of the caller. Register the service:
+
+```csharp
+builder.Services.AddTokenExchange(builder.Configuration); // reads the "Keycloak" section
+```
+
+To register multiple exchange clients in one app (e.g. one per downstream audience), use the `IConfigurationSection` overload and point each registration at a different section.
+
+Inject `ITokenExchangeService` into a controller and call `ExchangeToken`:
+
+```csharp
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Tide.Asgard.AspNetCore.Authentication.TokenExchange;
+
+[Authorize]
+[ApiController]
+[Route("[controller]")]
+public class HelloController(ITokenExchangeService exchange) : ControllerBase
+{
+    [HttpGet]
+    public async Task<IActionResult> Get()
+    {
+        var token = await exchange.ExchangeToken(
+            HttpContext.Request.Headers,
+            requestingClientId: "backend",
+            requestedAudience: "downstream-service"); // must exist as a realm client
+        return Ok(token);
+    }
+}
+```
+
+Behavioral notes:
+
+- The exchange posts `grant_type=urn:ietf:params:oauth:grant-type:token-exchange` to `protocol/openid-connect/token` and returns the new `access_token` (`TokenExchangeService.cs:42-85`).
+- The HTTP client is registered as a **singleton with the backend client secret baked into the Basic-auth header** (`ServiceCollectionExtensions.cs:91-97`). Rotating the secret requires an app restart.
+- `requestedAudience` must be a realm client. The asgard Example uses Keycloak's built-in `"account"` client as a demo; replace with a real audience.
+
+## Step 6: Protect endpoints
+
+Standard ASP.NET Core authorization. Nothing Tide-specific.
+
+```csharp
+[Authorize]
+[ApiController]
+[Route("[controller]")]
+public class SecretController : ControllerBase
+{
+    [HttpGet]
+    public IActionResult Get() => Ok($"Hello, {User.Identity?.Name}");
+}
+```
+
+For role-based authorization, use `Keycloak.AuthServices.Authorization` policies — the `Authorization` package is referenced transitively.
+
+## Step 7: SPA side (if you control it)
+
+Your SPA uses `@tidecloak/js` with the **public** client's adapter config. Reference pattern (`sources/asgard-sdk/.../Example/ClientApp/src/main.js`):
+
+```js
+import { TideCloak } from "@tidecloak/js";
+const kc = new TideCloak("keycloak.json");
+await kc.init({ onLoad: "login-required", checkLoginIframe: false });
+await kc.secureFetch(`${origin}/Secret`, {
+  headers: { Authorization: `Bearer ${kc.token}` },
+});
+```
+
+The audience mapper from Step 1 is what lets the .NET backend accept tokens issued for `browser-login-page`. If `aud` does not include `backend` you will see 401.
+
+**Do not enable `useDPoP`** in `kc.init({...})` at this point. The .NET token-exchange path crashes on DPoP-tagged requests — see [Common Failures](#common-failures).
+
+---
+
+## Verification
+
+- [ ] `Tide.Asgard.AspNetCore.Authentication.csproj` is referenced from your csproj.
+- [ ] `appsettings.json` has a `Keycloak` section with `realm`, `auth-server-url`, `resource`, `credentials.secret`, and `jwk.keys[]` containing an Ed25519 key.
+- [ ] `Program.cs` calls `AddKeycloakWebApiAuthentication` **with** `options.TokenValidationParameters.IssuerSigningKey = Utils.GetEd25519IssuerKey(...)`.
+- [ ] An unauthenticated request to a `[Authorize]` endpoint returns 401.
+- [ ] A request with a valid `Authorization: Bearer <token>` from `browser-login-page` (containing `backend` in `aud`) succeeds.
+- [ ] If Step 5 is wired: `ITokenExchangeService.ExchangeToken(...)` returns a non-empty access token for the configured audience.
+- [ ] Logs show `Keycloak.AuthServices` at Debug level emitting validation traces.
+
+---
+
+## Common Failures
+
+| Symptom | Cause | Repair |
+|---|---|---|
+| 401 with `IDX10503: Signature validation failed. Token does not have a kid` or `Unable to match keys` | Step 4's `IssuerSigningKey = Utils.GetEd25519IssuerKey(...)` line missing or commented (matches the Example, not the README) | Add the line back. See `sources/asgard-sdk/README.md:129`. |
+| 401 with `Audience validation failed` on browser-issued tokens | Audience mapper missing from `browser-login-page` | Step 1 — add `backend-mapper` to the `browser-login-page-dedicated` client scope. |
+| `NotImplementedException` thrown from `ExchangeToken` | The SPA enabled DPoP. `TokenExchangeService.cs:28-35` routes DPoP-tagged requests to `ExchangeDPoPToken`, which is a stub at line 93 | Disable `useDPoP` on the SPA (`kc.init`) until the SDK ships a DPoP-aware exchange path. |
+| `NotImplementedException` thrown from a "Doken" auth header | `ExchangeTideDoken` is a stub at `TokenExchangeService.cs:132` | Do not use the Doken auth scheme with this SDK today. |
+| Backend ignores DPoP proof on inbound requests | `.WithDPoP(...)` is commented out at `KeycloakWebApiAuthenticationBuilderExtensions.cs:33-68`; `DPoPProofValidationService` exists but is never registered | If you need DPoP today, register `DPoPProofValidationService` and the `MessageReceivedHandler` / `TokenValidationHandler` / `ChallengeHandler` event handlers manually. Or wait for the SDK to ship `.WithDPoP`. |
+| 404 on `/` when running the asgard Example cold | The SPA at `ClientApp/` is **not built by MSBuild**. Vite outputs to `wwwroot/` but `Example.csproj` has no `<Target>` running `npm run build` | Run `npm install && npm run build` in `ClientApp/` before `dotnet run`. |
+| `@tidecloak/js` cannot be resolved when running the asgard Example | `ClientApp/package.json` references `@tidecloak/js` from filesystem path `~/tidecloak-js/packages/tidecloak-js`, not npm | Clone `github.com/tide-foundation/tidecloak-js` to `~/tidecloak-js/` or update the reference to an npm version. |
+| `BadImageFormat`, target framework mismatch | Project targets a pre-net10.0 framework | Bump `<TargetFramework>net10.0</TargetFramework>` and install the .NET 10 SDK. |
+| Realm secret rotated but exchanges still use the old secret | The exchange `HttpClient` is a singleton with Basic-auth baked in at registration time (`ServiceCollectionExtensions.cs:91-97`) | Restart the app after rotation. ASSUMED: there is no hot-reload path. |
+
+---
+
+## Anti-patterns and Do Not Do This
+
+- **Do not copy the Example `Program.cs` verbatim.** The Example has `IssuerSigningKey` commented out — JWT validation will silently fail on EdDSA tokens. Use the README form.
+- **Do not commit `credentials.secret`** to source control. The asgard example does this twice for demo purposes (`appsettings.json:20`, `README.md:91`). Use `dotnet user-secrets` for development and environment variables / a secrets manager for production.
+- **Do not enable browser DPoP today.** `useDPoP` in the SPA causes every Token Exchange call to throw `NotImplementedException` (see Common Failures).
+- **Do not point `requestedAudience` at the wrong client.** It must exist as a realm client with Standard Token Exchange enabled. `"account"` works in demos because it is Keycloak's built-in client.
+- **Do not register `AddTokenExchange(IConfiguration)` for multi-client scenarios.** Use the `IConfigurationSection` overload — the `IConfiguration` form hardcodes the `"Keycloak"` section name (`ServiceCollectionExtensions.cs:117`).
+- **Do not rely on the commented-out helpers.** `UseTidecloakDashboard`, `UseTideSecuredDPoP`, `AddAutoClientCeritificationToDashboard`, `.WithDPoP` — all four are commented out at HEAD. The public type signatures (`TidecloakDashboardOptions`, `MTLSOptions`, `ClientCertificationOptions`) ship but nothing wires them.
+- **Do not assume the .NET SDK validates Tide Policies / Forseti contracts.** Policy enforcement happens on ORKs (C# Forseti contracts, see [custom-contracts.md](../canon/custom-contracts.md)). The .NET SDK only handles JWT auth and token exchange.
+- **Do not treat folder names as canonical.** The source tree contains typos that are reachable via `using` statements: `ClientCeritifcation/` (should be `ClientCertification`), `MessageRecievedHandler.cs` (should be `Received`). Grep for the wrong spelling or you will miss them.
+
+---
+
+## Repair Path
+
+If you have an existing ASP.NET Core API on TideCloak that is misbehaving:
+
+1. **JWT validation failures** — confirm `IssuerSigningKey = Utils.GetEd25519IssuerKey(...)` is present in `Program.cs`. The Microsoft default JWT handler does not ship EdDSA.
+2. **401 with audience mismatch** — confirm the SPA's client has an audience mapper to the backend client.
+3. **Token exchange throws** — confirm no DPoP / Doken auth header is being sent. Today only Bearer works.
+4. **Inbound DPoP** — confirm whether you actually need it. If yes, you are off the supported path and must register DPoP services manually (see Common Failures row). If no, ignore the `Tide.Asgard.AspNetCore.DPoP` project entirely.
+
+---
+
+## Cross-references
+
+- [add-auth-nextjs-fresh.md](add-auth-nextjs-fresh.md) — Next.js equivalent (different SDK).
+- [protect-api-nextjs.md](protect-api-nextjs.md) / [verify-jwt-server-side.md](verify-jwt-server-side.md) — Node-side JWT verification path.
+- [Step 5: Wire Token Exchange](#step-5-optional-wire-token-exchange) — RFC 8693 token exchange is the shipped path for .NET server-to-server delegation. (Browser-driven server-side delegation is an asgard feature — the `asgard-tide` Node SDK, the same one keylessh's server-delegation uses — and is unmerged/experimental, not on main, so there is no standalone server-delegation playbook.)
+- [custom-contracts.md](../canon/custom-contracts.md) — Forseti contracts; out of scope for this playbook but relevant if your .NET API is downstream of policy-governed signing.
+- [framework-matrix.md](../canon/framework-matrix.md#net--aspnet-core-via-asgard) — concise framework entry for .NET via asgard.