@tideorg/mcp 1.4.0 → 1.4.2

package/GAP_REGISTER.md

@@ -43,7 +43,7 @@ Controlled status set:
 | GAP-021 | Ragnarok post-transition details | STILL_UNRESOLVED | No exemplar implements Ragnarok. | Still needs transition plan. |
 | GAP-022 | C# SDK lacks Tide-specific content | PARTIALLY_RESOLVED_BY_MULTI_EXEMPLAR | Three contracts across two exemplars demonstrate comprehensive C# API surface: `IAccessPolicy`, `DataContext`, `ExecutorContext`, `ApproversContext`, `PolicyDecision`, `DokenDto`, `DokenDto.WrapAll()`, `Decision.*`, `TideKey.From()`, `Utils.GetEpochSeconds()`, `ExecutionType`, `ApprovalType`. | Not a standalone SDK package — types are available only within Forseti contract context. |
 | GAP-023 | Keycloak-to-TideCloak migration path | STILL_UNRESOLVED | No exemplar is a migration. All are greenfield. | Still needs migration guide. |
-| GAP-024 | Multi-tenant / multi-realm Fabric interaction | STILL_UNRESOLVED | All exemplars use single realm. tidewarden uses org-scoped roles (`org:{uuid}:role`) but still single realm. | Still needs multi-tenancy docs. |
+| GAP-024 | Multi-tenant / multi-realm Fabric interaction | RESOLVED_BY_MULTI_EXEMPLAR | Ratidefy SaaS (ratidefy.com) implements full multi-tenant with per-tenant realms. Two-phase provisioning: realm+user first, role assignment after Tide account link. Path-based routing (`/t/<slug>/`). Each tenant gets independent VVK, Forseti policies, and IGA. Dynamic adapter config served from DB. Key learnings: client-origin-auth key format, IDP signing requirement, role assignment ordering. | Resolved. `canon/tidecloak-bootstrap.md` updated with "Hosted / SaaS Multi-Tenant Provisioning" section. |
 | GAP-025 | VVK ORK 12-gate verification details | STILL_UNRESOLVED | No exemplar reveals gate list. | Still needs full gate list and error behavior. |
 | GAP-026 | Adapter JSON field documentation | RESOLVED_BY_KEYLESSH | `tidecloakConfig.ts` TypeScript interface. forseti-crypto-quickstart provides additional field: `client-origin-auth-*` (signed origin binding). | Record as canon. Additional field `client-origin-auth-*` noted (GAP-048). |
 | GAP-027 | Production deployment guide | PARTIALLY_RESOLVED_BY_KEYLESSH | keylessh `DEPLOYMENT.md` shows container patterns. tidewarden shows Docker multi-stage builds + Dockerfile.acr for ACR. | Extract reusable patterns. Full checklist still needed. |

package/README.md

@@ -1,38 +1,197 @@
-# Tide Agent Pack
-
-This repo turns Tide source material into operational assets for AI coding agents.
-
-## Goal
-
-Help coding agents implement Tide correctly for low-experience builders.
-
-## Primary outputs
-
-- canon doctrine
-- implementation playbooks
-- agent adapters
-- skills
-- starter prompts
-- starter templates
-- eval cases
-
-## Source policy
-
-Put copied authoritative material in `sources/`.
-Do not rely on drifting live docs during drafting.
-Mark content as:
-- `VERIFIED`
-- `INFERRED`
-- `ASSUMED`
-
-## Drafting order
-
-1. `notes/source-audit.md`
-2. `canon/*`
-3. `playbooks/*`
-4. `adapters/*`
-5. `skills/*`
-6. `prompts/*`
-7. `templates/*`
-8. `evals/cases.yaml`
-9. `GAP_REGISTER.md`
+# 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

package/canon/tidecloak-bootstrap.md

@@ -243,6 +243,70 @@ The bootstrap/init script must check the HTTP status of every critical step and
 
 ---
 
