@tideorg/mcp 1.4.0

package/reference-apps/policy-governed-signing/bootstrap-sequence.md

@@ -0,0 +1,128 @@
+# Bootstrap Sequence — Policy-Governed Signing
+
+All steps must complete before users can safely use signing features. Order matters.
+
+## Phase 1: TideCloak infrastructure
+
+1. **Start TideCloak container**
+   - Use `tidecloak-dev` (development) or `tidecloak-stg-dev` (staging with ORK env vars).
+   - Staging requires `SYSTEM_HOME_ORK`, `USER_HOME_ORK`, `THRESHOLD_T`, `THRESHOLD_N`.
+   - Wait for readiness: `curl http://localhost:8080/health/ready` returns 200.
+
+2. **Obtain bootstrap admin token**
+   - `POST /realms/master/protocol/openid-connect/token` with `KC_BOOTSTRAP_ADMIN_USERNAME` / `KC_BOOTSTRAP_ADMIN_PASSWORD`.
+
+## Phase 2: Realm and client setup
+
+3. **Import realm template**
+   - `POST /admin/realms` with `realm.json`.
+   - Template must declare: realm name, OIDC client, `_tide_enabled` role, default-roles composite, protocol mappers.
+   - Template should include redirect URIs for all clients.
+
+4. **License the realm**
+   - `POST /admin/realms/{realm}/vendorResources/setUpTideRealm` with admin email.
+   - Content-Type: `application/x-www-form-urlencoded`. Body: `email=admin@example.com`.
+   - Returns licensing JSON as `text/plain`.
+
+5. **Enable IGA**
+   - `POST /admin/realms/{realm}/tide-admin/toggle-iga` with form-urlencoded `isIGAEnabled=true`.
+   - Must happen after licensing. Enables change-set governance for role/user mutations.
+
+## Phase 3: Approve initial change-sets
+
+6. **Approve client change-sets**
+   - IGA creates draft change-sets for client mutations during realm import.
+   - List: `GET /admin/realms/{realm}/tide-admin/change-set/clients/requests`.
+   - For each: sign (`POST .../change-set/sign`) then commit (`POST .../change-set/commit`).
+
+## Phase 4: Admin user setup
+
+7. **Create admin user**
+   - `POST /admin/realms/{realm}/users` with username, email, enabled=true.
+
+8. **Assign `tide-realm-admin` role**
+   - Get role ID: `GET /admin/realms/{realm}/clients/{realm-mgmt-client-id}/roles` and find `tide-realm-admin`.
+   - Assign: `POST /admin/realms/{realm}/users/{userId}/role-mappings/clients/{realm-mgmt-client-id}`.
+
+9. **Generate account-linking invite**
+   - `POST /admin/realms/{realm}/tideAdminResources/get-required-action-link?userId={userId}&lifespan=43200` with body `["link-tide-account-action"]`.
+   - Admin must complete this link in a browser to bind their identity to the Tide Fabric.
+
+10. **Wait for account linking**
+    - Poll `GET /admin/realms/{realm}/users/{userId}` until `attributes.tideUserKey` and `attributes.vuid` are present.
+    - Do not proceed until both attributes exist.
+
+## Phase 5: Approve user change-sets
+
+11. **Approve user change-sets**
+    - List: `GET /admin/realms/{realm}/tide-admin/change-set/users/requests`.
+    - For each: sign then commit.
+
+## Phase 6: IDP settings and adapter export
+
+12. **Configure IDP settings (optional)**
+    - Upload branding (logo, background) if desired.
+    - Set `CustomAdminUIDomain` if a separate app hosts the approval/admin UI.
+
+13. **Sign IDP settings**
+    - `POST /admin/realms/{realm}/vendorResources/sign-idp-settings`.
+    - Required after any IDP config change. Without it, the enclave rejects settings as unsigned.
+
+14. **Export adapter JSON**
+    - `GET /admin/realms/{realm}/vendorResources/get-installations-provider?clientId={clientUUID}&providerId=keycloak-oidc-keycloak-json`.
+    - Save to app config path (e.g., `data/tidecloak.json`).
+    - Verify `jwk`, `vendorId`, `homeOrkUrl`, `client-origin-auth-*` fields are present.
+    - If `jwk` is missing: IGA was not enabled before export. Re-enable IGA and re-export.
+
+## Phase 7: Signing role and policy setup (admin-driven)
+
+15. **Create signing roles**
+    - Admin creates client roles via app UI or TideCloak admin API.
+    - Role names follow app-specific prefix pattern (e.g., `ssh:<username>`).
+    - Role creation goes through IGA change-set when IGA is enabled.
+    - Approve and commit role change-sets.
+
+16. **Assign signing roles to users**
+    - Admin assigns roles to users via app UI or TideCloak admin API.
+    - Role assignment goes through IGA change-set.
+    - Approve and commit.
+
+17. **Create and approve signing policies**
+    - Admin creates a PolicySignRequest with:
+      - Forseti contract source code (C# implementing `IAccessPolicy`)
+      - Policy parameters (`Role`, `Resource`, `threshold`, `approval_type`, `execution_type`)
+      - Model ID (e.g., `BasicCustom<SSH>:BasicCustom<1>`)
+      - Contract transport (source + entry type)
+    - PolicyApproval must be signed and committed so `signed_policy_data` is populated.
+    - Until committed, signing requests for that role will fail.
+
+## Phase 8: App readiness
+
+18. **Place adapter JSON in app**
+    - Express/Node: `data/tidecloak.json`
+    - Next.js: `data/tidecloak.json`
+    - React/Vite or Vanilla: `public/tidecloak.json`
+
+19. **Configure CSP**
+    - Add `frame-src '*'` to Content-Security-Policy. Required for ORK enclave iframe.
+
+20. **Start app server**
+    - App must be able to reach TideCloak at the URL in `auth-server-url`.
+    - App must serve the redirect handler at the configured `redirectUri` path.
+    - App must serve `silent-check-sso.html` in `public/` for session refresh.
+
+## Pre-user checklist
+
+Before any user accesses signing features, verify:
+
+- [ ] TideCloak healthy (`/health/ready` returns 200)
+- [ ] Realm licensed and IGA enabled
+- [ ] At least one admin with linked Tide account
+- [ ] All pending change-sets approved and committed (clients, users, roles)
+- [ ] At least one signing role created and assigned to a user
+- [ ] Signing PolicyApproval committed with non-empty `signed_policy_data` for each role
+- [ ] Adapter JSON exported with `jwk`, `vendorId`, `homeOrkUrl`
+- [ ] `sign-idp-settings` called
+- [ ] App server running with JWT + DPoP verification on protected endpoints
+- [ ] Redirect handler present at `redirectUri` path
+- [ ] CSP includes `frame-src '*'`

package/reference-apps/policy-governed-signing/manifest.yaml

@@ -0,0 +1,78 @@
+# Policy-Governed Signing — Scenario Manifest
+
+id: policy-governed-signing
+title: Policy-Governed Signing
+category: threshold-signing
+description: Cryptographic signing authorized by Forseti contracts on the ORK network; no single entity holds the signing key
+
+frameworks:
+  - nextjs
+  - react-vite
+  - vanilla
+
+core_patterns:
+  - forseti
+  - doken
+  - dpop
+  - iga
+  - oidc
+  - threshold-signing
+  - policy-signing
+  - custom-request
+  - basic-custom-request
+  - dynamic-custom-request
+  - policy-sign-request
+  - client-roles
+  - signing
+  - ssh
+  - keyless
+
+match_keywords:
+  - policy signing
+  - threshold signing
+  - keyless ssh
+  - keyless signing
+  - ssh signing
+  - challenge signing
+  - document signing
+  - transaction signing
+  - forseti signing
+  - ork signing
+  - decentralised signing
+  - decentralized signing
+  - policy-governed
+  - sign with tide
+  - blockchain signing
+  - cryptocurrency wallet
+  - wallet signing
+  - blockchain transaction
+  - crypto wallet
+  - tide signing
+
+bootstrap_required: true
+requires_admin_preapproval: true
+requires_iga: true
+requires_e2ee: false
+signing_mode: policy-governed
+
+default_roles:
+  - _tide_enabled
+
+policy_roles: []
+
+signing_role_pattern: "<prefix>:<name>"
+
+default_playbooks:
+  - start-tidecloak-dev
+  - bootstrap-realm-from-template
+  - initialize-admin-and-link-account
+  - add-auth-nextjs-fresh
+  - protect-routes-nextjs
+  - protect-api-nextjs
+  - verify-jwt-server-side
+  - add-rbac-nextjs
+
+discriminating_question: Does the app produce cryptographic signatures (SSH challenges, document signing, transaction approval)? If the app encrypts/decrypts data instead, use an encryption scenario.
+valid_only_when: App needs ORK-mediated threshold signing, not encryption.
+
+notes: No encryption layer. Signing roles and policies are created by admin at runtime via app UI or API. Forseti contracts validate data, approvers, and executor before ORKs produce signature. Uses BasicCustomRequest or DynamicCustomRequest pattern. Replace <prefix>:<name> with app-specific pattern (e.g., ssh:root, sign:document, tx:payment).

package/reference-apps/policy-governed-signing/role-policy-matrix.md

@@ -0,0 +1,62 @@
+# Role-Policy Matrix — Policy-Governed Signing
+
+## Tide bootstrap roles
+
+| Role | Purpose | Attached policy | Created by | Approved by | Required before first use | Default / optional | Notes |
+|------|---------|----------------|------------|-------------|--------------------------|-------------------|-------|
+| `_tide_enabled` | Enables Tide operations for user | None (gate role) | Realm template | N/A (declared in realm.json) | Yes | Default | Must be in realm.json. Not auto-created. |
+| `tide-realm-admin` | Full realm administration | N/A | Bootstrap script | N/A (first admin) | Yes (at least one) | Required | Client role on `realm-management`, not a realm role. |
+
+## Signing roles (Forseti contract-backed)
+
+| Role | Purpose | Attached policy | Created by | Approved by | Required before first use | Default / optional | Notes |
+|------|---------|----------------|------------|-------------|--------------------------|-------------------|-------|
+| `<prefix>:<name>` (e.g., `ssh:root`) | Authorizes signing operations for a specific resource | Forseti contract with `signed_policy_data`; validates data, approvers, executor | Admin via app UI | Tide realm admin(s) via IGA | Yes (for that resource) | Per-resource | PolicyApproval must be committed with `signed_policy_data` before signing works for this role. |
+
+## Key rules
+
+1. `_tide_enabled` must be declared in `realm.json`. It is not auto-created by `setUpTideRealm`.
+2. Signing roles are client roles on the app's OIDC client, not realm roles.
+3. Each signing role requires a committed PolicyApproval with `signed_policy_data` before the ORKs will authorize signing for that role.
+4. Role assignment changes go through IGA change-sets when IGA is enabled. Roles appear in JWT/doken after next token refresh (up to 120s delay).
+5. `tide-realm-admin` is a client role on `realm-management`, not a realm role.
+6. The Forseti contract's `ValidateExecutor` must check that the executor's doken contains the required signing role.
+7. The Forseti contract's `ValidateApprovers` checks that approvers hold appropriate roles (e.g., `tide-realm-admin` or the signing role itself).
+8. The Forseti contract's `ValidateData` validates the data being signed (e.g., SSH challenge structure, document hash format).
+
+## Forseti contract structure
+
+The signing contract implements `IAccessPolicy` with three validators:
+
+| Validator | What it checks |
+|-----------|---------------|
+| `ValidateData` | Validates the data payload being signed. App-specific: SSH contracts parse SSHv2 publickey challenge; document contracts check hash format. |
+| `ValidateApprovers` | Checks that approvers hold the required role on the correct resource. Uses `DokenDto.WrapAll()` and `Decision.RequireAnyWithRole()`. |
+| `ValidateExecutor` | Checks that the executor's doken is not expired and holds the required signing role. Uses `Decision.RequireNotExpired()` and `Decision.RequireRole()`. |
+
+## Policy parameters
+
+Forseti contracts use `[PolicyParam]` attributes for automatic parameter binding from the policy `params` map:
+
+| Parameter | Type | Required | Purpose |
+|-----------|------|----------|---------|
+| `Role` | string | Yes | The client role required for signing (e.g., `ssh:root`) |
+| `Resource` | string | Yes | The client/resource ID for role lookup |
+| `threshold` | number | Yes | Minimum number of approvers required |
+| `approval_type` | string | Yes | `implicit` (doken-only) or `explicit` (requires operator approval popup) |
+| `execution_type` | string | Yes | `public` or `private` |
+
+## Request patterns
+
+| Pattern | Model ID format | When to use |
+|---------|----------------|-------------|
+| `BasicCustomRequest` | `BasicCustom<Name>:BasicCustom<Version>` | Data to sign is known at request creation time and does not change |
+| `DynamicCustomRequest` | `DynamicCustom<Name>:DynamicCustom<Version>` | Data to sign may change between authorization and signing |
+
+## Contract transport structure [OBSERVED_PATTERN]
+
+PolicySignRequest draft contains:
+1. Policy bytes (serialized `Policy` object)
+2. Contract transport: `[contractType("forseti"), [emptyBytes, [sourceCode, entryType("Contract")]]]`
+
+This is constructed via `TideMemory.CreateFromArray` nesting. The contract ID is the SHA-512 hash of the source code.

package/reference-apps/policy-governed-signing/scenario.md

@@ -0,0 +1,113 @@
+# Policy-Governed Signing
+
+## What this is
+
+An application where cryptographic signing operations are authorized by Forseti contracts running on the ORK network. The user authenticates via TideCloak OIDC, receives a doken, and when the app needs a signature (e.g., SSH challenge, document signing, transaction approval), the ORKs validate the request against a Forseti contract before collaboratively producing the signature.
+
+No single entity holds the signing key. The key is mathematically split across independent ORKs via threshold cryptography.
+
+## When to use this scenario
+
+Use when the user describes:
+- an app that signs data using Tide threshold cryptography
+- SSH access control with policy-based signing
+- keyless SSH or keyless signing
+- document signing with multi-admin approval
+- transaction signing governed by smart contracts
+- any app where cryptographic signatures are produced by ORKs after policy validation
+
+Do NOT use when:
+- the user needs only authentication (no signing)
+- the user needs encryption/decryption (use `organisation-password-manager` or self-encryption patterns)
+- the user describes a password manager or credential vault
+
+## Core Tide capabilities used
+
+1. **TideCloak OIDC authentication** — zero-knowledge login via threshold PRISM
+2. **DPoP token binding** — access tokens bound to device/session
+3. **Doken** — delegation token authorizing ORK-mediated operations
+4. **Forseti contracts** — C# smart contracts executed in ORK sandboxes; validate data, approvers, and executor before signing
+5. **Policy:1 auth flow** — policy-based authorization; ORKs check contract before producing signature
+6. **IGA (Identity Governance)** — role and policy changes require multi-admin approval via change-sets
+7. **BasicCustomRequest / DynamicCustomRequest** — request patterns for submitting signing operations to ORKs
+8. **PolicySignRequest** — creates signing policies with contract code, parameters, and model IDs
+9. **Client roles** — prefixed pattern (e.g., `ssh:<username>`) for per-resource access control
+
+## What must exist before first user access
+
+1. TideCloak running with a realm for the app
+2. Realm licensed (`setUpTideRealm`) and IGA enabled (`toggle-iga`)
+3. Admin user created, Tide account linked, `tide-realm-admin` role assigned
+4. Initial client and user change-sets approved and committed
+5. `sign-idp-settings` called after IDP config changes
+6. Adapter JSON exported to app (`tidecloak.json`) with `jwk`, `vendorId`, `homeOrkUrl`, `client-origin-auth-*`
+7. At least one signing role created (e.g., `ssh:<username>`) via admin UI
+8. Signing policy created, approved, and committed for each role (Forseti contract + `signed_policy_data`)
+9. App server running with JWT + DPoP verification on protected endpoints
+
+## Admin/bootstrap-only steps
+
+- Start TideCloak container
+- Import realm template
+- Call `setUpTideRealm` and `toggle-iga`
+- Create admin user and generate account-linking invite
+- Approve pending change-sets (client, user)
+- Upload branding / configure IDP settings + `sign-idp-settings`
+- Set `CustomAdminUIDomain` if a separate app hosts the approval UI
+- Export adapter JSON
+- Create signing roles via admin UI
+- Create and approve signing policies via admin UI (or policy template system)
+
+## Runtime user flow
+
+1. User visits app
+2. App redirects to TideCloak for OIDC login
+3. TideCloak authenticates via threshold PRISM (zero-knowledge)
+4. TideCloak returns access token + refresh token + doken + id token
+5. App server validates JWT (signature + claims + DPoP)
+6. When a signing operation is needed (e.g., SSH authentication):
+   - Client fetches the committed policy (`signed_policy_data`) for the target role
+   - Client creates a `BasicCustomRequest` or `DynamicCustomRequest` with the data to sign
+   - Client attaches doken as authorizer and policy bytes
+   - Client calls `createTideRequest` then `executeSignRequest`
+   - ORKs execute the Forseti contract: validate data, check approver/executor roles, enforce thresholds
+   - If policy allows, ORKs collaboratively produce the Ed25519 signature
+7. Signature exists only in client memory; signing key never materializes anywhere
+
+## Default playbook sequence
+
+1. `start-tidecloak-dev`
+2. `bootstrap-realm-from-template`
+3. `initialize-admin-and-link-account`
+4. `add-auth-nextjs-fresh` (or framework-appropriate equivalent)
+5. `protect-routes-nextjs`
+6. `protect-api-nextjs`
+7. `verify-jwt-server-side`
+8. `add-rbac-nextjs`
+
+## Key diagnostics
+
+| Symptom | Likely cause |
+|---------|-------------|
+| Login hangs or blank screen | CSP missing `frame-src '*'`, or redirect handler missing |
+| Signing fails with "No doken available" | User not authenticated, or doken expired, or `IAMService._tc` not initialized |
+| Forseti contract rejects with `PolicyDecision.Deny` | Data validation failed (check contract logic), or executor lacks required role |
+| `BadPolicy.ForbiddenCall` | Contract uses a blocked namespace (e.g., `System.IO`) |
+| `OutOfGasException` | Contract exceeds 50,000 gas limit; simplify logic |
+| Policy fetch returns null | PolicyApproval not committed, or role name mismatch |
+| Roles missing from JWT/doken | IGA change-set not committed, or token not refreshed (up to 120s delay) |
+| Adapter JSON missing `jwk` | IGA not enabled on realm before export |
+| `client-origin-auth-*` mismatch | `sign-idp-settings` not called after origin change |
+| Signature length unexpected | Check algorithm; Ed25519 signatures are 64 bytes |
+
+## Intentionally configurable
+
+- **Role naming pattern**: Apps define their own prefix (e.g., `ssh:<user>`, `sign:<resource>`, `tx:<type>`)
+- **Forseti contract logic**: Apps write custom `ValidateData`, `ValidateApprovers`, `ValidateExecutor` methods
+- **Request pattern**: Choose `BasicCustomRequest` (static data) or `DynamicCustomRequest` (data can change between auth and signing)
+- **Approval type**: Implicit (doken-only, no popup) or explicit (requires operator approval popup)
+- **Execution type**: Public or private
+- **Policy parameters**: `[PolicyParam]` attributes in the contract are filled from the policy `params` map
+- **Model ID**: Custom `BasicCustom<Name>:BasicCustom<Version>` or `DynamicCustom<Name>:DynamicCustom<Version>` patterns
+- **Approval thresholds**: IGA admin quorum and contract thresholds are deployment-configurable
+- **Contract entry type**: Must be `Contract` implementing `IAccessPolicy`

package/skills/tide-diagnostics/SKILL.md

@@ -0,0 +1,99 @@
+# Role: Learnings / Pack Curator
+
+---
+
+## Purpose
+
+Troubleshoot broken Tide integrations. Own login failures, missing roles/claims, auth errors, and finding extraction. This skill does NOT build new features — it fixes broken ones.
+
+---
+
+## Boundary
+
+| This subagent owns | Hand off to |
+|-------------------|-------------|
+| Login broken, hangs, blank screen | — |
+| Roles missing from JWT/doken | — |
+| CSP violations blocking SWE iframe | — |
+| DPoP verification failures | — |
+| Policy commit failures ("Policy supplied has not been signed") | — |
+| E2EE failures ("User has not been given any access") | — |
+| Redirect mismatch errors | — |
+| Finding extraction and learnings | — |
+| Regression test proposals | — |
+| Building new features | `tide-integration`, `tide-route-and-api-protection`, `tide-rbac-and-e2ee` |
+| Bootstrap/realm issues | `tide-setup` |
+
+---
+
+## When to Trigger
+
+- User reports login issues (hangs, blank screen, redirect loop)
+- User reports 401/403 errors on protected APIs
+- User reports missing roles or claims in JWT
+- User reports E2EE failures
+- User reports policy signing failures
+- Orchestrator detected a broken state during inspection
+- After a build session, to extract reusable learnings
+
+---
+
+## When NOT to Trigger
+
+- App has no Tide integration at all → `tide-setup` then `tide-integration`
+- User wants to add new features → route to appropriate subagent
+- User wants to set up TideCloak → `tide-setup`
+
+---
+
+## Execution
+
+### Symptom-based routing
+
+| Symptom | Likely cause | Playbook |
+|---------|-------------|----------|
+| Login hangs or blank screen | CSP missing `frame-src '*'`, redirect handler missing, DPoP auth page missing | `diagnose-broken-login` |
+| Login redirect loop | `@tidecloak/react` ESM alias missing (AP-42), provider not wired | `diagnose-broken-login` |
+| DPoP login fails | `tide_dpop_auth.html` missing or dynamic route not configured (I-12, L-07) | `diagnose-broken-login` |
+| 401 on all API calls | JWT verification not implemented, or DPoP proof missing | `diagnose-missing-roles-or-claims` |
+| 403 on API calls | Role not assigned, IGA change-set not committed, or 120s refresh delay | `diagnose-missing-roles-or-claims` |
+| Roles missing from JWT | IGA change-set not committed, token not refreshed (up to 120s) | `diagnose-missing-roles-or-claims` |
+| E2EE fails "User has not been given any access" | Self-encryption role missing, tag mismatch, IGA not approved | See T-13 in `tide-rbac-and-e2ee` |
+| Policy commit fails "Policy supplied has not been signed" | Admin policy not fetched, not base64-decoded, or wrong attachment order | See T-14 in `tide-rbac-and-e2ee` |
+| Encrypted data can't be shared | Using self-encryption instead of policy-governed (AP-24) | Route to `tide-rbac-and-e2ee` sharing gate |
+
+### Finding extraction
+
+After resolving an issue, determine whether it is:
+- **App-specific** (local machine state, one-off mistake) → do not promote to pack
+- **Reusable** (pack gap, missing guidance, wrong instruction) → create a finding note in `notes/test-findings/`
+
+For reusable findings, include:
+- What the pack implied
+- What was actually needed
+- Root cause
+- Lowest correct pack layer to patch
+- Regression test
+
+---
+
+## Handoff Trace
+
+```
+[TRACE]
+Scenario: <scenario or "diagnostics">
+Role: Learnings / Pack Curator
+Reason: <what broke | what needs extraction>
+Preconditions: Build complete or issue reported
+Next: <specialist to fix | STOP if learning-only>
+[/TRACE]
+```
+
+---
+
+## Do Not Do This
+
+- Do not treat UI gating failures as auth failures. `hasRealmRole()` / `hasClientRole()` are UX only.
+- Do not rename self-encryption roles to fix sharing failures (AP-26).
+- Do not treat policy commit failure as a role issue (T-14).
+- Do not add `createRemoteJWKSet` as a fallback when `jwk` is missing — fix the adapter export instead (I-04).

package/skills/tide-integration/SKILL.md

@@ -0,0 +1,136 @@
+# Role: Application Engineer
+
+---
+
+## Purpose
+
+Wire the Tide SDK into the application. Own SDK installation, provider setup, config loading, redirect handler, CSP, silent SSO, DPoP auth page, and webpack workarounds. This is app-level work, not infrastructure.
+
+---
+
+## Boundary
+
+| This subagent owns | Hand off to |
+|-------------------|-------------|
+| SDK install (`@tidecloak/nextjs` or `@tidecloak/react`) | — |
+| TideCloakProvider wiring with `useDPoP` in config object | — |
+| `tidecloak.json` placement and import | `tide-setup` if file doesn't exist and TideCloak not bootstrapped |
+| `silent-check-sso.html` in `public/` | — |
+| Post-auth redirect handler (`auth/redirect/page.tsx`) | — |
+| `tide_dpop_auth.html` + `next.config.ts` rewrites + DPoP headers (I-12) | — |
+| CSP (`frame-src '*'`) in `next.config` headers | — |
+| Webpack workarounds (`strictExportPresence`, `@tidecloak/react` ESM alias) | — |
+| Retrofit into existing apps | — |
+| Server-side delegation setup (`@tidecloak/server`, `createTideFetch`) | — |
+| Route/API protection | `tide-route-and-api-protection` |
+| Roles, RBAC, encryption | `tide-rbac-and-e2ee` |
+| TideCloak bootstrap, realm, licensing | `tide-setup` |
+| Login broken, diagnostics | `tide-diagnostics` |
+
+---
+
+## When to Trigger
+
+- `tide-setup` detected that SDK or provider is missing (Path A/B)
+- `tide-setup` detected hardening gaps (Path D)
+- User asks to "add Tide to my app" or "add login"
+- Orchestrator routed here after bootstrap is confirmed
+
+### Scenario-disambiguation gate (I-17)
+
+| Branch | How to resolve |
+|--------|---------------|
+| Fresh app vs existing app | Check for existing auth (NextAuth, Clerk, custom JWT) in the repo |
+| Provider missing vs not wired | Check `package.json` for SDK, layout for `TideCloakProvider` |
+| Config missing vs present | Check `data/tidecloak.json` or `public/tidecloak.json` |
+
+---
+
+## When NOT to Trigger
+
+- TideCloak is not running and not bootstrapped → `tide-setup` first
+- App already has working Tide auth (provider wired, adapter loaded, login functional) → route to `tide-route-and-api-protection` or `tide-rbac-and-e2ee`
+- Something is broken → `tide-diagnostics`
+
+---
+
+## Preconditions
+
+- TideCloak is bootstrapped and `tidecloak.json` exists with `jwk`, `vendorId`, `homeOrkUrl`
+- A Next.js (or React/Vite) project exists
+
+---
+
+## Execution
+
+### Fresh app (no auth)
+
+Follow playbook `add-auth-nextjs-fresh`:
+1. Install `@tidecloak/nextjs` (or `@tidecloak/react` for non-Next.js)
+2. Configure provider with `useDPoP` inside config object (not as JSX prop)
+3. Place `tidecloak.json` at correct path (`data/` for Next.js, `public/` for React/Vite)
+4. Create `public/silent-check-sso.html`
+5. Create post-auth redirect handler at `auth/redirect/page.tsx`
+6. Copy `tide_dpop_auth.html` to `public/` and add `rewrites()` + DPoP-specific `headers()` in `next.config.ts` (I-12). Do NOT use a route handler.
+7. Configure CSP: `frame-src '*'` in `next.config` headers (global); `script-src 'unsafe-inline'` on `/tide_dpop/:path*` only
+8. Add webpack workarounds to `next.config.ts`: `strictExportPresence = false` + `@tidecloak/react` ESM alias
+
+### Existing app (has other auth)
+
+Follow playbook `add-auth-nextjs-existing`:
+1. Same steps as fresh but preserve existing app behavior
+2. Replace existing auth provider with `TideCloakProvider`
+3. Remove old auth (NextAuth, Clerk, etc.) after Tide is working
+
+### Server-side delegation
+
+Follow playbook `setup-server-delegation`:
+1. Install `@tidecloak/server`
+2. Create `TideDelegation` singleton with TideCloak config
+3. Wire `/api/delegation` POST endpoint with `handleDelegation()`
+4. Add `requireDelegation()` middleware to admin routes
+5. Wrap browser fetch with `createTideFetch` from `@tidecloak/js`
+6. Optionally scope delegation roles via `requireDelegation({ roles: { ... } })`
+
+### Hardening gaps (from tide-setup Path D)
+
+Fix each missing item per the table in `tide-setup`.
+
+---
+
+## Verification Checklist
+
+- [ ] `@tidecloak/nextjs` (or equivalent) in `package.json`
+- [ ] `TideCloakProvider` wraps the app with `useDPoP` in config object
+- [ ] `tidecloak.json` exists with `jwk`, `vendorId`, `homeOrkUrl`
+- [ ] `public/silent-check-sso.html` exists
+- [ ] Post-auth redirect handler exists at configured `redirectUri`
+- [ ] `public/tide_dpop_auth.html` exists + `next.config.ts` has `rewrites()` for `/tide_dpop/:path*` and DPoP-specific `headers()`
+- [ ] CSP includes `frame-src '*'`
+- [ ] Webpack config has `strictExportPresence = false` + `@tidecloak/react` ESM alias
+- [ ] Login flow completes: redirect to Tide IdP -> auth -> callback -> app
+- [ ] If server-side admin calls needed: `@tidecloak/server` installed, delegation endpoints wired
+
+---
+
+## Handoff Trace
+
+```
+[TRACE]
+Scenario: <scenario>
+Role: Application Engineer
+Reason: <SDK not installed | provider not wired | config missing | hardening gaps>
+Preconditions: TideCloak bootstrapped, tidecloak.json exists
+Next: Security Engineer | STOP if integration incomplete
+[/TRACE]
+```
+
+---
+
+## Do Not Do This
+
+- Do not create ad hoc auth wiring. Follow the playbook.
+- Do not use `NEXT_PUBLIC_TIDECLOAK_*` env vars. Use `tidecloak.json` directly. (AP-38)
+- Do not pass `useDPoP` as a JSX prop. It goes inside the config object. (AP-42, session-002)
+- Do not modify `tide_dpop_auth.html`. It is integrity-checked. (I-12, L-07)
+- Do not apply `script-src 'unsafe-inline'` globally. Only on the DPoP auth route. (L-07)