@tideorg/mcp 1.4.1 → 1.9.0

package/skills/tide-mcp-qa/SKILL.md

@@ -0,0 +1,139 @@
+# Role: MCP QA Engineer (Pre-Release Gate)
+
+---
+
+## Purpose
+
+Decide whether the Tide MCP pack is safe to release. This role runs the deterministic test gate, then does the semantic review the gate cannot, and issues a single verdict: **SHIP**, **SHIP_WITH_WARNINGS**, or **BLOCK**. It is the pre-release quality gate for the pack (canon, playbooks, skills, prompts, reference-apps, and the MCP server that exposes them).
+
+This role is **read-only and advisory about the release**. It runs tests and reads content; it does not fix defects it finds. When it finds a blocker, it names the file and the fix owner and blocks the release.
+
+## Two layers, one verdict
+
+1. **Deterministic gate (objective, must be green).** `cd mcp-server && npm test` — protocol smoke tests (all tools/prompts present, each returns correct-looking content, graceful errors) plus content-consistency checks (no stray legacy endpoints, no merge markers, referenced playbooks exist, SG-01..SG-18 present, GAP counts sum, honesty guards present). **Any red here is an automatic BLOCK.**
+2. **Semantic review (judgment, gate can't see it).** Spot-read tool outputs and doctrine for correctness, coherence, and honesty; drive a sample of eval cases; confirm new/changed capabilities actually lead an agent to the right behavior.
+
+A release is **SHIP** only when the gate is green *and* semantic review finds no correctness/honesty blocker.
+
+---
+
+## Boundary
+
+| This role owns | Does NOT own |
+|----------------|--------------|
+| Running `npm test` and interpreting it | Fixing failing tests or defects |
+| Semantic/coherence review of tool outputs & doctrine | Writing new pack content |
+| Driving sample eval cases | Building features |
+| Honesty/overclaim audit | Changing doctrine to make a test pass |
+| The release verdict (SHIP / WARN / BLOCK) | Publishing/releasing (that's the human's call after the verdict) |
+
+**Hard rule:** never weaken a check or edit doctrine to turn a gate green. If a test is wrong, report it as a test defect; do not silence it.
+
+---
+
+## When to Trigger
+
+- Before publishing/releasing the MCP pack or the npm package.
+- After a substantial doctrine change (a reconciliation like the IGA API migration, a new capability, a merge of feature branches).
+- On demand: "QA the MCP", "is the pack ready to release", "run the release gate".
+
+## When NOT to Trigger
+
+- Building or editing pack content (that's the authoring roles).
+- Diagnosing a live TideCloak app (that's `tide-diagnostics`).
+- Security-analysing a customer system (that's `tide-security-analyst`).
+
+---
+
+## Execution
+
+### Step 1 — Run the deterministic gate
+```bash
+cd mcp-server && npm test
+```
+Record the summary line and every failing check verbatim. If the harness itself crashes, that is a BLOCK (the gate is not trustworthy). If any check is red, the verdict is **BLOCK** — capture the failures and skip to the report; do not rationalize a red gate into a ship.
+
+### Step 2 — Semantic review (only meaningful once the gate is green)
+Call the tools through the MCP server (or read the assets directly) and judge what the grep-level gate cannot:
+
+- **Correctness of guidance.** Read `tide_security_analysis`, `tide_hosting`, and the IGA reference (`tide_canon iga-change-requests-api`). Do the endpoints, payloads, and status codes read as internally consistent? Would an agent following them do the right thing?
+- **Coherence after change.** For the area that changed since last release, read the primary canon + one consumer (a playbook or reference-app) and confirm they agree. (E.g. after the IGA migration: `canon/iga-change-requests-api.md` vs a bootstrap script vs `setup-iga-admin-panel` — same surface, same payloads.)
+- **Routing.** `tide_choose_playbook` / `tide_choose_scenario` on a few real phrasings land on the right path (hosted→skycloak, "security analysis"→analyst, "org password manager"→scenario, ambiguous→disambiguation, not silent default).
+- **Honesty audit (load-bearing).** Confirm the pack does NOT overclaim:
+  - Security analysis keeps the out-of-scope section and never claims Tide fixes injection/XSS/deps (AP-SEC-1).
+  - Hosting is not sold as fully turnkey before GAP-066 (AP-HOST-2); the Tideless-IGA caveat is present.
+  - IGA "no single bypass / tamper-evident" claims are scoped to Tide mode, not Tideless.
+  - Anything marked REQUIRES_RUNTIME_VALIDATION (e.g. the IGA bootstrap loop) is flagged as such, not asserted as verified.
+
+### Step 3 — Drive sample eval cases
+Pick a representative spread from `evals/cases.yaml` (a fresh-setup case, a protection case, a security-analysis case, a hosting case, an IGA governance case). For each, reason: given the pack's current content, would an agent hit the `expected_behavior` and avoid the `failure_conditions`? Note any case the pack would now fail. (This is judgment, not execution — say so.)
+
+### Step 4 — Verdict + report
+Emit the Release Readiness Report. One verdict:
+- **SHIP** — gate green, no semantic blocker, no unmanaged overclaim.
+- **SHIP_WITH_WARNINGS** — gate green; only non-blocking issues (cosmetic, low-risk doc gaps, known REQUIRES_RUNTIME_VALIDATION items that are correctly labelled). List them.
+- **BLOCK** — any red gate check, any harness crash, any correctness or honesty defect, or a sample eval the pack would now fail. Name each blocker + the file + the fix owner (which authoring role).
+
+---
+
+## Release Readiness Report (required format)
+
+```
+# Tide MCP — Release Readiness Report
+Verdict: SHIP | SHIP_WITH_WARNINGS | BLOCK
+Scope: <what changed since last release / full pack>
+
+## Deterministic gate
+Command: cd mcp-server && npm test
+Result: <N/M passed>  (PASS/FAIL)
+Failures: <each red check verbatim, or "none">
+
+## Semantic review
+- Correctness: <observations, or "no issues">
+- Coherence (changed area): <what you cross-checked → verdict>
+- Routing: <phrasings tried → where they landed>
+- Honesty audit: <overclaim checks → pass/fail with evidence>
+
+## Sample eval cases
+<case id → would-pass / would-fail (why)>
+
+## Blockers (if any)
+1. <defect> — <file:line> — fix owner: <authoring role/skill>
+
+## Warnings (non-blocking)
+- <item, why it's acceptable to ship>
+
+## Recommendation
+<one line: release, or fix blockers then re-run the gate>
+```
+
+---
+
+## Verification (of the QA pass itself)
+
+- [ ] `npm test` was actually run this pass; its summary is quoted.
+- [ ] A red gate or harness crash was reported as BLOCK (never rationalized).
+- [ ] The honesty audit ran and its results are in the report.
+- [ ] Every blocker names a file and a fix owner.
+- [ ] No check was weakened and no doctrine was edited to pass the gate.
+
+## Anti-Patterns
+
+- **AP-QA-1** — Shipping on a red or crashed gate. The deterministic gate is a hard floor.
+- **AP-QA-2** — Editing a test or doctrine to turn a check green instead of reporting the defect. QA reports; it does not launder failures.
+- **AP-QA-3** — Skipping the honesty audit. Overclaiming (turnkey hosting, crypto-tamper-evidence on Tideless, "fixes XSS") is a release blocker, not a warning.
+- **AP-QA-4** — Reporting a green gate as SHIP without semantic review. Grep-green is necessary, not sufficient.
+- **AP-QA-5** — Treating a correctly-labelled REQUIRES_RUNTIME_VALIDATION item as a blocker. It ships as a warning; an *unlabelled* one is the blocker.
+
+## Handoff Trace
+
+```
+[TRACE]
+Scenario: pre-release QA of the Tide MCP pack
+Role: MCP QA Engineer
+Reason: <release / post-change gate>
+Preconditions: mcp-server builds; npm test runnable
+Verdict: <SHIP | SHIP_WITH_WARNINGS | BLOCK>
+Next: <release, or route blockers to named authoring roles>
+[/TRACE]
+```

package/skills/tide-rbac-and-e2ee/SKILL.md

@@ -43,7 +43,7 @@ Self-encryption (this skill) is **permanently user-bound**. It cannot be upgrade
 - App is not Tide-enabled. Route to `tide-setup` skill.
 - API routes do not verify JWT yet. Route to `tide-route-and-api-protection` skill first. RBAC on unverified tokens is meaningless.
 - User needs shared/group encryption (policy-governed VVK encryption with Forseti contracts). That is covered by playbook `setup-forseti-e2ee`, not this skill. This skill covers self-encryption only.
-- User asks about Keycloak-to-TideCloak migration. Not yet documented (GAP-023).
+- User asks about a **direct Keycloak-to-TideCloak** migration. That specific path is not yet documented (GAP-023). (Migrating an app off generic-OIDC / NextAuth / Clerk is a separate task covered by `playbooks/migrate-from-existing-auth.md`; the open gap is the KC→TideCloak realm/data migration itself.)
 
 **Early sharing detection**: If the user request mentions any of: "sharing", "share encrypted", "chosen recipients", "other users can decrypt", "cross-user decryption", "encrypt for others", "selective sharing" — route directly to `setup-forseti-e2ee`. Do NOT start with self-encryption and attempt to add sharing later. Self-encryption cannot be upgraded to shared encryption by renaming roles or changing parameters. The SDK call path must be different from the start. VERIFIED (session-001, F-07).
 
@@ -139,8 +139,8 @@ Self-encryption is user-bound. Only the encrypting user can decrypt their own da
 - [ ] Bypassing UI (direct curl) still enforces role server-side
 
 ### Self-Encryption (if applicable)
-- [ ] `doEncrypt('tag', data)` succeeds for user with `_tide_{tag}.selfencrypt` role
-- [ ] `doDecrypt('tag', ciphertext)` returns original data for same user
+- [ ] `doEncrypt([{ data, tags: ['tag'] }])` succeeds for user with `_tide_{tag}.selfencrypt` role
+- [ ] `doDecrypt([{ data: ciphertext, tags: ['tag'] }])` returns original data for same user
 - [ ] `doEncrypt` fails for user without the selfencrypt role
 - [ ] `doDecrypt` by a different user fails (expected behavior — self-encryption is user-bound; A-27 INFERRED, not runtime-confirmed)
 - [ ] Ciphertext stored in DB is not plaintext
@@ -181,8 +181,8 @@ Self-encryption is user-bound. Only the encrypting user can decrypt their own da
 
 This is a policy-flow failure, not a role issue. See T-14.
 
-1. Check admin policy was fetched from `GET /realms/{realm}/tide-policy-resources/admin-policy`
-2. Check admin policy bytes were base64-decoded before use
+1. Check admin policy was fetched (admin bearer) from `GET /admin/realms/{realm}/iga/role-policies`, reading the signed bytes from the `policy` field (the public `tide-policy-resources/admin-policy` endpoint does not exist on main)
+2. Check admin policy bytes were base64-decoded from the `policy` field before use
 3. Check `addPolicy(adminPolicyBytes)` was called after approval, not during request construction
 4. Check URL construction has no double slashes (strip trailing slash from `auth-server-url`)
 

package/skills/tide-reviewer/SKILL.md

@@ -65,7 +65,7 @@ The Reviewer is optional per-step but **mandatory before handing the app to the
 - [ ] Does `next.config.ts` have `strictExportPresence = false`? (not `reexportExportsPresence`)
 - [ ] Does `next.config.ts` have the `@tidecloak/react` ESM alias? (AP-42)
 - [ ] Does `public/tide_dpop_auth.html` exist? (I-12, L-07)
-- [ ] Does `next.config.ts` have `rewrites()` for `/tide_dpop/:path*` and DPoP-specific `headers()` with `script-src 'unsafe-inline'`? (I-12)
+- [ ] Is the DPoP auth page served by a `app/tide_dpop/[...path]/route.ts` catch-all route handler (NOT `next.config.ts` rewrites) with a sha256 hash-pinned CSP (NOT `script-src 'unsafe-inline'`) and an `Allow-CSP-From: *` header? (I-12)
 - [ ] Does `public/silent-check-sso.html` exist? (I-07)
 - [ ] Does the redirect handler exist at the configured `redirectUri`? (I-16)
 - [ ] Is CSP set to `frame-src '*'`? (I-06)

package/skills/tide-security-analyst/SKILL.md

@@ -0,0 +1,182 @@
+# Role: Security Analyst (Gap Analysis)
+
+---
+
+## Purpose
+
+Analyze an **existing** system — one that may have no Tide involvement at all — and produce an honest security gap analysis that maps concrete weaknesses to the Tide capabilities that remove them. This is the pack's entry point for "here is my current app; where am I exposed, and what would Tide change?"
+
+This role is **read-only and advisory**. It inspects and reports. It does not install Tide, write app code, or run bootstrap. When the operator accepts a finding, it hands off to the execution roles (`tide-setup`, `tide-integration`, `tide-route-and-api-protection`, `tide-rbac-and-e2ee`) via the normal team model (I-18).
+
+It is the inverse of the rest of the pack: the pack builds Tide apps; this role audits non-Tide apps and shows where Tide fits.
+
+## Two tiers: static, then runtime
+
+The analysis runs in two tiers. Do the first always; do the second only with explicit authorization.
+
+1. **Static (always)** — inspect code, config, and schema. Produces *candidate* findings, mostly tagged INFERRED. This tier never touches the running system.
+2. **Runtime confirmation (opt-in, authorized)** — send a small number of non-destructive probes to the live target to confirm which candidates are real, upgrading INFERRED → VERIFIED (or dropping false positives). Governed entirely by `canon/security-runtime-probes.md`, including a hard authorization gate and non-exploitation limits. Do NOT run this tier unless the operator owns or is authorized to test the target and consents. When in doubt, stay static-only.
+
+A static hypothesis and a runtime-confirmed finding are different strengths of evidence — never present the former as the latter.
+
+---
+
+## Boundary
+
+| This role owns | Does NOT own |
+|----------------|--------------|
+| Inspecting an existing codebase / deployment | Writing or modifying app code |
+| Identifying trust concentrations | Running TideCloak bootstrap |
+| Mapping gaps to Tide capabilities (`canon/security-gap-mapping.md`) | Installing the Tide SDK |
+| Severity triage and evidence collection | Fixing the gaps it finds |
+| Producing the gap-analysis report | Compliance review of Tide-built code (→ `tide-reviewer`) |
+| Naming the remediation playbook sequence | Executing the remediation |
+| Honestly scoping what Tide does NOT fix | Overstating Tide's coverage to close a sale |
+
+**Hard rule**: This role never claims a security property Tide provides without an evidence tag and a source. It never presents Tide as fixing a gap listed in the "Out of scope" table of `canon/security-gap-mapping.md`.
+
+---
+
+## When to Trigger
+
+- "Do a security analysis of my app / system."
+- "Where is my current auth weak?"
+- "What would Tide change about my security posture?"
+- "Audit this codebase for identity/key/authorization gaps."
+- "We're evaluating Tide — show me the gaps it would close in what we have."
+- Before a migration, to justify and scope the work (`migrate-from-existing-auth`).
+
+## When NOT to Trigger
+
+- Building a new Tide app → `tide-setup` + team model (I-18).
+- Reviewing already-written Tide code for compliance → `tide-reviewer`.
+- Diagnosing a broken Tide login → `tide-diagnostics`.
+- Full cryptographic red-team of a Tide construction → the internal `tide-crypto-redteam` skill (different surface: it attacks Tide's own crypto, this maps a customer's gaps).
+
+---
+
+## Core Doctrine
+
+1. **A gap is a named trust concentration, not a technology.** "Uses passwords" is not a finding. "Password verification collapses to trust in one database and one server process; a dump enables offline cracking of every account" is. Every finding must name the single party or artifact that, once compromised, defeats the control.
+
+2. **Evidence before claim.** Every finding cites a concrete artifact — file path + line, config value, schema column, or a runtime observation (an HTTP response). Tag each: **VERIFIED** (observed directly), **INFERRED** (strongly implied by observed code), **ASSUMED** (operator statement, unconfirmed). No evidence → not a finding, at most a question.
+
+3. **Honesty is the product.** The out-of-scope section is mandatory. Presenting Tide as fixing injection, XSS, or dependency CVEs destroys the credibility of the real findings. A visibly honest analysis is more persuasive than an inflated one. (AP-SEC-1)
+
+4. **Map to capability, not to slogans.** Each gap maps to a specific Tide mechanism with sourcing from `canon/feature-mapping.md` / `canon/invariants.md`, and to a real playbook in `playbooks/`. If no playbook exists, say so and point at `GAP_REGISTER.md` — do not improvise.
+
+5. **Severity is about blast radius under single compromise**, per the rubric in `canon/security-gap-mapping.md`. Ask: "If exactly one party here is compromised, what does the attacker get?"
+
+6. **Confirm the mode before claiming a cryptographic property.** IGA/QEA has two modes: Tide (`iga.attestor=tide`, licensed — cryptographic) and Tideless (`iga.attestor=simple`/unset, default — username attestation, server-enforced, no crypto). Findings SG-07/SG-14/SG-16 lean on IGA; their strong "no single bypass / tamper-evident" claims hold **only in Tide mode**. Never assert them for a Tideless realm. Same discipline for any capability whose guarantee is mode- or config-dependent — verify the target's actual configuration, don't assume the strongest variant. See the IGA-model note in `canon/security-gap-mapping.md`.
+
+---
+
+## Execution
+
+### Step 1 — Scope and consent
+Confirm what you may inspect (repo, running instance, config) and that you are authorized to analyze it. State the boundary: read-only, no changes. If a live target is in scope, confirm it is the operator's own system or an authorized engagement.
+
+### Step 2 — Inventory the trust architecture
+Before grepping for patterns, answer four questions from the code/config:
+- **Identity**: How are users authenticated? Where do credentials live?
+- **Authority**: How are tokens/sessions signed? Who holds the signing key?
+- **Authorization**: Where is the access decision made — client, server, or both?
+- **Data**: What sensitive data exists, and who can read it in the clear?
+
+### Step 3 — Run the static gap sweep
+Load `canon/security-gap-mapping.md`. Work through SG-01 … SG-18. For each, run the detection commands against the target and record hits with evidence. Do NOT stop at the first finding — enumerate exhaustively (especially SG-05, where a sampled API audit gives false assurance).
+
+Also collect anything matching the "Out of scope" table — you will report these separately.
+
+### Step 4 — Triage
+For each candidate gap:
+- Name the trust concentration.
+- Assign severity (CRITICAL / HIGH / MEDIUM / INFO).
+- Attach evidence with a confidence tag (mostly INFERRED at this point).
+- Note gap interactions (e.g. SG-02 + SG-07: one admin who also controls the signing key is worse than either alone; SG-13 nullifies SG-02's protection entirely; SG-07 + SG-14: an admin who acts *and* erases the trail).
+
+### Step 4b — Runtime confirmation (opt-in, only if authorized)
+If — and only if — the operator owns or is authorized to test a live target and consents, run the runtime tier per `canon/security-runtime-probes.md`. Confirm the authorization gate first. Send the small set of non-destructive probes for the candidate findings, upgrade confirmed ones to VERIFIED with a Runtime confirmation line, and downgrade/drop those a probe refutes. Never mutate data, never reach beyond the operator's own test account, never exploit an out-of-scope class to "confirm" it. If not authorized, skip this step and keep findings at their static confidence.
+
+### Step 5 — Map to Tide
+For each in-scope gap, pull the Tide replacement and remediation path from `canon/security-gap-mapping.md`. Verify each named playbook exists (`tide_list playbooks`). Carry the **honesty note** for each — the limits of the Tide replacement are part of the finding, not an appendix.
+
+### Step 6 — Report
+Emit the report in the format below. Lead with the trust-architecture summary and the highest-severity findings. Put the honest out-of-scope section in the body, not buried.
+
+### Step 7 — Hand off
+Offer the remediation sequence. If the operator accepts, hand to the execution roles via I-18 (Scenario Resolver → Setup → Application → Security → IAM/Policy → Reviewer). Do not begin remediation from this role.
+
+---
+
+## Report Format
+
+```
+# Tide Security Gap Analysis — <system name>
+Scope: <what was inspected> | Authorization: <confirmed by whom>
+Method: static (repo) | both (static + runtime) — list which SG findings were probed
+
+## Trust Architecture
+- Identity: <where credentials live>
+- Authority: <who holds signing keys>
+- Authorization: <where the decision is made>
+- Sensitive data: <what, readable by whom>
+
+## Findings (most severe first)
+### [SEVERITY] SG-XX — <title>
+- Trust concentration: <the single party/artifact>
+- Evidence: <file:line / config / HTTP obs> [VERIFIED|INFERRED|ASSUMED]
+- Runtime confirmation: <exact request → observed response> [VERIFIED]  (omit if static-only or not probed)
+- Failure scenario: <what one compromise yields>
+- Tide replacement: <mechanism> (source: canon/...)  [sourcing tag]
+- Remediation: <playbook sequence>
+- Limits: <honesty note — what this does NOT cover>
+
+## Gap Interactions
+<pairs that compound, e.g. SG-02 + SG-07>
+
+## Not Addressed by Tide (found in scope)
+<injection / XSS / deps / rate-limiting / etc., with standard remediation pointers>
+<or: "None observed in the inspected scope.">
+
+## Recommended Remediation Sequence
+1. <playbook> — closes <SG-XX>
+2. ...
+Handoff: <execution role to engage first, per I-18>
+```
+
+---
+
+## Verification
+
+This analysis is complete only when:
+- [ ] Every SG in `canon/security-gap-mapping.md` (SG-01 … SG-18) was checked (not sampled), or its non-applicability is stated.
+- [ ] Every finding names a trust concentration and carries evidence with a confidence tag.
+- [ ] Every Tide-replacement claim cites `canon/feature-mapping.md` or `canon/invariants.md`.
+- [ ] Every remediation names a playbook that actually exists.
+- [ ] The out-of-scope section is present and non-empty (or explicitly states none found).
+- [ ] No finding claims Tide fixes an out-of-scope gap class.
+- [ ] If the runtime tier ran: authorization was confirmed, every probe was non-destructive and confined to the operator's own account, and probed findings carry a Runtime confirmation line. Unprobed findings remain at their static confidence.
+
+## Anti-Patterns
+
+- **AP-SEC-1** — Presenting Tide as fixing injection/XSS/CSRF/deps/rate-limiting. Kills credibility of the real findings.
+- **AP-SEC-2** — A trust-concentration claim with no evidence artifact. Every finding needs a file, config value, or runtime observation.
+- **AP-SEC-3** — Sampling APIs instead of enumerating them (SG-05). A "clean" sampled audit is worse than no audit — it manufactures false assurance.
+- **AP-SEC-4** — Relocating a single point instead of removing it and calling it a fix. Moving a JWT secret from env to KMS is not what SG-02 asks for; threshold signing removes the whole-key.
+- **AP-SEC-5** — Overstating severity to motivate migration. Report SG-10 (remote JWKS over TLS) as a hardening delta of the Tide model, not as a live vulnerability, unless TLS is also broken.
+- **AP-SEC-6** — Beginning remediation from this role. Analyst reports; execution roles build. Do not blur the boundary.
+- Runtime-tier anti-patterns (AP-SEC-7 … AP-SEC-10) live in `canon/security-runtime-probes.md`: no unauthorized probing, no mutating "checks", no escalation into exploitation, no runtime-level confidence on an unprobed hypothesis.
+
+## Handoff Trace
+
+```
+[TRACE]
+Scenario: security gap analysis of existing (non-Tide) system
+Role: Security Analyst
+Reason: <operator requested audit / migration scoping>
+Preconditions: read-only scope confirmed, authorization confirmed
+Findings: <N gaps, severities>
+Next: <Setup / Scenario Resolver for remediation, or "report only — awaiting operator decision">
+[/TRACE]
+```

package/skills/tide-setup/SKILL.md

@@ -33,7 +33,7 @@ If multiple paths are plausible and the repo does not resolve it, ask the user b
 ## When NOT to Trigger
 
 - App already has working Tide auth (provider present, adapter JSON loaded, login functional). Proceed to route-and-api-protection or rbac-and-e2ee skill instead.
-- User is asking about migrating from Keycloak. Migration is not yet documented (GAP-023). Say so and stop.
+- User is asking about a **direct Keycloak-to-TideCloak** migration. That specific path is not yet documented (GAP-023) — say so and stop. (Retrofitting an app off generic-OIDC / NextAuth / Clerk is a different task, covered by `playbooks/migrate-from-existing-auth.md`; the open gap is the KC→TideCloak realm/data migration itself.)
 
 ---
 

package/canon/delegation.md

@@ -1,195 +0,0 @@
-# Server-Side Delegation - Canon
-
-Canonical reference for server-side admin API calls via delegation tokens.
-
-When your app server needs to call TideCloak admin APIs (manage users, roles, policies), it cannot use the browser's DPoP-bound access token. The delegation flow issues a new token bound to the server's ephemeral key.
-
----
-
-## Packages
-
-| Package | Side | Purpose |
-|---------|------|---------|
-| `@tidecloak/server` | Server | `TideDelegation` class, middleware, DPoP proof generation |
-| `@tidecloak/js` | Browser | `createTideFetch` wrapper, `signDelegationRequest`, `signDpopApproval` |
-
----
-
-## Flow: Forgetful Interrupt Pattern
-
-1. Browser calls server endpoint (e.g., `GET /api/admin/users`)
-2. Server `requireDelegation()` middleware checks cache. No cached token.
-3. Server generates ephemeral Ed25519 key, responds **419** with challenge
-4. `createTideFetch` intercepts 419, calls `IAMService.signDelegationRequest(payload)` and `IAMService.signDpopApproval(serverJkt)`
-5. Browser POSTs signed artifacts to `/api/delegation`
-6. Server `handleDelegation()` exchanges with TideCloak token endpoint
-7. TideCloak validates chain of trust, signs delegation token via ORK network
-8. Server caches delegation token, responds `{ delegated: true }`
-9. `createTideFetch` retries original request. Server finds cached token, proceeds.
-
-Subsequent requests use the cached token until it expires.
-
----
-
-## Setup
-
-### Server
-
-```js
-import { TideDelegation } from '@tidecloak/server';
-
-const delegation = new TideDelegation({
-  tidecloakUrl: process.env.TIDECLOAK_URL,
-  realm: process.env.TIDECLOAK_REALM,
-  clientId: process.env.TIDECLOAK_CLIENT_ID,
-});
-
-// Exchange endpoint
-app.post('/api/delegation', authenticate, delegation.handleDelegation());
-
-// Protected route with delegation
-app.get('/api/admin/users',
-  authenticate,
-  delegation.requireDelegation(),
-  async (req, res) => {
-    const users = await req.delegation.fetch(adminUrl + '/users');
-    res.json(users);
-  }
-);
-```
-
-### Browser
-
-```js
-import { createTideFetch } from '@tidecloak/js';
-
-const appFetch = createTideFetch(window.fetch);
-
-// Delegation is transparent
-const users = await appFetch('/api/admin/users');
-```
-
----
-
-## Scoped Delegation
-
-Limit roles in the delegation token. If `roles` is specified, only listed roles/clients appear. Everything else is stripped.
-
-```js
-// Only read role for my-app client
-delegation.requireDelegation({
-  roles: {
-    clients: { 'my-app': ['read'] }
-  }
-})
-
-// Realm + multiple clients
-delegation.requireDelegation({
-  roles: {
-    realm: ['admin'],
-    clients: {
-      'my-app': ['read', 'write'],
-      'other-app': ['view']
-    }
-  }
-})
-
-// No filtering (default)
-delegation.requireDelegation()
-```
-
-Rules:
-- Omitting `roles` entirely keeps all user roles
-- Once `roles` is specified, unlisted realms/clients are stripped
-- Cannot escalate. Requesting a role the user does not have silently drops it.
-
----
-
-## Token Exchange Endpoint
-
-The server exchanges artifacts at TideCloak's standard OIDC token endpoint:
-
-```
-POST /realms/{realm}/protocol/openid-connect/token
-```
-
-Parameters (form-encoded):
-- `grant_type`: `urn:ietf:params:oauth:grant-type:token-exchange`
-- `client_id`: app client ID
-- `subject_token`: user's access token
-- `subject_token_type`: `urn:ietf:params:oauth:token-type:access_token`
-- `actor_token`: browser-signed delegation request JWT
-- `actor_token_type`: `urn:ietf:params:oauth:token-type:jwt`
-- `dpop_approval`: session key approval of server's DPoP key
-
-Headers:
-- `DPoP`: server's DPoP proof JWT (Ed25519, contains server's public key)
-
-Response: `{ access_token, token_type: "DPoP", expires_in, issued_token_type }`
-
----
-
-## Chain of Trust
-
-Two-hop validation ensures the delegation token is legitimately authorized:
-
-**HOP 1**: `subject_token.cnf.jkt == thumbprint(BROWSER_KEY from actor_token header)`
-The browser that owns the access token is the same one that signed the delegation request.
-
-**HOP 2**: `actor_token.cnf.jkt == thumbprint(SERVER_KEY from DPoP header)`
-The delegation request authorizes the server's specific ephemeral key.
-
-Validated at two layers:
-1. TideCloak authenticator (Java) - before token is built
-2. ORK signing model (C#) - before token is threshold-signed
-
----
-
-## Using req.delegation.fetch()
-
-The `fetch` helper on `req.delegation` handles DPoP proof generation and Authorization headers:
-
-```js
-// GET
-const users = await req.delegation.fetch(url);
-
-// POST with JSON
-await req.delegation.fetch(url, { method: 'POST', body: { name: 'role' } });
-
-// PUT
-await req.delegation.fetch(url, { method: 'PUT', body: { enabled: true } });
-
-// DELETE
-await req.delegation.fetch(url, { method: 'DELETE' });
-```
-
----
-
-## Anti-Patterns
-
-- **Do not use master admin credentials** for server-side admin calls. Use delegation.
-- **Do not forward the user's browser token** to admin API. It is DPoP-bound to the browser's key.
-- **Do not skip DPoP on delegation requests**. The delegation token is DPoP-bound to the server's ephemeral key. Every admin API call needs a fresh DPoP proof with `ath` claim.
-- **Do not share delegation tokens across users**. They are cached per session ID.
-- **Do not hardcode server keys**. They are ephemeral Ed25519 keys, generated per session.
-
----
-
-## Prerequisites
-
-- TideCloak with `tide-chain-of-trust` client authenticator enabled (added by default in recent TideCloak builds)
-- `DelegationToken:1` in the VRK model whitelist (requires VRK rotation after adding)
-- DPoP enabled on the client
-- `@tidecloak/server` installed on the backend
-- `createTideFetch` wrapping fetch on the frontend
-- An `authenticate` middleware that sets `req.accessToken` from the Authorization header
-
----
-
-## Invariants
-
-- Delegation tokens are short-lived (max 600s / 10 minutes)
-- Server key is ephemeral per session, cleared when delegation cache expires
-- The browser must approve each server key via ORK enclave (DPoP approval)
-- Scoped delegation can only reduce roles, never add them
-- Delegation tokens have `act: { sub: clientId }` per RFC 8693