+## Hosted / SaaS Multi-Tenant Provisioning
+
+When bootstrapping realms programmatically on a hosted TideCloak instance (e.g., `login.dauth.me`) for a multi-tenant SaaS application, the same initialization sequence applies but with critical differences. VERIFIED (Ratidefy SaaS, ratidefy.com).
+
+### Two-Phase Provisioning
+
+Role assignment MUST happen after the admin user links their Tide account. IGA change requests require a Tide doken to be signable. Without a linked identity, the sign endpoint returns 200 but the change-set remains in DRAFT permanently.
+
+**Phase A** (automated, before user interaction):
+Steps 1–9 from the standard sequence, EXCEPT step 8c (role assignment). Generate the invite link at the end.
+
+**Phase B** (after user links Tide account via invite link):
+Step 8c (assign role) → Step 11 (approve role change-sets).
+
+**Anti-pattern:** Assigning `tide-realm-admin` before the user links their Tide account. Creates an unsignable DRAFT change request. The only recovery is to delete the draft and re-assign after linking. VERIFIED.
+
+### client-origin-auth Key Format
+
+The adapter config exported from TideCloak includes keys like:
+```
+"client-origin-auth-https://myapp.example.com": "E1Kaff...=="
+```
+
+The **origin URL is part of the key name**, not just metadata. When storing adapter config fields in a database for dynamic serving, preserve the full key name. Storing only the value produces invalid config that causes `[HEIMDALL] Client origin could not be verified`.
+
+**Correct storage format** (e.g., JSON column):
+```json
+{ "key": "client-origin-auth-https://myapp.example.com", "value": "E1Kaff...==" }
+```
+
+VERIFIED.
+
+### IDP Settings Signing
+
+After setting `CustomAdminUIDomain` on the Tide IDP, you MUST call:
+```
+POST /admin/realms/{realm}/vendorResources/sign-idp-settings
+```
+
+Without this step, the Tide enclave rejects all signing/encryption requests from the configured origin with `Client origin could not be verified`. The sign step cryptographically binds the IDP settings to the ORK network. VERIFIED.
+
+### Path-Based vs Subdomain Tenant Routing
+
+If using path-based routing (`myapp.com/t/<tenant>/`) instead of subdomains (`tenant.myapp.com`):
+- Set redirect URIs on the **root domain** (`https://myapp.com/*`), not per-tenant subdomains
+- `CustomAdminUIDomain` must be the root domain (`https://myapp.com`)
+- The `client-origin-auth` key will reference the root domain
+
+Subdomain routing requires a wildcard SSL certificate. Azure App Service managed certs do not support wildcards — use path-based routing or Azure Front Door. VERIFIED.
+
+### JWT kid Requirement
+
+Some TideCloak realm configurations produce JWTs with missing `kid` (Key ID) in the header. The standard Keycloak admin REST API requires `kid` to verify token signatures. Tokens without `kid` cause 401 on all admin API calls even with valid roles.
+
+**Symptom**: Token has all admin roles (`realm-admin`, `manage-users`, etc.) but admin API returns `{"error":"HTTP 401 Unauthorized"}`. TideCloak logs: `kid is null, cant find public key: realm={0}`.
+
+**Fix**: Recreate the realm. The `kid` issue is a realm configuration problem, not a token issue. VERIFIED.
+
+### DPoP on Hosted Instances
+
+DPoP (`useDPoP: { mode: 'strict', alg: 'EdDSA' }`) may not be supported on all hosted TideCloak instances. Enabling DPoP on `login.dauth.me` caused 500 on the token endpoint. Do not enable DPoP unless confirmed supported by the hosting provider. Standard `secureFetch` without DPoP works for admin API calls when the token has a valid `kid`. VERIFIED.
+
+---
+
 ## Data Directory Rules
 
 - Mount `./data:/opt/keycloak/data/h2`, never the project root.

package/canon/troubleshooting.md

@@ -1492,3 +1492,89 @@ VERIFIED (TIDE_LEARNINGS-001 L-11).
 **Verification**: After fixing the server error, the request returns 200 with proper CORS headers.
 
 VERIFIED (LEARNINGS-ratidefy-batch-001 L-15).
