@tideorg/mcp 1.4.0

package/prompts/secure-existing-app.md

@@ -0,0 +1,80 @@
+# Prompt: Secure an Existing App with Tide
+
+Copy-paste this prompt to an AI coding agent to add Tide to an existing Next.js application safely and incrementally.
+
+---
+
+## The Prompt
+
+> I have an existing Next.js app. Add Tide authentication and server-side API protection to it. Preserve the existing app behavior. Do not rewrite the app.
+>
+> **Route first, then act.** Use the development team model. Team sequence: Scenario Resolver → Setup → Application Engineer (retrofit) → Security Engineer → IAM/Policy if needed → Reviewer before handoff. Check `reference-apps/INDEX.md` for a matching scenario.
+>
+> **Assumptions**:
+> - The app already has pages, routes, and possibly API endpoints.
+> - The app may or may not have existing auth (e.g., NextAuth, custom JWT, session cookies).
+>
+> **Inspect first** (before any code changes):
+> 1. Is TideCloak running? `curl -sf http://localhost:8080 > /dev/null && echo "Running" || echo "Not running"`
+> 2. Check if Tide is already installed: `grep '@tidecloak' package.json`
+> 3. Check for existing auth: `grep -r "auth\|login\|session\|jwt\|NextAuth" app/ pages/ lib/ --include="*.ts" --include="*.tsx" | head -20`
+> 4. Check for existing request interception: `cat proxy.ts 2>/dev/null || cat middleware.ts 2>/dev/null`
+> 5. Check for existing API routes: `find app/api pages/api -name "*.ts" 2>/dev/null`
+> 6. Check if any API route already verifies JWTs: `grep -r "jwtVerify\|verifyToken\|verifyJWT" app/api/ lib/ --include="*.ts" 2>/dev/null`
+>
+> **If TideCloak is not running**, bootstrap it first:
+> 1. Playbook `start-tidecloak-dev` — start the Docker container
+> 2. Playbook `bootstrap-realm-from-template` — create realm, enable licensing + IGA
+> 3. Playbook `initialize-admin-and-link-account` — create admin, link Tide account, export adapter JSON
+>
+> All three playbooks are sequential and mandatory. Bootstrap is NOT complete until a user with a non-empty `tideUserKey` attribute exists and `data/tidecloak.json` is exported. Do not attempt Tide SDK wiring until all three steps finish. VERIFIED (atproto-learnings L-01).
+>
+> **If TideCloak is running but Tide is not installed**, determine the right setup path:
+> - No existing auth at all → playbook `add-auth-nextjs-fresh`
+> - Has existing auth to replace or supplement → playbook `add-auth-nextjs-existing`
+> - Follow the `tide-setup` skill to complete all checks.
+>
+> **If Tide is already installed**, determine what is missing:
+> - No server-side JWT verification (`lib/auth/tideJWT.ts` absent) → follow `tide-route-and-api-protection` skill
+> - JWT verification exists but no role checks → follow `tide-rbac-and-e2ee` skill
+> - Everything in place → audit existing API routes for gaps (see below)
+>
+> **Package versions** (when installing Tide packages):
+> 1. Run `npm view @tidecloak/nextjs version` before adding to package.json. Pin the exact version. Do not use `"latest"`.
+> 2. If the resolved version is 0.99.x, skip it. Fall back to `canon/version-policy.md`.
+> 3. Do not use `--force` or `--legacy-peer-deps` as the default. Align versions to resolve peer conflicts.
+> 4. Include a short version-selection summary in your output.
+>
+> **Playbook sequence** (follow in order, skip steps already completed):
+> 1. `add-auth-nextjs-fresh` or `add-auth-nextjs-existing` — setup. Verify login works before proceeding.
+> 2. `protect-routes-nextjs` — client-side route guards (UX only).
+> 3. `protect-api-nextjs` then `verify-jwt-server-side` — server-side JWT + DPoP verification. This is real authorization.
+> 4. `add-rbac-nextjs` — role-based access control. Only after step 3 is verified.
+>
+> Use the `tide-route-and-api-protection` skill's diagnostic table to audit any existing API routes for gaps.
+>
+> **Preserve existing behavior**:
+> - Do not remove existing pages or routes.
+> - Do not restructure the project unless required for Tide wiring.
+> - Add Tide as a layer: provider wrapping the app, verification in API routes.
+> - Test that existing non-auth functionality still works after each step.
+> - If the app uses existing auth (NextAuth, custom), decide with me whether to replace or run in parallel. Do not silently remove it.
+>
+> **Do not**: Create fake auth helpers, plain-text role cookies, or ad hoc local auth. Do not treat `hasRole()` or route guards as real API protection. Do not skip DPoP. See `adapters/AGENTS.md` Forbidden Shortcuts for the full list.
+>
+> **If the app is not Tide-enabled at all**, stop all other work. Complete setup first. Do not diagnose Tide issues on an app without Tide installed.
+
+---
+
+## Acceptance Criteria
+
+- [ ] TideCloak running with realm configured and adapter JSON exported
+- [ ] Tide provider wraps the app with DPoP enabled
+- [ ] Adapter JSON present with `jwk`, `vendorId`, `homeOrkUrl`
+- [ ] Login flow works (redirect to TideCloak and back)
+- [ ] Every API route that handles sensitive data verifies JWT server-side
+- [ ] Unauthenticated curl to protected API returns 401
+- [ ] Existing non-auth functionality still works
+- [ ] No fake auth helpers or plain-text role cookies in codebase
+- [ ] Post-auth redirect handler exists at configured `redirectUri` path
+- [ ] Browser console shows no CSP violations

