@tideorg/mcp 1.4.2 → 1.9.1

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

package/playbooks/setup-server-delegation.md

@@ -1,142 +0,0 @@
-# Setup Server-Side Delegation
-
-For apps where the backend needs to call TideCloak admin APIs on behalf of authenticated users.
-
----
-
-## When to Use
-
-- Your server manages users, roles, or policies via TideCloak admin API
-- You need server-side role management or access approvals
-- You want to avoid using master admin credentials from your server
-
----
-
-## Prerequisites
-
-- TideCloak bootstrapped and running
-- `tidecloak.json` exported with `jwk`, `vendorId`, `homeOrkUrl`
-- App has working Tide login (provider wired, DPoP enabled)
-- Node.js 18+ on the server (Ed25519 support)
-
----
-
-## Steps
-
-### 1. Install server SDK
-
-```bash
-npm install @tidecloak/server
-```
-
-### 2. Create delegation instance
-
-```ts
-// server/lib/delegation.ts
-import { TideDelegation } from '@tidecloak/server';
-
-let _delegation: TideDelegation | null = null;
-
-export function getDelegation(): TideDelegation {
-  if (!_delegation) {
-    _delegation = new TideDelegation({
-      tidecloakUrl: process.env.TIDECLOAK_URL || config['auth-server-url'],
-      realm: process.env.TIDECLOAK_REALM || config.realm,
-      clientId: process.env.TIDECLOAK_CLIENT_ID || config.resource,
-    });
-  }
-  return _delegation;
-}
-```
-
-Use a lazy singleton. Do not create a new instance per request.
-
-### 3. Wire delegation exchange endpoint
-
-```ts
-app.post('/api/delegation', authenticate, getDelegation().handleDelegation());
-```
-
-This endpoint receives signed delegation artifacts from the browser and exchanges them with TideCloak for a delegation token.
-
-### 4. Add delegation middleware to admin routes
-
-```ts
-app.get('/api/admin/users',
-  authenticate,
-  requireAdmin,
-  getDelegation().requireDelegation(),
-  async (req, res) => {
-    const adminUrl = `${tidecloakUrl}/admin/realms/${realm}`;
-    const users = await req.delegation.fetch(`${adminUrl}/users`);
-    res.json(users);
-  }
-);
-```
-
-The middleware:
-- Checks if a cached delegation token exists for this user session
-- If yes: attaches `req.delegation` with `token` and `fetch()` helper
-- If no: responds 419 with a delegation challenge
-
-### 5. Wrap browser fetch with createTideFetch
-
-```ts
-import { createTideFetch } from '@tidecloak/js';
-
-// Wrap the app's fetch function
-const appFetch = createTideFetch(window.fetch);
-
-// Use appFetch for all server calls that may need delegation
-const users = await appFetch('/api/admin/users');
-```
-
-`createTideFetch` intercepts 419 responses, handles the delegation signing flow with the browser's DPoP key, and retries the original request.
-
-### 6. Optional: scope delegation roles
-
-```ts
-// Only include specific roles in the delegation token
-getDelegation().requireDelegation({
-  roles: {
-    realm: ['admin'],
-    clients: { 'my-app': ['manage-users'] }
-  }
-})
-```
-
-If `roles` is specified, only listed roles appear in the delegation token. Unlisted realms/clients are stripped. Cannot add roles the user does not have.
-
----
-
-## Verification
-
-- [ ] `@tidecloak/server` in server package.json
-- [ ] `/api/delegation` POST route wired with `handleDelegation()`
-- [ ] Admin routes use `requireDelegation()` middleware
-- [ ] Browser uses `createTideFetch` wrapper
-- [ ] Admin API calls succeed: user list, role management, etc.
-- [ ] 419 responses are handled transparently (no user-visible interruption)
-- [ ] Delegation token is cached (no 419 on every request)
-
----
-
-## Troubleshooting
-
-**Repeated 419 responses**
-Check that `/api/delegation` is wired correctly and the `authenticate` middleware sets `req.accessToken`.
-
-**"No pending delegation challenge"**
-Server restarted between 419 and delegation POST. Browser retries automatically.
-
-**"Delegation exchange failed"**
-Check TideCloak has `tide-chain-of-trust` client authenticator enabled and `DelegationToken:1` in VRK model whitelist. A VRK rotation is needed after adding the model ID.
-
-**"DPoP is not initialized"**
-`signDelegationRequest` needs the DPoP provider. Ensure `useDPoP` is in the TideCloakProvider config object.
-
-**Delegation token has wrong roles**
-If using scoped delegation, everything not listed is excluded. Omit `roles` for full permissions.
-
-**Admin API returns 403**
-The user does not have the required role (e.g., `tide-realm-admin` on `realm-management`). Delegation can only use roles the user already has.