+
+---
+
+## T-20: Admin API Returns 401 Despite Valid Roles (Missing JWT kid)
+
+**Symptom**: Token has all admin roles (`realm-admin`, `manage-users`, `view-users`, etc.), token is not expired, but admin REST API returns `{"error":"HTTP 401 Unauthorized"}`. TideCloak logs show `kid is null, cant find public key: realm={0}`.
+
+**Possible Causes**:
+1. JWT header has no `kid` field — realm's EdDSA signing key configuration is broken
+2. Token signed with ORK threshold EdDSA but no `kid` reference for admin API to look up the verification key
+
+**Diagnostics**:
+
+```bash
+# Decode the JWT header
+echo '<token>' | cut -d. -f1 | base64 -d 2>/dev/null | jq .
+# If output shows {"alg":"EdDSA","typ":"JWT"} with NO "kid" field — that's the problem
+```
+
+**Fix**: Recreate the TideCloak realm. The `kid` issue is a realm-level configuration problem that cannot be fixed on existing tokens. A new realm will issue tokens with proper `kid` in the JWT header.
+
+**Verification**: After recreating the realm, decode a new token's header — it should include `"kid": "some-key-id"`.
+
+VERIFIED (Ratidefy SaaS — ratidefy-sign realm had missing kid, recreated as ratidefy-sign-2).
+
+---
+
+## T-21: Enclave Error "Client origin could not be verified"
+
+**Symptom**: Tide enclave popup appears and immediately closes. Browser console shows `[HEIMDALL] Recieved enclave error: Client origin could not be verified`.
+
+**Possible Causes**:
+1. `CustomAdminUIDomain` not set on Tide IDP
+2. IDP settings not signed after setting `CustomAdminUIDomain`
+3. `client-origin-auth` key in adapter config is malformed or missing the origin URL
+
+**Diagnostics**:
+
+```bash
+# Check CustomAdminUIDomain
+TOKEN=$(curl -s -X POST "$TC_URL/realms/master/protocol/openid-connect/token" \
+  -d "username=admin&password=$PASS&grant_type=password&client_id=admin-cli" | jq -r .access_token)
+curl -s "$TC_URL/admin/realms/$REALM/identity-provider/instances/tide" \
+  -H "Authorization: Bearer $TOKEN" | jq '.config.CustomAdminUIDomain'
+
+# Check adapter config for client-origin-auth key
+# The key MUST include the origin URL: "client-origin-auth-https://myapp.com"
+# NOT a hash/signature as the key suffix
+```
+
+**Fix**:
+1. Set `CustomAdminUIDomain` to the app origin (e.g., `https://myapp.com`)
+2. Sign the IDP settings: `POST /admin/realms/{realm}/vendorResources/sign-idp-settings`
+3. Ensure adapter config `client-origin-auth` key includes the origin URL, not just the signature value
+
+**Verification**: Enclave popup appears and stays open for user interaction.
+
+VERIFIED (Ratidefy SaaS — IDP settings unsigned, client-origin-auth key had signature instead of origin URL).
+
+---
+
+## T-22: IGA Role Assignment Stuck in DRAFT (Unsignable Change Request)
+
+**Symptom**: Role assigned to user via admin API, change request created, but sign/commit returns 200 without actually signing. Role remains in DRAFT state permanently.
+
+**Possible Causes**:
+1. Role assigned before the user linked their Tide account — IGA requires a Tide doken for change request signing
+2. The master admin token can create change requests but cannot sign them without a Tide identity
+
+**Diagnostics**:
+1. Check TideCloak admin → realm → Users → target user → Role Mapping tab
+2. If role shows "DRAFT" badge, the change request was never signed
+3. Check if user has a federated identity (Identity Provider Links tab)
+
+**Fix**: 
+1. Delete the DRAFT change request
+2. Ensure the user links their Tide account first (via invite link)
+3. Then assign the role — the change request can now be signed
+
+**Prevention**: In automated provisioning, split into two phases:
+- Phase A: Create realm, user, generate invite link (no role assignment)
+- Phase B: After user links Tide account, assign role and approve change request
+
+**Verification**: Role shows "ACTIVE" status in TideCloak admin after sign+commit.
+
+VERIFIED (Ratidefy SaaS — provisioner assigned tide-realm-admin before account linking, creating permanent DRAFT).

package/mcp-server/dist/http.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/mcp-server/dist/http.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import express from "express";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer } from "./server.js";
+const app = express();
+app.use(express.json());
+// Optional Bearer token auth
+const API_TOKEN = process.env.API_TOKEN;
+if (API_TOKEN) {
+    app.use("/mcp", (req, res, next) => {
+        const auth = req.headers.authorization;
+        if (!auth || auth !== `Bearer ${API_TOKEN}`) {
+            res.status(401).json({ error: "Unauthorized" });
+            return;
+        }
+        next();
+    });
+}
+// MCP endpoint — stateless (new server + transport per request)
+app.post("/mcp", async (req, res) => {
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    res.on("close", () => {
+        transport.close();
+        server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+});
+// Handle GET and DELETE for SSE streams (required by protocol)
+app.get("/mcp", async (req, res) => {
+    res.status(405).json({ error: "Method not allowed. Use POST for stateless MCP." });
+});
+app.delete("/mcp", async (req, res) => {
+    res.status(405).json({ error: "Method not allowed. Stateless server — no sessions to delete." });
+});
+// Health check for Azure / load balancers
+app.get("/health", (_, res) => {
+    res.status(200).json({ status: "ok", name: "@tideorg/mcp" });
+});
+const port = parseInt(process.env.PORT || "3000", 10);
+app.listen(port, "0.0.0.0", () => {
+    console.log(`@tideorg/mcp HTTP server listening on port ${port}`);
+    console.log(`MCP endpoint: http://0.0.0.0:${port}/mcp`);
+    console.log(`Health check: http://0.0.0.0:${port}/health`);
+});