package/reference-apps/INDEX.md

@@ -0,0 +1,87 @@
+# Scenario-Pattern Library
+
+Known app scenarios with pre-defined Tide role, policy, and bootstrap patterns.
+
+## Purpose
+
+When a user describes an app that matches a known scenario, agents use the scenario manifest to determine:
+- which Tide features are required
+- which roles and policies to create
+- who creates and approves them
+- the correct playbook sequence
+- what must happen before users can use the app
+
+## How to use
+
+1. When a user says "build me an app" or describes an app type, check this index.
+2. If the description matches **one** scenario, read its `manifest.yaml` for the full pattern.
+3. If the description matches **multiple** scenarios or is ambiguous, resolve the branch before proceeding. Use the discriminating questions in the table below. If unresolved, ask the user — do not silently pick one. (I-17)
+4. Use the matched manifest to drive role creation, policy deployment, and playbook ordering.
+5. If no scenario matches and the request is a standard auth/protection flow, fall back to `tide-setup` skill detection and playbook routing.
+6. If no scenario matches and the request describes a **novel pattern** not covered by existing playbooks, route to `tide-solutions-architect` to explore safe implementation options within pack constraints.
+
+## Disambiguation
+
+If the request could map to multiple scenarios, resolve with these questions:
+
+| Ambiguity | Discriminating question | If yes | If no |
+|-----------|------------------------|--------|-------|
+| Encryption vs signing | Does the app encrypt/decrypt data, or produce cryptographic signatures? | Encryption → check sharing/real-time. Signing → `policy-governed-signing`. | Neither → check governance or standard auth. |
+| Self-encryption vs shared | Do other users need to decrypt the same ciphertext? | `organisation-password-manager` or `setup-forseti-e2ee` | Self-encryption via `tide-rbac-and-e2ee` or `encrypted-communication` |
+| Real-time E2E vs stored data | Does the app need real-time encrypted communication (chat, video, audio) with external crypto? | `encrypted-communication` | `organisation-password-manager` or standard self-encryption |
+| Vault/org app vs generic app | Is this a credential vault, password manager, or team-shared encrypted store? | `organisation-password-manager` | Check other scenarios or use standard playbooks |
+| Governance vs end-user app | Does the app need a custom admin UI for approving IGA change requests? | `iga-admin-governance` | Standard auth playbooks |
+| Admin panel vs built-in console | Is the built-in TideCloak Admin Console sufficient for governance? | Standard playbooks (no custom governance needed) | `iga-admin-governance` |
+| Signing service vs direct signing | Does the app sign git commits/merges server-side after PR-based admin approval? | `git-pr-signing-service` | `policy-governed-signing` (direct in-app signing) |
+| Single scenario vs no match | Does the description mention domain-specific keywords (SSH, vault, signing, admin, governance, chat, video, messaging)? | Use matched scenario | Use generic playbook routing |
+
+## Scenarios
+
+| ID | Scenario | Primary Tide capability | Default roles | Policy roles | When to use |
+|----|----------|------------------------|---------------|-------------|-------------|
+| `organisation-password-manager` | Shared credential vault for teams | Self-encryption + policy-governed encryption (Forseti) | `_tide_enabled`, `_tide_<tag>.selfencrypt`, `_tide_<tag>.selfdecrypt` | `appUser`, `orgOwner` | Password manager, credential vault, team vault, secret store |
+| `policy-governed-signing` | Cryptographic signing via Forseti contracts on ORK network | Policy-governed threshold signing (Forseti) | `_tide_enabled` | Per-resource signing roles (e.g., `ssh:<user>`) | Keyless SSH, document signing, transaction signing, any policy-governed signing |
+| `git-pr-signing-service` | Enterprise PR-based commit signing via GitHub webhooks | Policy-governed threshold signing (Forseti) + GitHub API | `_tide_enabled` | Per-branch signing roles (e.g., `git-sign:main`) | Git commit signing, verified commits, enterprise code signing, PR signing service |
+| `iga-admin-governance` | Custom admin panel for IGA change request governance | IGA change-set lifecycle + multi-admin quorum | `_tide_enabled`, `tide-realm-admin` | None (governance, not data) | Admin dashboard, approval workflow, change request management, governance panel |
+| `encrypted-communication` | Real-time encrypted chat/video with Tide-protected key storage | Self-encryption (key storage) + external crypto (runtime E2E) | `_tide_enabled`, `_tide_<tag>.selfencrypt`, `_tide_<tag>.selfdecrypt` | None | Encrypted chat, encrypted video calls, secure messaging, zero-knowledge server |
+
+## Matching rules
+
+- Match on app description keywords, not exact names.
+- `organisation-password-manager` matches: "password manager", "credential vault", "shared secrets", "team vault", "org vault", "shared password store", "secret store", "vaultwarden", "bitwarden", "encrypted sharing", "share encrypted data", "cross-user decryption", "shared encryption", "encrypt and share", "chosen recipients", "selective sharing", "encrypt for others".
+- `policy-governed-signing` matches: "keyless ssh", "ssh signing", "policy signing", "threshold signing", "document signing", "transaction signing", "forseti signing", "ork signing", "decentralised signing", "sign with tide".
+- `git-pr-signing-service` matches: "git signing", "git commit signing", "commit signing", "signed commits", "verified commits", "github signing", "github verified", "pr signing", "merge signing", "sign commits", "sign merges", "code signing service", "enterprise commit signing", "verified badge", "git tag signing".
+- `iga-admin-governance` matches: "admin panel", "admin dashboard", "governance panel", "governance dashboard", "change request", "approval workflow", "multi-admin", "quorum approval", "iga admin", "iga panel", "manage change requests", "approve changes", "admin console", "policy management panel".
+- `encrypted-communication` matches: "encrypted chat", "encrypted messaging", "encrypted video", "e2e chat", "e2e messaging", "secure chat", "secure messaging", "private messaging", "zero knowledge", "encrypted group chat", "encrypted video call", "signal-like", "whatsapp-like", "chat app with encryption", "video app with encryption", "encrypted collaboration", "forward secrecy", "key exchange".
+- If the user describes a **single-user private vault** with no sharing, do NOT use the password manager scenario. Use the `nextjs-e2ee-vault` template instead.
+- If the user describes **only authentication** with no signing or encryption, do NOT use these scenarios. Use the standard playbook sequence.
+- If the user only needs the **built-in TideCloak Admin Console** for governance, do NOT use the `iga-admin-governance` scenario. Use the standard `setup-iga-admin-panel` playbook directly.
+
+## What a scenario defines
+
+Each scenario directory contains:
+
+| File | Purpose |
+|------|---------|
+| `scenario.md` | What the app is, what Tide features it needs |
+| `manifest.yaml` | Machine-readable: roles, policies, playbook sequence, bootstrap requirements |
+| `role-policy-matrix.md` | Which roles exist, what each policy checks, who approves |
+| `bootstrap-sequence.md` | Step-by-step pre-user setup (admin-only, before app goes live) |
+| `anti-patterns.md` | Scenario-specific mistakes |
+
+## Key differences between scenarios
+
+| Aspect | organisation-password-manager | policy-governed-signing | git-pr-signing-service | iga-admin-governance | encrypted-communication |
+|--------|------------------------------|------------------------|------------------------|---------------------|------------------------|
+| Primary operation | Encrypt/decrypt data | Sign data | Sign git merge commits | Approve/commit admin changes | Real-time encrypted communication |
+| Encryption | Self-encryption + policy-governed | None | None | None | Self-encryption (key storage) + external crypto (runtime) |
+| Signing | None | Forseti contract-authorized threshold signing | Forseti contract-authorized threshold signing (git commits) | Enclave signing for change-set approval | None |
+| Org-scoped roles | Yes (`org:{uuid}:{role}`) | No | No | No | No |
+| E2EE roles | Yes (`_tide_<tag>.selfencrypt/selfdecrypt`) | No | No | No | Yes (`_tide_<tag>.selfencrypt/selfdecrypt`) |
+| Forseti contracts | Validate org scope + VVK signatures | Validate data + authorize signer | Validate commit content + authorize approvers + verify service | Optional: manage role-policy attachments | None |
+| External integration | No | No | Yes (GitHub webhooks, Checks API, Git Data API) | No | No |
+| External crypto library | No | No | No (SSH wire format wrapping only) | No | Yes (libsodium, WebCrypto, etc.) |
+| IGA required | Yes | Yes | Yes | Yes (core purpose) | Yes |
+| Admin pre-approval | Yes (appUser, orgOwner policies) | Yes (signing policies per role) | Yes (signing policies per branch) | Yes (quorum for all admin mutations) | Yes (E2E roles) |
+| Min admins | 1 | 1 | 2 (signing quorum) | 2 (for quorum governance) | 1 |
+| Developer interacts with Tide | Yes | Yes | No (developers push code normally) | Yes | Yes |

