@tideorg/mcp 1.4.2 → 1.9.0

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to `@tideorg/mcp` (the Tide Agent Pack) are documented here.
+
+## 1.9.0 — 2026-07-15
+
+The largest release since the pack's initial cut. It broadens the MCP from an
+*integration helper* into a *security and hosting advisor*, migrates the IGA API
+to the current surface, and adds a real pre-release quality gate. Also makes the
+pack ready to list in the Claude directory.
+
+### Highlights
+
+- **Security gap analysis** — audit an existing (even non-Tide) system and map
+  its weaknesses to Tide capabilities.
+- **Partner-hosted TideCloak via Skycloak** — a managed-hosting path alongside
+  self-hosting.
+- **IGA API migration** to `/iga/change-requests/...` (replaces the legacy
+  `/tide-admin/change-set/...`).
+- **Pre-release QA gate** (`npm test`) + GitHub Actions CI.
+- **Read-only tool annotations** and a privacy policy — Claude-directory ready.
+
+### New capabilities
+
+- **`tide_security_analysis` tool** + `tide-security-analysis` prompt. Backed by
+  `canon/security-gap-mapping.md` (SG-01 … SG-18: a trust-concentration → Tide
+  capability → remediation → honesty-note table, plus a mandatory "what Tide does
+  NOT fix" section), `canon/security-runtime-probes.md` (opt-in, authorization-
+  gated live probing), and the `tide-security-analyst` skill.
+- **`tide_hosting` tool** + `canon/hosting-options.md` and the
+  `provision-tidecloak-skycloak` playbook: self-host vs partner-hosted decision,
+  the trust model (partner-hosting is an availability/metadata trust, not an
+  integrity trust — the host can't forge tokens or decrypt data), and the
+  Skycloak provisioning API reference.
+- **`tide-mcp-qa` skill + prompt** — the QA Engineer role that runs the gate,
+  audits for overclaiming, and issues a SHIP / BLOCK verdict.
+
+The MCP now exposes **16 tools** and **5 prompts** (was 14 / 3).
+
+### Changed
+
+- **IGA change-request API** migrated to `/iga/change-requests/{id}/authorize|commit`
+  (per-id, `bulk-authorize` for batches), replacing the legacy
+  `/tide-admin/change-set/*/batch`. New authoritative reference
+  `canon/iga-change-requests-api.md`; reconciled across canon, playbooks,
+  bootstrap scripts, and reference-apps. Captures the **Tide vs Tideless** mode
+  split — IGA is cryptographic only in Tide (licensed) mode.
+- **All tools now carry `readOnlyHint` annotations** (they are read-only).
+
+### Fixed / internal
+
+- **Deterministic QA gate** (`mcp-server/test/`, `npm test`): protocol smoke
+  tests (tools/prompts present, annotated, return sane content) + content
+  consistency (no stray legacy endpoints, referenced playbooks exist, SG-01…18
+  present, GAP counts sum, manifests valid, versions in sync). **113/113.**
+- **GitHub Actions** `qa-gate.yml` runs the gate on every PR and on pushes to
+  `main`.
+- **Claude directory readiness**: `PRIVACY.md` (no data collected), corrected +
+  validated plugin manifests (`claude plugin validate` passes), version
+  reconciliation so `server.ts`, both `package.json`s, and `plugin.json` all read
+  **1.9.0**.
+- `npm run test:remote` verifies a live/hosted endpoint (tool count, annotation
+  coverage, version).
+
+### Known follow-ups (require a live stack)
+
+- **IGA bootstrap loop** (`bulk-authorize → commit`) is verified against the spec
+  but `REQUIRES_RUNTIME_VALIDATION` on a live iga-core instance. (GAP-065)
+- **Skycloak-hosted Tide vendor surface** unconfirmed — provisioning is verified,
+  but whether a hosted cluster exposes `setUpTideRealm`/IGA/adapter-with-Tide-
+  extensions must be checked on a live cluster (`scripts/skycloak-smoke.sh`).
+  (GAP-066)
+- Provisioning a **TideCloak** cluster via the Skycloak API needs the identity-
+  platform selector field confirmed with Skycloak; the documented API path
+  defaults to vanilla Keycloak.
+
+### Upgrade notes
+
+- If you script the TideCloak bootstrap, switch IGA approvals to the new
+  `/iga/change-requests/...` surface — see `canon/iga-change-requests-api.md`.
+- No changes required to app-side SDK wiring.

package/GAP_REGISTER.md

@@ -10,6 +10,7 @@ Controlled status set:
 - `RESOLVED_BY_MULTI_EXEMPLAR` — answered by consistent evidence across two or more exemplars
 - `PARTIALLY_RESOLVED_BY_KEYLESSH` — exemplar provides partial evidence; gaps remain
 - `PARTIALLY_RESOLVED_BY_MULTI_EXEMPLAR` — multiple exemplars provide partial evidence; gaps remain
+- `PARTIALLY_RESOLVED_BY_VENDOR` — vendor confirmed the direction/decision; some detail (e.g., exact payloads) still needed before full drafting
 - `STILL_UNRESOLVED` — no evidence from any source
 - `DOCS_ONLY_CONTRADICTION` — docs say one thing, implementation says another
 - `REQUIRES_RUNTIME_VALIDATION` — exemplar suggests an answer but single-app evidence is insufficient to generalize
@@ -20,7 +21,7 @@ Controlled status set:
 
 | Gap ID | Description | Status | Evidence Source | Next Action |
 |--------|------------|--------|-----------------|-------------|
-| GAP-001 | Authentication API omits all Tide-specific flows | RESOLVED_BY_VENDOR | `init-tidecloak.sh` reveals undocumented admin endpoints. `server/auth.ts` shows DPoP verification. `canon/tidecloak-endpoints.md` now documents 94 endpoints across 8 resource classes. `canon/delegation.md` documents token exchange flow. | Resolved. All Tide-specific auth endpoints documented in `canon/tidecloak-endpoints.md`. Source API docs remain incomplete but pack has full operational coverage. |
+| GAP-001 | Authentication API omits all Tide-specific flows | RESOLVED_BY_VENDOR | `init-tidecloak.sh` reveals undocumented admin endpoints. `server/auth.ts` shows DPoP verification. `canon/tidecloak-endpoints.md` now documents 94 endpoints across 8 resource classes (including the token-exchange endpoint). | Resolved. All Tide-specific auth endpoints documented in `canon/tidecloak-endpoints.md`. Source API docs remain incomplete but pack has full operational coverage. |
 | GAP-002 | Management API omits IGA endpoints | RESOLVED_BY_NORMATIVE_DOC | CHANGE_REQUEST_API.md provides complete REST API with request/response schemas for all change-set operations, policy management, TS client. | Resolved. Canon updated. |
 | GAP-003 | Quorum threshold formula inconsistency | PARTIALLY_RESOLVED_BY_KEYLESSH | `start.sh`: threshold is deployment-configurable. Three distinct concepts: admin quorum (70%), Fabric operational threshold (T/N), SSH policy threshold (per-role). | Document the three-layer distinction. CHANGE_REQUEST_API.md confirms SSH policy `threshold` is distinct from IGA admin quorum. |
 | GAP-004 | Error handling undocumented across all SDKs | RESOLVED_BY_VENDOR | No formal error code taxonomy. One custom class: `NetworkError` (extends `Error`, includes `.response`). All other errors are plain `Error` with string messages. Retryable: `NetworkError`, `enclave.networkFailure`, `enclave.throttled`, `enclave.thresholdTimeoutFailure`, `authRefreshError` (once). Fatal: init errors, input validation, missing roles (`"User has not been given any access to '${tag}'"`), policy violations (`BadPolicy.*`, `OutOfGasException`, `PolicyDecision.Deny()`), mode restrictions. Token/auth errors require re-login. Event listeners (`authError`, `authRefreshError`, `initError`) are the primary async error channel. No built-in retry logic in SDK. | Resolved. Canon updated with error catalog. Adapters pending. |
@@ -77,13 +78,15 @@ Controlled status set:
 | GAP-055 | `oauth2-dpop` npm package for DPoP verification | PARTIALLY_RESOLVED_BY_MULTI_EXEMPLAR | test-cases `dpop-protected/route.ts` uses `oauth2-dpop` package for server-side DPoP proof verification. Simpler than manual verification. | Document as alternative to manual DPoP verification in canon. |
 | GAP-056 | `deleteStatus` semantics for ACTIVE change-set records | STILL_UNRESOLVED | CHANGE_REQUEST_API.md: ACTIVE records have a `deleteStatus` field tracking pending deletion. Does deletion require the same quorum? | Needs vendor clarification. |
 | GAP-057 | Licensing change requests use different path prefix | STILL_UNRESOLVED | CHANGE_REQUEST_API.md: `GET /tideAdminResources/change-set/licensing/requests` vs `GET /tide-admin/change-set/users/requests`. Path inconsistency suggests separate implementations. | Needs clarification on whether licensing requests follow the same sign/commit flow. |
-| GAP-058 | Server-side delegation flow undocumented in pack | RESOLVED_BY_VENDOR | `@tidecloak/server` TideDelegation class, `createTideFetch`, 419 interrupt pattern, `requireDelegation()`/`handleDelegation()` middleware. Token exchange via `/protocol/openid-connect/token` with grant_type=token-exchange. Two-hop chain of trust validated by TideChainOfTrustAuthenticator (Java) and DelegationTokenSignRequest (C#). | Resolved. Canon `delegation.md` and playbook `setup-server-delegation.md` created. |
+| GAP-058 | Server-side delegation flow undocumented in pack | UNSHIPPED_REMOVED | Server-side delegation is an asgard feature (the `asgard-tide` Node SDK, as used by keylessh) + two-hop chain of trust (TideMtlsAuthenticator Java, DelegationTokenSignRequest C#); exists only on unmerged asgard/keylessh feature branches and ork `asgard-implementation`; nothing on `origin/main`. | Removed from pack 2026-07-07 — was documenting unshipped behavior. Re-document only after asgard-tide delegation merges to main. |
 | GAP-059 | TideCloak extension endpoints not comprehensively documented | RESOLVED_BY_VENDOR | 94 endpoints across 8 resource classes (VendorResource, VoucherResource, PublicResource, TideIdpResource, TideIdpAdminRealmResource, IGARealmResource, TideAdminRealmResource, PolicyResourceProvider). | Resolved. Canon `tidecloak-endpoints.md` created with full endpoint reference. |
-| GAP-060 | `@tidecloak/server` package not documented in pack | RESOLVED_BY_VENDOR | Server-side SDK for delegation exchange. Exports TideDelegation class with packRequest, exchange, generateDpopProof, requireDelegation, handleDelegation. | Resolved. Canon and playbook updated. |
-| GAP-061 | Scoped delegation (requested_roles) undocumented | RESOLVED_BY_VENDOR | `requireDelegation({ roles: { realm: [...], clients: { ... } } })` filters delegation token roles. Specified via actor_token payload. Exchange provider intersects with user's actual roles. Unlisted = excluded when roles specified. | Resolved. Canon `delegation.md` documents scoped delegation. |
+| GAP-060 | Server-side delegation SDK not documented in pack | UNSHIPPED_REMOVED | The delegation SDK is an asgard (`asgard-tide`) Node package, unmerged/experimental and unpublished; lives only on asgard/keylessh feature branches, not `main`. (There is no `@tidecloak/*` server package — that was a mis-attribution.) | Removed from pack 2026-07-07 — unshipped. |
+| GAP-061 | Scoped delegation (requested_roles) undocumented | UNSHIPPED_REMOVED | Scoped-delegation role filtering is part of the unshipped asgard (`asgard-tide`) delegation surface (feature-branch only). | Removed from pack 2026-07-07 — unshipped. |
 | GAP-062 | Custom Forseti contract creation guide missing from pack | RESOLVED_BY_VENDOR | Ork.Forseti.Sdk README, IAccessPolicy interface, DecisionBuilder, DokenDto, PolicyParam, ForsetiSdk runtime, sandbox restrictions, deployment, policy signing. | Resolved. Canon `custom-contracts.md` created. |
 | GAP-063 | No Go/REST SDK for ORK threshold signing operations | STILL_UNRESOLVED | LEARNINGS-cosign-batch-001 L-01: ORK signing (`createTideRequest` → `executeSignRequest`) only available via JS SDK. No Go, Python, or REST API for direct ORK interaction. Resolved for web apps (JS SDK); blocks CLI tools and non-JS server-side signing. | Needs vendor clarification on ORK REST API or multi-language SDK plans. |
 | GAP-064 | No CLI/terminal authentication flow (PRISM requires browser SWE iframe) | STILL_UNRESOLVED | LEARNINGS-cosign-batch-001 L-02: all TideCloak auth flows require browser context for PRISM zero-knowledge proof via SWE iframe. No device auth grant, service account, or headless flow exists. Browser-bridge (localhost page) is a workaround, not a native flow. | Needs vendor clarification on device auth grant or service account model. |
+| GAP-065 | IGA/QEA change-request API surface migrated: `/iga/change-requests/...` replaces `/tide-admin/change-set/...` | RESOLVED_BY_VENDOR | **CONFIRMED by Tide (2026-07-07)** and spec obtained (`tide-foundation/tidecloak-iga-extensions/docs/qea-iga-api.md`). iga-core's `/iga/change-requests/...` surface replaces the legacy `/tide-admin/change-set/...`. Surface: write captured as HTTP 202 + change-request `id`; per-id `POST .../{id}/authorize` (body `{}`; 409=four-eyes) → `POST .../{id}/commit` (412=under threshold/unmet dependency); `POST .../{id}/deny` (204); batch `POST /iga/change-requests/bulk-authorize` (`{actionTypeIn,limit}`, 429 mutex); `GET /iga/change-requests?status=PENDING` (objects keyed by `id`, with `entityType`/`readyToCommit`/`threshold`/`dependsOn`); Tide-mode enclave two-phase `GET`/`POST .../{id}/approval-model`; comments + `POST /iga/adopt`. Toggle unchanged (`POST /tide-admin/toggle-iga`). Two-mode split — Tide (`iga.attestor=tide`, cryptographic VRK→Midgard→ORK) vs Tideless (`iga.attestor=simple`/unset, username attestation, NO crypto). | **Resolved.** New authoritative reference `canon/iga-change-requests-api.md` created (full spec + old→new map + bootstrap authorize→commit loop). Reconciled across: `canon/feature-mapping.md`, `canon/invariants.md` (I-10), `canon/tidecloak-endpoints.md`, `canon/concepts.md`, `canon/troubleshooting.md`, `canon/tidecloak-bootstrap.md`, `canon/anti-patterns.md`, `canon/security-gap-mapping.md`; playbooks (`deploy-tidecloak-docker`, `bootstrap-realm-from-template`, `initialize-admin-and-link-account`, `setup-iga-admin-panel`, `setup-forseti-e2ee`); bootstrap scripts (`templates/*/scripts/init-tidecloak.sh`, `templates/shared/bootstrap-tidecloak.sh`); reference-apps bootstrap-sequences + `iga-admin-governance`. **Bootstrap loop is REQUIRES_RUNTIME_VALIDATION** — verify end-to-end on a live iga-core instance. Historical `notes/` and `sources/` retain the legacy surface intentionally (audit record). |
+| GAP-066 | Tide vendor surface on Skycloak-hosted TideCloak clusters unconfirmed | STILL_UNRESOLVED | `canon/hosting-options.md` + `playbooks/provision-tidecloak-skycloak.md`: Skycloak (`api.skycloak.io`, partner) offers TideCloak as a cluster identity platform, but the public docs (`skycloak.io/docs/api/`, API-Version 2026-06-01.beta) do not confirm that a hosted TideCloak cluster exposes the Tide vendor endpoints the pack's bootstrap depends on (`vendorResources/setUpTideRealm`, `tide-admin/toggle-iga`, the change-request governance API, adapter export enriched with `jwk`/`vendorId`/`homeOrkUrl`), nor how Tide licensing (Stripe free-tier flow) is handled in the hosted context. Cluster provisioning IS verified via the Skycloak API; the Tide-realm bootstrap on top is ASSUMED and must be verified on a live instance. | Verify against a live Skycloak-hosted TideCloak cluster: probe `setUpTideRealm`, confirm exported adapter has Tide extensions. If absent, Skycloak hosts the broker but Tide-realm provisioning/licensing needs the partner's Tide-specific path — raise with the Tide/Skycloak teams. |
 
 ---
 
@@ -92,22 +95,29 @@ Controlled status set:
 | Status | Count |
 |--------|-------|
 | RESOLVED_BY_KEYLESSH | 1 |
-| RESOLVED_BY_VENDOR | 33 |
+| RESOLVED_BY_VENDOR | 34 |
 | RESOLVED_BY_NORMATIVE_DOC | 3 |
 | RESOLVED_BY_MULTI_EXEMPLAR | 2 |
 | PARTIALLY_RESOLVED_BY_KEYLESSH | 4 |
 | PARTIALLY_RESOLVED_BY_MULTI_EXEMPLAR | 4 |
+| PARTIALLY_RESOLVED_BY_VENDOR | 0 |
 | RESOLVED_FOR_EVALS | 1 |
 | RESOLVED_BY_WHITEPAPER | 1 |
-| STILL_UNRESOLVED | 14 |
+| STILL_UNRESOLVED | 15 |
 | DOCS_ONLY_CONTRADICTION | 0 |
 | RESOLVED_FOR_TEMPLATES | 1 |
 | REQUIRES_RUNTIME_VALIDATION | 0 |
-| **Total** | **64** |
+| **Total** | **66** |
+
+Security-analysis sync (2026-07-06): GAP-065 added for the IGA/QEA API-surface + Tide/Tideless mode-split divergence between pack canon and current staging. Canon `security-gap-mapping.md` + `security-runtime-probes.md` and skill `tide-security-analyst` added.
+
+Hosting-integration sync (2026-07-07): GAP-066 added for the unconfirmed Tide vendor surface on Skycloak-hosted TideCloak clusters. Canon `hosting-options.md` and playbook `provision-tidecloak-skycloak.md` added.
+
+IGA API-migration sync (2026-07-07): GAP-065 reclassified STILL_UNRESOLVED → PARTIALLY_RESOLVED_BY_VENDOR → **RESOLVED_BY_VENDOR** once the iga-core spec (`qea-iga-api.md`) was obtained. New authoritative reference `canon/iga-change-requests-api.md`; the `/iga/change-requests/...` surface reconciled across canon, playbooks, bootstrap scripts, and reference-apps. Bootstrap approve→commit loop is REQUIRES_RUNTIME_VALIDATION. `PARTIALLY_RESOLVED_BY_VENDOR` status added to the controlled set (currently 0). Historical `notes/`/`sources/` intentionally retain the legacy surface.
 
 Full sync pass (2026-04-13): GAP-001 upgraded from PARTIALLY_RESOLVED_BY_KEYLESSH to RESOLVED_BY_VENDOR (all auth endpoints now documented in `canon/tidecloak-endpoints.md`). GAP-029 upgraded from PARTIALLY_RESOLVED_BY_MULTI_EXEMPLAR to RESOLVED_BY_VENDOR (`get-required-action-link` schema now documented). RESOLVED_BY_VENDOR count corrected to 32. No new gaps.
 
-Integration-focus sync (2026-04-13): 4 new gaps added (GAP-058 through GAP-061) for server-side delegation, endpoint documentation, @tidecloak/server SDK, and scoped delegation. Canon updated with `delegation.md` and `tidecloak-endpoints.md`. Playbook `setup-server-delegation.md` added. See `notes/test-findings/tidecloak-integration-focus.md`.
+Integration-focus sync (2026-04-13): 4 new gaps added (GAP-058 through GAP-061) for server-side delegation, endpoint documentation, the asgard-tide delegation SDK, and scoped delegation. Canon updated with `tidecloak-endpoints.md`. (The server-side delegation canon + playbook added in this pass were removed 2026-07-07 as unshipped; GAP-058/060/061 reopened as UNSHIPPED_REMOVED.) See `notes/test-findings/tidecloak-integration-focus.md`.
 
 Batch-01 adjudication (2026-03-25): 14 gaps resolved by vendor answers.
 Batch-02 adjudication (2026-03-25): 5 gaps resolved by vendor answers. GAP-029 strengthened. 5 assumptions resolved (A-21, A-22, A-25, A-26, A-28).

package/PRIVACY.md

@@ -0,0 +1,41 @@
+# Privacy Policy — Tide Agent Pack MCP Server (`@tideorg/mcp`)
+
+_Last updated: 2026-07-14_
+
+The Tide Agent Pack MCP server exposes read-only operational guidance (canon, playbooks, skills, prompts, scenarios) to AI coding agents. This policy explains what the server does and does not do with data.
+
+## Summary
+
+**The server collects no personal data, requires no account, stores nothing, and shares nothing with third parties.** Every tool is read-only: it reads guidance files bundled with the server and returns text. It performs no writes, no external network calls, and no tracking.
+
+## What the server processes
+
+- **Tool arguments.** Some tools accept short text arguments — a file name (e.g. `tide_canon name="invariants"`) or a free-text situation (e.g. `tide_choose_scenario situation="..."`). These arguments are used **transiently, in memory**, to select which bundled guidance to return. They are not stored, logged as content, analyzed, profiled, sold, or used to train any model.
+- **Bundled content only.** The server's responses come entirely from static files shipped with the package (`canon/`, `playbooks/`, `skills/`, `prompts/`, `reference-apps/`, `GAP_REGISTER.md`). It does not read your source code, files, or environment, and it does not fetch anything from the internet at request time.
+
+## What the server does NOT do
+
+- No user accounts, authentication of end users, or identity collection.
+- No collection of personal data or PII.
+- No persistence of tool arguments or responses.
+- No analytics, telemetry, tracking, or advertising.
+- No sharing or sale of data to third parties.
+- No use of any input for model training.
+
+## Deployment modes
+
+- **Local (stdio).** When run locally by a coding agent (the default), the server runs entirely on your machine. No data leaves your device through this server.
+- **Hosted (HTTP).** When run as a hosted HTTPS endpoint, tool arguments are sent to the server over TLS and processed in memory to select guidance. The application persists no request bodies. Standard infrastructure/operational logs at the hosting layer may record request metadata (e.g. timestamps, IP address, response codes) for reliability and abuse prevention; these contain no bundled-content responses and are subject to the hosting provider's retention. The server itself writes no such logs.
+
+## Data retention
+
+The application retains **no** user data. There is nothing to export or delete because nothing is stored.
+
+## Changes
+
+Material changes to this policy will be published in this file with an updated date.
+
+## Contact
+
+Tide Foundation — <info@tide.org>
+Source and issues: <https://github.com/tide-foundation/tide-agent-pack>

package/README.md

@@ -1,197 +1,204 @@
-# Tide Agent Pack
-
-AI coding agents that know how to implement [TideCloak](https://tidecloak.com) correctly.
-
-This MCP server gives your AI assistant deep knowledge of Tide authentication, threshold cryptography, Forseti smart contracts, and server-side security patterns. Instead of guessing, your AI follows verified playbooks.
-
-## Quick Start
-
-### Claude Code (CLI or VS Code extension)
-
-Run this one command:
-
-```bash
-claude mcp add tide-pack -- npx -y @tideorg/mcp
-```
-
-Done. Start a conversation and ask your agent to add Tide auth to your app.
-
-### Project-level config (any MCP client)
-
-Add a `.mcp.json` file to your project root:
-
-```json
-{
-  "mcpServers": {
-    "tide-pack": {
-      "command": "npx",
-      "args": ["-y", "@tideorg/mcp"]
-    }
-  }
-}
-```
-
-Works with: Claude Code, Cursor, Windsurf, Cline, and any MCP-compatible tool.
-
-### Claude Desktop
-
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
-
-```json
-{
-  "mcpServers": {
-    "tide-pack": {
-      "command": "npx",
-      "args": ["-y", "@tideorg/mcp"]
-    }
-  }
-}
-```
-
-### Cursor
-
-Open Settings > MCP Servers > Add Server:
-- Name: `tide-pack`
-- Command: `npx`
-- Args: `-y @tideorg/mcp`
-
-Or add to `.cursor/mcp.json` in your project root.
-
-### Windsurf
-
-Add to `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "tide": {
-      "url": "https://mcp.tide.org/mcp"
-    }
-  }
-}
-```
-
-Or for local: `"command": "npx", "args": ["-y", "@tideorg/mcp"]`
-
-### Zed
-
-Add to your Zed settings (`~/.config/zed/settings.json`):
-
-```json
-{
-  "context_servers": {
-    "tide": {
-      "command": {
-        "path": "npx",
-        "args": ["-y", "@tideorg/mcp"]
-      }
-    }
-  }
-}
-```
-
-Note: Zed uses `context_servers` (not `mcpServers`) and doesn't yet support remote URL-based MCP servers — use the npx command.
-
-### OpenAI Codex CLI
-
-Add to `~/.codex/config.json`:
-
-```json
-{
-  "mcpServers": {
-    "tide": {
-      "command": "npx",
-      "args": ["-y", "@tideorg/mcp"]
-    }
-  }
-}
-```
-
-Note: Codex CLI currently supports stdio-based MCP servers only — use the npx command.
-
-## What your AI can do with this
-
-Once connected, your AI assistant can:
-
-- **Add Tide auth** to a new or existing Next.js/React app
-- **Protect API routes** with server-side JWT + DPoP verification
-- **Set up role-based access** with Tide's IGA governance
-- **Deploy Forseti smart contracts** for policy-governed encryption and signing
-- **Bootstrap TideCloak** from Docker to fully configured realm
-- **Diagnose issues** like broken login, missing roles, CORS errors
-- **Follow security invariants** that prevent common auth mistakes
-
-## Try it
-
-After setup, try these prompts in your AI coding tool:
-
-> Add Tide authentication to my Next.js app
-
-> I have an existing app with auth — help me migrate to Tide
-
-> Set up encrypted data sharing between users with Tide
-
-> Help me create a Forseti contract for multi-admin approval
-
-## What's inside
-
-| Category | Count | Examples |
-|----------|-------|---------|
-| Canon doctrine | 12 files | Security invariants, anti-patterns, framework matrix, troubleshooting |
-| Playbooks | 17 step-by-step guides | Add auth, protect APIs, verify JWTs, deploy TideCloak, set up E2EE |
-| Skills | 9 composable roles | Setup, integration, security review, learning capture |
-| Scenarios | 5 reference architectures | Password manager, signing service, encrypted chat, governance panel |
-| Prompts | 4 starter prompts | Secure existing app, migrate auth, admin approval, customer portal |
-
-## Remote Server (no install required)
-
-We host the MCP server so you don't have to install anything. Just add the URL:
-
-```json
-{
-  "mcpServers": {
-    "tide": {
-      "url": "https://mcp.tide.org/mcp"
-    }
-  }
-}
-```
-
-No Node.js required. No npx. Works with any MCP client that supports remote servers.
-
-## Self-hosting
-
-Want to run your own instance? Pull from Docker Hub:
-
-```bash
-docker run -p 3000:3000 tideorg/mcp
-```
-
-Or build from source:
-
-```bash
-docker build -t tideorg/mcp .
-docker run -p 3000:3000 tideorg/mcp
-```
-
-Then point your MCP client at `http://localhost:3000/mcp`.
-
-Optional: set `API_TOKEN` environment variable to require Bearer token auth:
-
-```bash
-docker run -p 3000:3000 -e API_TOKEN=your-secret tideorg/mcp
-```
-
-## Requirements
-
-- **Remote server**: None (just an MCP client that supports remote URLs)
-- **npm/npx install**: Node.js 18+
-- **Self-hosted Docker**: Docker
-
-No TideCloak instance needed to start — the agent will guide you through setup.
-
-## Links
-
-- [TideCloak](https://tidecloak.com) — The identity platform
-- [npm package](https://www.npmjs.com/package/@tideorg/mcp) — `@tideorg/mcp`
-- [Tide Foundation](https://tide.org) — The organisation behind Tide
+# Tide Agent Pack
+
+[![MCP QA Gate](https://github.com/tide-foundation/tide-agent-pack/actions/workflows/qa-gate.yml/badge.svg)](https://github.com/tide-foundation/tide-agent-pack/actions/workflows/qa-gate.yml)
+
+AI coding agents that know how to implement [TideCloak](https://tidecloak.com) correctly.
+
+This MCP server gives your AI assistant deep knowledge of Tide authentication, threshold cryptography, Forseti smart contracts, and server-side security patterns. Instead of guessing, your AI follows verified playbooks.
+
+## Quick Start
+
+### Claude Code (CLI or VS Code extension)
+
+Run this one command:
+
+```bash
+claude mcp add tide-pack -- npx -y @tideorg/mcp
+```
+
+Done. Start a conversation and ask your agent to add Tide auth to your app.
+
+### Project-level config (any MCP client)
+
+Add a `.mcp.json` file to your project root:
+
+```json
+{
+  "mcpServers": {
+    "tide-pack": {
+      "command": "npx",
+      "args": ["-y", "@tideorg/mcp"]
+    }
+  }
+}
+```
+
+Works with: Claude Code, Cursor, Windsurf, Cline, and any MCP-compatible tool.
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "tide-pack": {
+      "command": "npx",
+      "args": ["-y", "@tideorg/mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Open Settings > MCP Servers > Add Server:
+- Name: `tide-pack`
+- Command: `npx`
+- Args: `-y @tideorg/mcp`
+
+Or add to `.cursor/mcp.json` in your project root.
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tide": {
+      "url": "https://mcp.tide.org/mcp"
+    }
+  }
+}
+```
+
+Or for local: `"command": "npx", "args": ["-y", "@tideorg/mcp"]`
+
+### Zed
+
+Add to your Zed settings (`~/.config/zed/settings.json`):
+
+```json
+{
+  "context_servers": {
+    "tide": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "@tideorg/mcp"]
+      }
+    }
+  }
+}
+```
+
+Note: Zed uses `context_servers` (not `mcpServers`) and doesn't yet support remote URL-based MCP servers — use the npx command.
+
+### OpenAI Codex CLI
+
+Add to `~/.codex/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tide": {
+      "command": "npx",
+      "args": ["-y", "@tideorg/mcp"]
+    }
+  }
+}
+```
+
+Note: Codex CLI currently supports stdio-based MCP servers only — use the npx command.
+
+## What your AI can do with this
+
+Once connected, your AI assistant can:
+
+- **Add Tide auth** to a new or existing Next.js/React app
+- **Protect API routes** with server-side JWT + DPoP verification
+- **Set up role-based access** with Tide's IGA governance
+- **Deploy Forseti smart contracts** for policy-governed encryption and signing
+- **Bootstrap TideCloak** from Docker to fully configured realm
+- **Diagnose issues** like broken login, missing roles, CORS errors
+- **Follow security invariants** that prevent common auth mistakes
+
+## Try it
+
+After setup, try these prompts in your AI coding tool:
+
+> Add Tide authentication to my Next.js app
+
+> I have an existing app with auth — help me migrate to Tide
+
+> Set up encrypted data sharing between users with Tide
+
+> Help me create a Forseti contract for multi-admin approval
+
+## What's inside
+
+| Category | Count | Examples |
+|----------|-------|---------|
+| Canon doctrine | 12 files | Security invariants, anti-patterns, framework matrix, troubleshooting |
+| Playbooks | 17 step-by-step guides | Add auth, protect APIs, verify JWTs, deploy TideCloak, set up E2EE |
+| Skills | 9 composable roles | Setup, integration, security review, learning capture |
+| Scenarios | 5 reference architectures | Password manager, signing service, encrypted chat, governance panel |
+| Prompts | 4 starter prompts | Secure existing app, migrate auth, admin approval, customer portal |
+
+## Remote Server (no install required)
+
+We host the MCP server so you don't have to install anything. Just add the URL:
+
+```json
+{
+  "mcpServers": {
+    "tide": {
+      "url": "https://mcp.tide.org/mcp"
+    }
+  }
+}
+```
+
+No Node.js required. No npx. Works with any MCP client that supports remote servers.
+
+## Self-hosting
+
+Want to run your own instance? Pull from Docker Hub:
+
+```bash
+docker run -p 3000:3000 tideorg/mcp
+```
+
+Or build from source:
+
+```bash
+docker build -t tideorg/mcp .
+docker run -p 3000:3000 tideorg/mcp
+```
+
+Then point your MCP client at `http://localhost:3000/mcp`.
+
+Optional: set `API_TOKEN` environment variable to require Bearer token auth:
+
+```bash
+docker run -p 3000:3000 -e API_TOKEN=your-secret tideorg/mcp
+```
+
+## Requirements
+
+- **Remote server**: None (just an MCP client that supports remote URLs)
+- **npm/npx install**: Node.js 18+
+- **Self-hosted Docker**: Docker
+
+No TideCloak instance needed to start — the agent will guide you through setup.
+
+## Privacy
+
+The MCP server is **read-only** and collects no data — no accounts, no telemetry, no storage, no third-party sharing. Tool arguments are used transiently in memory to select bundled guidance. See [PRIVACY.md](PRIVACY.md).
+
+## Links
+
+- [TideCloak](https://tidecloak.com) — The identity platform
+- [npm package](https://www.npmjs.com/package/@tideorg/mcp) — `@tideorg/mcp`
+- [Privacy policy](PRIVACY.md)
+- [Tide Foundation](https://tide.org) — The organisation behind Tide

package/adapters/AGENTS.md

@@ -53,7 +53,7 @@ Do not do these. Each defeats a specific invariant or creates a real vulnerabili
 - **Do not** create single-admin bypass paths around IGA. (AP-05)
 - **Do not** skip DPoP verification on protected APIs. (AP-06)
 - **Do not** store plain-text role cookies, ad hoc local auth logic, or fake auth helpers.
-- **Do not** use `IAMService` for DPoP flows — use the `TideCloak` class with `enableDpop: true`.
+- **Do not** disable DPoP. It is enabled/enforced by default. `IAMService` (the shipped singleton) supports DPoP via `useDPoP: { mode: 'strict', alg: 'ES256' }` in its config — there is no `enableDpop` flag and no separate `TideCloak` class requirement.
 - **Do not** use named ESM imports from `@tidecloak/verify` — it is CJS. Use default import with defensive interop.
 - **Do not** import `Models`, `PolicySignRequest`, `BaseTideRequest`, `ApprovalType`, or `ExecutionType` from `@tidecloak/nextjs`. That package is the Next.js integration layer only. Import `Models` from `@tideorg/js` and `PolicySignRequest` from `heimdall-tide`. Importing from `@tidecloak/nextjs` returns `undefined` at runtime.
 - **Do not** call `createTideRequest()`, `requestTideOperatorApproval()`, or `executeSignRequest()` on `IAMService`. These methods live on the underlying TideCloak instance at `IAMService._tc`. Calling them on `IAMService` throws `is not a function`.
@@ -79,6 +79,7 @@ This agent operates as a virtual development team. The **Tech Lead** decides rou
 | **IAM / Policy Engineer** | `tide-rbac-and-e2ee` | Roles, hasRealmRole vs hasClientRole, self vs shared encryption, policy signing, Forseti, IGA governance |
 | **Solutions Architect** | `tide-solutions-architect` | Pattern exploration when no existing scenario/playbook covers the request |
 | **Reviewer / QA Engineer** | `tide-reviewer` | Compliance checking, invariant validation, anti-pattern detection, scenario correctness |
+| **Security Analyst** | `tide-security-analyst` | Read-only gap analysis of an **existing** (possibly non-Tide) system; maps weaknesses to Tide capabilities. Entry point for "audit my app" / migration scoping. Runs before and independently of the build flow — reports, does not build. |
 | **Learnings / Pack Curator** | `tide-diagnostics` | Troubleshooting, finding extraction, learnings, regression proposals |
 
 ### How the Tech Lead works
@@ -238,4 +239,4 @@ These are implementation pitfalls not covered by invariants or anti-patterns. Fo
 - **Token refresh delay**: After IGA commit, roles appear in JWT/doken after next token refresh (up to 120s).
 - **`tide-realm-admin`**: Client role on `realm-management`, not a realm role.
 - **Post-auth redirect handler**: Must exist at configured `redirectUri` path. Missing handler = login appears to fail (404 after auth). See `canon/redirect-handler.md`.
-- **Version policy**: All `@tidecloak/*` packages pin to `0.13.26`. No 0.99.x. See `canon/version-policy.md`.
+- **Version policy**: All `@tidecloak/*` packages pin to `0.13.33`. No 0.99.x. See `canon/version-policy.md`.