package/reference-apps/encrypted-communication/anti-patterns.md

@@ -0,0 +1,123 @@
+# Encrypted Communication — Anti-Patterns
+
+Scenario-specific mistakes for encrypted communication apps using the hybrid Tide + external crypto pattern. General Tide anti-patterns (I-01 through I-16, AP-01 through AP-42) still apply.
+
+---
+
+## AP-EC01: Storing private keys in plaintext
+
+**Mistake**: Storing the user's private key in the database without Tide encryption, or storing it in localStorage/sessionStorage.
+
+**Why it fails**: The private key is the root of trust for all E2E operations. If stored in plaintext, a database breach or XSS attack exposes all encrypted communications.
+
+**Fix**: Always encrypt the private key with `doEncrypt(privateKeyBytes, tag)` before storing. Always decrypt with `doDecrypt()` on login. Never persist the decrypted private key outside of in-memory variables.
+
+---
+
+## AP-EC02: Generating keys server-side
+
+**Mistake**: Generating the user's asymmetric keypair on the server and sending the private key to the client.
+
+**Why it fails**: The server sees the private key in plaintext, breaking the zero-knowledge property. The private key transits over the network unprotected by Tide.
+
+**Fix**: Generate keypairs client-side only. The server never sees the private key. It only stores the Tide-encrypted ciphertext.
+
+---
+
+## AP-EC03: Using Tide doEncrypt/doDecrypt for runtime message encryption
+
+**Mistake**: Encrypting every chat message or media frame with Tide's `doEncrypt()`.
+
+**Why it fails**: Tide self-encryption is identity-bound (only the encrypting user can decrypt). Other participants cannot decrypt messages encrypted this way. Also, `doEncrypt()` requires a round-trip to the ORK network, making it too slow for real-time frame-by-frame media encryption.
+
+**Fix**: Use Tide self-encryption only for private key storage (once per login). Use an external crypto library for runtime E2E operations (message encryption, frame encryption, key exchange).
+
+---
+
+## AP-EC04: Skipping key material API protection
+
+**Mistake**: Serving the encrypted key material endpoint without JWT verification. Anyone can fetch any user's encrypted private key.
+
+**Why it fails**: While the encrypted private key cannot be decrypted without Tide (identity-bound), exposing it unnecessarily increases attack surface. The public key endpoint may also leak presence information.
+
+**Fix**: Protect key material API endpoints with server-side JWT verification. Only serve a user's own encrypted private key to that authenticated user. Public keys may be more broadly accessible but still require authentication.
+
+---
+
+## AP-EC05: Trusting client-supplied public keys without verification
+
+**Mistake**: Accepting a user's public key from the client without verifying it corresponds to the encrypted private key.
+
+**Why it fails**: An attacker could submit a different public key, enabling a key substitution attack. Other users would encrypt messages to the attacker's key instead of the real user's key.
+
+**Fix**: Verify the public key matches the private key on the client side before storing. For libsodium Ed25519, derive the public key from the private key and compare. The server cannot verify this (it never sees the private key), so the client must do it.
+
+---
+
+## AP-EC06: No key rotation on membership change
+
+**Mistake**: Using the same conversation key after a member leaves a group chat or call.
+
+**Why it fails**: The departed member still has the conversation key and can decrypt future messages if they intercept the ciphertext.
+
+**Fix**: Rotate the conversation key when any member leaves. Generate a new key and distribute it (encrypted) to remaining members only. Store key history with version numbers so old messages remain decryptable with the old key.
+
+---
+
+## AP-EC07: Encrypting conversation keys with Tide instead of public-key crypto
+
+**Mistake**: Using `doEncrypt()` to encrypt conversation keys for distribution to other users.
+
+**Why it fails**: Tide self-encryption is identity-bound. If user A encrypts the conversation key with `doEncrypt()`, only user A can decrypt it. User B cannot decrypt it.
+
+**Fix**: Use the external crypto library's public-key encryption for key distribution. Encrypt the conversation key with each recipient's public key individually.
+
+---
+
+## AP-EC08: Treating ProtectedRoute as API protection
+
+**Mistake**: Using a client-side `ProtectedRoute` component as the only access control for encrypted data.
+
+**Why it fails**: Client-side route guards are UI gating only. The API endpoints serving key material and encrypted messages are still accessible via direct HTTP requests.
+
+**Fix**: Every API endpoint that serves or accepts encrypted data must have server-side JWT verification. The `ProtectedRoute` component is a UX convenience, not a security boundary.
+
+---
+
+## AP-EC09: Hardcoding the encryption tag
+
+**Mistake**: Using a hardcoded tag string (e.g., `"self"`) without ensuring matching roles exist in the realm.
+
+**Why it fails**: `doEncrypt(data, "chat")` requires the user to have `_tide_chat.selfencrypt`. If the realm only has `_tide_self.selfencrypt`, the operation fails with "User has not been given any access to 'chat'".
+
+**Fix**: Choose one tag name. Ensure the realm template includes matching `_tide_<tag>.selfencrypt` and `_tide_<tag>.selfdecrypt` roles. Document the tag name. Do not change it after users have encrypted data with it.
+
+---
+
+## AP-EC10: Initializing crypto before TideCloak auth completes
+
+**Mistake**: Calling `doEncrypt()` or `doDecrypt()` before the TideCloak provider has finished initializing and the user is authenticated.
+
+**Why it fails**: The SDK requires an active session with valid doken. Calling encryption methods before auth completes throws errors or returns undefined.
+
+**Fix**: Wait for `isAuthenticated === true` before attempting any Tide encryption operations. Gate the key initialization flow on authentication completion.
+
+---
+
+## AP-EC11: Losing the decrypted private key on token refresh
+
+**Mistake**: Clearing the in-memory private key state when the TideCloak token refreshes.
+
+**Why it fails**: Token refresh is a normal background operation. Clearing crypto state forces the user to re-decrypt their private key, which may briefly break active E2E sessions.
+
+**Fix**: Keep the decrypted private key in a React ref or module-level variable that survives re-renders and token refreshes. Only clear it on explicit logout.
+
+---
+
+## AP-EC12: Using `@tidecloak/react` version 0.99.x
+
+**Mistake**: Installing a 0.99.x pre-release version of the Tide SDK.
+
+**Why it fails**: 0.99.x versions are unstable pre-releases. The stable version is 0.13.26 (per pack version policy).
+
+**Fix**: Pin `@tidecloak/react` to `0.13.26`. See `canon/version-policy.md`.

package/reference-apps/encrypted-communication/bootstrap-sequence.md

@@ -0,0 +1,152 @@
+# Encrypted Communication — Bootstrap Sequence
+
+---
+
+## Phase 1: TideCloak Infrastructure
+
+1. Start TideCloak container:
+   ```bash
+   docker run -d --name tidecloak -p 8080:8080 tideorg/tidecloak-dev:latest
+   ```
+   Wait until `http://localhost:8080` responds.
+
+2. Obtain master admin token:
+   ```bash
+   TOKEN=$(curl -s -X POST "http://localhost:8080/realms/master/protocol/openid-connect/token" \
+     -H "Content-Type: application/x-www-form-urlencoded" \
+     -d "grant_type=password&client_id=admin-cli&username=admin&password=password" \
+     | jq -r '.access_token')
+   ```
+
+---
+
+## Phase 2: Realm Setup
+
+3. Create realm from template.
+
+   The realm template must include:
+   - `_tide_enabled` in default composite role
+   - `_tide_<tag>.selfencrypt` and `_tide_<tag>.selfdecrypt` in default composite role
+   - `tidebrowser` authentication flow
+   - `link-tide-account-action` required action
+   - Tide protocol mappers (`tideUserKey`, `vuid`)
+   - `UPDATE_PASSWORD` required action disabled
+
+   ```bash
+   curl -s -X POST "http://localhost:8080/admin/realms" \
+     -H "Authorization: Bearer $TOKEN" \
+     -H "Content-Type: application/json" \
+     -d @realm.json
+   ```
+   **Fail-fast**: Check HTTP status. Abort on non-2xx.
+
+4. License realm:
+   ```bash
+   curl -s -X POST "http://localhost:8080/admin/realms/$REALM/vendorResources/setUpTideRealm" \
+     -H "Authorization: Bearer $TOKEN" \
+     -H "Content-Type: application/x-www-form-urlencoded" \
+     -d "email=admin@example.com"
+   ```
+
+5. Enable IGA:
+   ```bash
+   curl -s -X POST "http://localhost:8080/admin/realms/$REALM/tide-admin/toggle-iga" \
+     -H "Authorization: Bearer $TOKEN" \
+     -H "Content-Type: application/x-www-form-urlencoded" \
+     -d "isIGAEnabled=true"
+   ```
+
+6. Approve and commit initial client change request.
+
+---
+
+## Phase 3: Admin User
+
+7. Create admin user (include `firstName` and `lastName` to avoid `VERIFY_PROFILE` block).
+
+8. Approve and commit user creation change request.
+
+9. Assign `tide-realm-admin` (client role on `realm-management`).
+
+10. Approve and commit role assignment change request.
+
+11. Generate invite link (`lifespan=43200`). Admin completes Tide account linking.
+
+---
+
+## Phase 4: IDP Settings and Adapter Export
+
+12. Sign IDP settings:
+    ```bash
+    curl -s -X POST "http://localhost:8080/admin/realms/$REALM/vendorResources/sign-idp-settings" \
+      -H "Authorization: Bearer $TOKEN"
+    ```
+
+13. Export adapter JSON:
+    ```bash
+    curl -s "http://localhost:8080/admin/realms/$REALM/vendorResources/get-installations-provider?clientId=$CLIENT_UUID&providerId=keycloak-oidc-keycloak-json" \
+      -H "Authorization: Bearer $TOKEN" > tidecloak.json
+    ```
+    Verify `jwk` field is present.
+
+---
+
+## Phase 5: App Wiring
+
+14. Install SDK (`@tidecloak/react` or `@tidecloak/nextjs`).
+
+15. Wire TideCloak provider with adapter JSON config.
+
+16. Create redirect handler at configured `redirectUri` path.
+
+17. Add `public/silent-check-sso.html`.
+
+18. Set CSP `frame-src '*'` in server config or framework config.
+
+19. Implement server-side JWT verification for API routes that handle key material.
+
+20. Create API endpoint for storing/retrieving encrypted key material (protected by JWT verification).
+
+21. Create database table for user keys (user_id, public_key, encrypted_private_key).
+
+---
+
+## Phase 6: Client-Side Key Management
+
+22. Install external crypto library (e.g., `libsodium-wrappers`).
+
+23. Implement first-login flow:
+    - Generate keypair client-side
+    - Encrypt private key with `doEncrypt(privateKeyBytes, tag)`
+    - Store encrypted private key + public key via protected API
+
+24. Implement returning-login flow:
+    - Fetch encrypted key material via protected API
+    - Decrypt private key with `doDecrypt(encryptedPrivateKey, tag)`
+    - Private key available in memory for runtime E2E operations
+
+25. Implement runtime E2E operations using the external crypto library (not Tide).
+
+---
+
+## Pre-User Checklist
+
+Before any user accesses the app:
+
+- [ ] TideCloak running and reachable
+- [ ] Realm created with self-encryption roles in default composite
+- [ ] Realm licensed (`setUpTideRealm`)
+- [ ] IGA enabled (`toggle-iga`)
+- [ ] At least one admin user with `tide-realm-admin` linked
+- [ ] All initial change requests approved and committed
+- [ ] IDP settings signed (`sign-idp-settings`)
+- [ ] Adapter JSON exported with `jwk` field present
+- [ ] App has TideCloak provider wired with config
+- [ ] Redirect handler exists at configured path
+- [ ] `silent-check-sso.html` in public directory
+- [ ] CSP includes `frame-src '*'`
+- [ ] Server-side JWT verification on key material API endpoints
+- [ ] Database table for encrypted key storage exists
+- [ ] External crypto library installed and initialized
+- [ ] First-login keypair generation flow tested
+- [ ] Returning-login key decryption flow tested

package/reference-apps/encrypted-communication/manifest.yaml

@@ -0,0 +1,100 @@
+# Encrypted Real-Time Communication — Scenario Manifest
+
+id: encrypted-communication
+title: Encrypted Real-Time Communication
+category: e2e-communication
+description: Chat or video app with Tide-protected private keys and external crypto for runtime E2E encryption
+
+frameworks:
+  - nextjs
+  - react-vite
+  - vanilla
+
+core_patterns:
+  - self-encryption
+  - self-decryption
+  - oidc
+  - iga
+  - dpop
+  - e2e
+  - encrypted-chat
+  - encrypted-video
+  - encrypted-messaging
+  - key-storage
+  - key-exchange
+  - forward-secrecy
+  - zero-knowledge-server
+  - hybrid-encryption
+  - private-key-protection
+  - real-time
+  - websocket
+  - webrtc
+
+match_keywords:
+  - encrypted chat
+  - encrypted messaging
+  - encrypted video
+  - encrypted calls
+  - encrypted communication
+  - e2e chat
+  - e2e messaging
+  - e2e video
+  - e2e communication
+  - end to end encrypted
+  - end-to-end encrypted
+  - secure chat
+  - secure messaging
+  - secure video
+  - private messaging
+  - private chat
+  - zero knowledge
+  - zero-knowledge
+  - real-time encryption
+  - encrypted group chat
+  - encrypted video call
+  - signal-like
+  - whatsapp-like
+  - chat app with encryption
+  - video app with encryption
+  - tidetalk
+  - encrypted collaboration
+  - forward secrecy
+  - key exchange
+  - encryption and decryption
+  - encrypt decrypt share
+  - encryption with sharing
+  - encrypt and share
+  - shared encryption
+
+bootstrap_required: true
+requires_admin_preapproval: true
+requires_iga: true
+requires_e2ee: true
+encryption_mode: self-encryption
+
+default_roles:
+  - _tide_enabled
+  - _tide_<tag>.selfencrypt
+  - _tide_<tag>.selfdecrypt
+
+default_playbooks:
+  - start-tidecloak-dev
+  - bootstrap-realm-from-template
+  - initialize-admin-and-link-account
+  - configure-e2ee-roles-and-policies
+  - add-auth-nextjs-fresh
+  - protect-routes-nextjs
+  - protect-api-nextjs
+  - verify-jwt-server-side
+  - add-rbac-nextjs
+
+default_skills:
+  - tide-setup
+  - tide-integration
+  - tide-route-and-api-protection
+  - tide-rbac-and-e2ee
+
+discriminating_question: Does the app need real-time encrypted communication (chat, video, or audio) where the server never sees plaintext? If the app only stores encrypted data without real-time streaming, use organisation-password-manager instead.
+valid_only_when: App requires runtime E2E encryption for real-time content (messages, media frames) using external crypto, with Tide protecting the private key material at rest.
+
+notes: Two encryption layers. Layer 1 is Tide self-encryption for private key storage. Layer 2 is an external client-side crypto library for runtime E2E. Tide does not handle Layer 2 directly. Replace <tag> with app-specific tag name.

package/reference-apps/encrypted-communication/role-policy-matrix.md

@@ -0,0 +1,80 @@
+# Encrypted Communication — Role & Policy Matrix
+
+---
+
+## Tide Bootstrap Roles
+
+| Role | Type | Purpose | Created by | Approved by | Required before first use | Default / optional | Notes |
+|------|------|---------|-----------|-------------|--------------------------|-------------------|-------|
+| `_tide_enabled` | Realm | Enables Tide voucher system | Realm template | Auto (in default composite) | Yes | Default | Must be in `default-roles-{realm}` composite |
+| `_tide_<tag>.selfencrypt` | Realm | Allows user to encrypt their private key with Tide | Realm template | IGA quorum (if added after import) | Yes | Default | Replace `<tag>` with app-specific name (e.g., `keys`, `chat`) |
+| `_tide_<tag>.selfdecrypt` | Realm | Allows user to decrypt their private key with Tide | Realm template | IGA quorum (if added after import) | Yes | Default | Must pair with selfencrypt for round-trip |
+
+---
+
+## Application Roles (optional, app-defined)
+
+This scenario does not require app-specific roles beyond the Tide bootstrap roles. The app may add its own roles for business logic (e.g., `admin`, `moderator`, `premium-user`), but these are separate from the encryption mechanism.
+
+| Example role | Type | Purpose | Notes |
+|-------------|------|---------|-------|
+| `admin` | Realm | App admin (not Tide admin) | Optional. For app-level moderation, not IGA governance. |
+
+---
+
+## Key rules
+
+1. **Self-encryption is identity-bound.** Only the user who called `doEncrypt` can call `doDecrypt` on the same ciphertext. This is the correct behavior for private key storage — no other user should be able to decrypt your private key.
+
+2. **Both selfencrypt AND selfdecrypt roles are needed.** A user without `selfdecrypt` can store their encrypted key but cannot retrieve it on next login.
+
+3. **Roles must be in the default composite.** New users get these roles automatically. If roles are missing from the composite, users must be assigned individually and the assignment must go through IGA.
+
+4. **One tag is sufficient for this scenario.** Unlike the password manager scenario, this pattern does not need multiple tags or policy-governed encryption. A single tag (e.g., `keys`) covers the private key protection use case.
+
+5. **No Forseti contracts needed.** Self-encryption does not require policy bytes, contracts, or VVK shared encryption. The Tide SDK handles it directly via `doEncrypt(data, tag)` / `doDecrypt(data, tag)`.
+
+6. **No policy-governed encryption roles needed** (self-encryption variant only). The runtime E2E encryption uses an external crypto library, not Tide's policy-governed path.
+
+---
+
+## Shared Encryption Variant
+
+If the app requires **Tide-native shared encryption** (recipients decrypt via `IAMService.doDecrypt` with policy bytes, not external crypto), the self-encryption path above is insufficient. You need:
+
+1. **Additional roles**: A Forseti contract role (e.g., `shared-data-access`) that the contract checks for authorization
+2. **Voucher gate roles**: `_tide_<tag>.selfencrypt` / `_tide_<tag>.selfdecrypt` still needed for the voucher system
+3. **Forseti contract**: Deployed via `PolicySignRequest.addForsetiContractToUpload()` during the admin signing ceremony
+4. **Playbook**: Add `setup-forseti-e2ee` to the playbook sequence BEFORE `add-rbac-nextjs`
+
+See `setup-forseti-e2ee` playbook for the complete Forseti policy signing flow. VERIFIED (LEARNINGS-batch-009 L-03, L-06).
+
+---
+
+## What Tide does NOT handle in this scenario
+
+| Concern | Handled by | Notes |
+|---------|-----------|-------|
+| Runtime message encryption | External crypto library (e.g., libsodium `crypto_secretbox`) | Tide has no involvement |
+| Media frame encryption | External crypto library (e.g., libsodium with WebRTC Insertable Streams) | Tide has no involvement |
+| Key exchange between users | External crypto library (e.g., libsodium `crypto_scalarmult`) | Uses public keys stored in DB |
+| Conversation key generation | External crypto library | App generates symmetric keys for group chats |
+| Key rotation / forward secrecy | App logic | Re-encrypt conversation key for remaining members when membership changes |
+| Public key distribution | App server (stores public keys in database) | Server sees public keys, never private keys |
+
+---
+
+## Database Schema (minimum required)
+
+The app must store encrypted key material. Minimum columns:
+
+| Column | Type | Purpose |
+|--------|------|---------|
+| `user_id` | string | TideCloak user ID (from JWT `sub` claim) |
+| `public_key` | text | User's public key (plaintext, for key exchange) |
+| `encrypted_private_key` | text | User's private key encrypted by Tide self-encryption |
+| `created_at` | timestamp | When keys were generated |
+
+The encrypted_private_key column stores the base64 output of `doEncrypt()`. Size depends on the key type. For Ed25519 (32-byte private key): approximately 400 characters base64 after Tide encryption overhead.
+
+Optional extensions: key version, key history table (for forward secrecy), per-room conversation keys.