@tideorg/mcp 1.4.0

package/reference-apps/iga-admin-governance/scenario.md

@@ -0,0 +1,126 @@
+# IGA Admin Governance Panel
+
+## What this is
+
+An admin-facing dashboard for managing TideCloak's Identity Governance & Administration (IGA) change requests. Realm admins use this panel to review, approve, reject, and commit proposed changes to users, roles, groups, clients, policies, and realm settings. Every admin mutation in an IGA-enabled realm creates a draft change request. No change takes effect until quorum-signed and committed.
+
+This is a governance tool, not an end-user application. It sits alongside the app that triggered the admin changes.
+
+---
+
+## When to use this scenario
+
+Use when the app needs:
+- A custom admin UI for reviewing and approving IGA change requests (instead of or alongside the built-in TideCloak Admin Console)
+- Multi-admin quorum governance workflow embedded in a custom dashboard
+- Visibility into policy management, Forseti contracts, and role-policy attachments
+- Activity tracking (approvals, rejections, comments) on change requests
+
+Do NOT use when:
+- The built-in TideCloak Admin Console is sufficient for governance
+- The app only needs end-user authentication (use standard auth playbooks)
+- The app needs data encryption (use `organisation-password-manager` or `setup-forseti-e2ee`)
+- The app needs cryptographic signing (use `policy-governed-signing`)
+
+---
+
+## Core Tide capabilities used
+
+| Capability | Role in this scenario |
+|-----------|----------------------|
+| IGA change-set API | Core: list, sign, commit, cancel change requests |
+| Multi-admin quorum | Core: approval threshold enforced cryptographically |
+| Enclave signing | Core: MultiAdmin mode triggers enclave challenge popup |
+| Forseti contract management | Supporting: view and manage contracts attached to role policies |
+| Realm policy lifecycle | Supporting: create, approve, commit realm-level policies |
+| Policy template CRUD | Supporting: manage reusable policy templates |
+| SSH/role policy management | Supporting: attach contracts to roles, set thresholds |
+| DPoP authentication | Required: admin API calls must be DPoP-bound |
+| Server-side JWT verification | Required: governance API routes must verify admin identity |
+
+---
+
+## What must exist before first admin use
+
+1. TideCloak running with a licensed, IGA-enabled realm
+2. At least one admin user with `tide-realm-admin` (client role on `realm-management`)
+3. Admin user has completed Tide account linking (invite flow)
+4. Adapter JSON exported with `jwk` field (IGA must be enabled for `jwk` to be present)
+5. App deployed with DPoP-enabled provider and server-side JWT verification
+6. For quorum governance: at least two linked admin users
+
+---
+
+## Bootstrap-only steps
+
+These happen before any admin uses the governance panel:
+
+1. Start TideCloak container
+2. Create realm from template (with `_tide_enabled`, `tidebrowser` flow, protocol mappers)
+3. License realm (`setUpTideRealm`)
+4. Enable IGA (`toggle-iga`)
+5. Create first admin user, assign `tide-realm-admin`, generate invite link
+6. First admin completes account linking
+7. Approve/commit initial change requests (user, role, client)
+8. Sign IDP settings (`sign-idp-settings`)
+9. Export adapter JSON
+10. Create second admin user (for quorum) and repeat invite/link/approve cycle
+
+---
+
+## Runtime admin flow
+
+Once bootstrap is complete, the governance panel operates as follows:
+
+1. Admin logs in via TideCloak SSO (DPoP-bound)
+2. Panel fetches change-set counts (`GET /tide-admin/change-set/counts`)
+3. Panel lists pending requests by type (users, roles, groups, clients, settings, policies)
+4. Admin reviews a change request's details, activity, and comments
+5. Admin approves: `POST /tide-admin/change-set/sign/batch` (JSON body)
+   - If MultiAdmin: enclave challenge popup appears; admin signs and submits via `POST /tideAdminResources/add-review` (**multipart/form-data**, not JSON)
+   - If FirstAdmin: signed immediately with VRK
+6. When approval count >= quorum threshold: `POST /tide-admin/change-set/commit/batch`
+7. Admin can cancel pending requests: `POST /tide-admin/change-set/cancel/batch`
+8. Admin can reject: `POST /tideAdminResources/add-rejection` (**multipart/form-data**)
+9. Admin can add/edit/delete comments on change requests
+
+---
+
+## Default playbook sequence
+
+1. `start-tidecloak-dev`
+2. `bootstrap-realm-from-template`
+3. `initialize-admin-and-link-account`
+4. `add-auth-nextjs-fresh` (or `add-auth-nextjs-existing`)
+5. `protect-routes-nextjs`
+6. `protect-api-nextjs`
+7. `verify-jwt-server-side`
+8. `setup-iga-admin-panel`
+9. `add-rbac-nextjs`
+
+---
+
+## Key diagnostics
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| Sign returns 401 | Token expired or DPoP not attached | Re-login; ensure `secureFetch` with DPoP |
+| Sign returns enclave challenge (MultiAdmin) | Multiple admins exist | Handle popup flow via `add-review` endpoint |
+| Commit returns error | Not all required approvals met | Check approval count vs quorum threshold |
+| Change request stays PENDING after sign | Missing commit step | Call `commit/batch` after sign succeeds |
+| add-review returns 415 | Wrong content-type | Use `multipart/form-data`, not JSON |
+| Counts don't update after commit | Stale data | Refresh counts after every mutation |
+| Policy change requests don't appear | Realm policy not in pending state | Create pending realm policy first via `/tide-admin/realm-policy/pending` |
+| Forseti contracts tab empty | No contracts registered | Contracts deploy via SDK signing flow, not REST API |
+| 120s delay after commit before roles appear | Token refresh delay | Expected behavior; re-login or wait |
+
+---
+
+## Intentionally configurable
+
+- **Admin role name**: `tide-realm-admin` is the default, but apps may check additional app-specific admin roles for UI-level filtering
+- **Quorum threshold**: Determined by `max(1, floor(TotalAdmins * 0.7))` at the TideCloak level; not app-configurable
+- **Change-set types**: The panel can filter which types to show based on app needs (e.g., only users and roles, not clients)
+- **Activity features**: Comments and activity history are optional; core governance works without them
+- **Policy management tabs**: Forseti contracts and realm policy management are optional features; a minimal panel needs only change-set list/approve/commit
+- **Custom admin domain**: `CustomAdminUIDomain` must be set and `sign-idp-settings` called if the panel is hosted separately from TideCloak's built-in Admin Console

package/reference-apps/organisation-password-manager/anti-patterns.md

@@ -0,0 +1,71 @@
+# Anti-Patterns — Organisation Password Manager
+
+Scenario-specific mistakes. Each defeats a security property or causes a setup failure.
+
+## AP-S01: Skipping IGA before role creation
+
+Creating self-encryption roles before enabling IGA means those role changes are not governed. Enable IGA first, then create roles so they go through the change-set approval flow.
+
+## AP-S02: Missing self-encryption roles in default composite
+
+If `_tide_<tag>.selfencrypt` and `_tide_<tag>.selfdecrypt` are not included in the default-roles composite, new users cannot encrypt or decrypt until an admin manually assigns roles. This breaks the expected first-use experience.
+
+## AP-S03: Treating the server as a decryption endpoint
+
+The server must never decrypt vault data. Decryption happens client-side via doken + ORK threshold + crypto policy. If the server decrypts, the entire E2EE guarantee is void. The server stores and returns ciphertext only.
+
+## AP-S04: Storing plaintext credentials server-side
+
+Vault entries must be encrypted before leaving the client. If the app sends plaintext to the server "for later encryption", the server sees secrets in the clear. Encrypt client-side, transmit ciphertext.
+
+## AP-S05: Omitting DPoP on protected API routes
+
+DPoP binds the access token to the device/session. Without DPoP verification on API routes, a stolen access token can be replayed from a different device. Verify DPoP proof on every protected endpoint.
+
+## AP-S06: Using `createRemoteJWKSet` for JWT verification
+
+Use `createLocalJWKSet(config.jwk)` only. Remote JWKS fetch introduces a network dependency and a potential MITM vector. If `jwk` is missing from the adapter JSON, re-export with IGA enabled.
+
+## AP-S07: Forgetting `sign-idp-settings` after config changes
+
+Any change to IDP settings (logo, origins, admin domain) must be followed by `sign-idp-settings`. Without it, the ORK enclave rejects the settings as unsigned. Login and encryption will fail silently.
+
+## AP-S08: Lazy runtime creation of encryption roles
+
+Do not create `_tide_<tag>.selfencrypt` / `_tide_<tag>.selfdecrypt` roles at app startup or on first user request. These roles must exist and be approved via IGA change-sets before the app is available to users.
+
+## AP-S09: Using wrong adapter provider ID
+
+The provider ID is `keycloak-oidc-keycloak-json`. The string `tidecloak-oidc-keycloak-json` does not exist. Using the wrong ID returns an error or a generic adapter without Tide fields.
+
+## AP-S10: Assuming roles appear instantly after IGA commit
+
+After a change-set is committed, roles appear in JWT/doken on the next token refresh. This can take up to 120 seconds. Do not treat immediate post-commit token checks as authoritative.
+
+## AP-S11: Hiding vault UI without protecting the API
+
+Hiding the "decrypt" button for unauthorized users is UI gating only. The API endpoint that handles decryption must independently verify JWT signature, claims, roles, and DPoP. A hidden button is not a security boundary.
+
+## AP-S12: Skipping change-set approval during bootstrap
+
+After IGA is enabled, client and user mutations create draft change-sets. If these are not signed and committed, the changes remain in draft state. The realm appears configured but clients and users are not fully active.
+
+## AP-S13: Caching decrypted credentials on the server
+
+Decrypted vault data must exist only in client memory. Do not cache decrypted values in server-side sessions, databases, or logs. Each decryption request must go through the ORK threshold path.
+
+## AP-S14: Not committing appUser PolicyApproval before user access
+
+The `appUser` PolicyApproval must be committed with non-empty `signed_policy_data` before encryption works. If uncommitted, the crypto policy endpoint returns null and client-side encryption silently fails or errors.
+
+## AP-S15: Skipping orgOwner PolicyApproval
+
+The `orgOwner` PolicyApproval with its Forseti contract (VVK verification, org-scope validation) must be committed before org admin operations work. Without it, user context signing fails and org-level policy enforcement is absent.
+
+## AP-S16: Hardcoding org role names without UUID
+
+Org-scoped client roles must follow the `org:{uuid}:{suffix}` pattern. Hardcoding role names without the org UUID breaks multi-org support and causes the Forseti contract's `TryExtractOrgId` validation to fail.
+
+## AP-S17: Serving crypto policy without verifying commitment status
+
+The crypto policy endpoint should only return `signed_policy_data` from committed PolicyApprovals. Serving policy data from pending or draft approvals means the policy has not been validated by the required quorum.

package/reference-apps/organisation-password-manager/bootstrap-sequence.md

@@ -0,0 +1,127 @@
+# Bootstrap Sequence — Organisation Password Manager
+
+All steps must complete before users can safely use the app. Order matters.
+
+## Phase 1: TideCloak infrastructure
+
+1. **Start TideCloak container**
+   - Use `tidecloak-dev` (development) or `tidecloak-stg-dev` (staging with ORK env vars).
+   - Dev image has built-in defaults. Staging requires `SYSTEM_HOME_ORK`, `USER_HOME_ORK`, `THRESHOLD_T`, `THRESHOLD_N`.
+   - Wait for readiness: `curl http://localhost:8080/health/ready` returns 200.
+
+2. **Obtain bootstrap admin token**
+   - `POST /realms/master/protocol/openid-connect/token` with `KC_BOOTSTRAP_ADMIN_USERNAME` / `KC_BOOTSTRAP_ADMIN_PASSWORD`.
+
+## Phase 2: Realm and client setup
+
+3. **Import realm template**
+   - `POST /admin/realms` with `realm.json`.
+   - Template must declare: realm name, OIDC client, `_tide_enabled` role, self-encryption roles (`_tide_<tag>.selfencrypt`, `_tide_<tag>.selfdecrypt`), default-roles composite, protocol mappers.
+   - Template should include redirect URIs for all clients (web app, browser extension if applicable).
+
+4. **License the realm**
+   - `POST /admin/realms/{realm}/vendorResources/setUpTideRealm` with admin email.
+   - Content-Type: `application/x-www-form-urlencoded`. Body: `email=admin@example.com`.
+   - Returns licensing JSON as `text/plain`.
+
+5. **Enable IGA**
+   - `POST /admin/realms/{realm}/tide-admin/toggle-iga` with form-urlencoded `isIGAEnabled=true`.
+   - Must happen after licensing. Enables change-set governance for role/user mutations.
+
+## Phase 3: Admin user setup
+
+6. **Create admin user**
+   - `POST /admin/realms/{realm}/users` with username, email, enabled=true.
+
+7. **Assign `tide-realm-admin` role**
+   - Get role ID: `GET /admin/realms/{realm}/clients/{realm-mgmt-client-id}/roles` and find `tide-realm-admin`.
+   - Assign: `POST /admin/realms/{realm}/users/{userId}/role-mappings/clients/{realm-mgmt-client-id}`.
+
+8. **Generate account-linking invite**
+   - `PUT /admin/realms/{realm}/users/{userId}/execute-actions-email` with `["link-tide-account-action"]`.
+   - Or: `GET /admin/realms/{realm}/tide-admin/get-required-action-link?userId={userId}` for a direct URL.
+   - Admin must complete this link in a browser to bind their identity to the Tide Fabric.
+
+9. **Wait for account linking**
+   - Poll `GET /admin/realms/{realm}/users/{userId}` until `attributes.tideUserKey` and `attributes.vuid` are present.
+   - Do not proceed until both attributes exist.
+
+## Phase 4: Change-set approval
+
+10. **Approve pending change-sets**
+    - IGA creates draft change-sets for client and user mutations made during setup.
+    - List: `GET /admin/realms/{realm}/tide-admin/change-set/{type}/requests` for types `clients`, `users`.
+    - For each pending change-set:
+      - Sign: `POST /admin/realms/{realm}/tide-admin/change-set/sign` (requires admin doken).
+      - Commit: `POST /admin/realms/{realm}/tide-admin/change-set/commit`.
+    - Without this step, client and user changes are in draft state and not active.
+
+## Phase 5: IDP settings and adapter export
+
+11. **Configure IDP settings (optional)**
+    - Upload branding (logo, background) if desired.
+    - Set `CustomAdminUIDomain` if a separate app hosts the approval UI.
+
+12. **Sign IDP settings**
+    - `POST /admin/realms/{realm}/identity-provider/instances/tide` (PUT to update, then sign).
+    - Required after any IDP config change. Without it, the enclave rejects settings as unsigned.
+
+13. **Export adapter JSON**
+    - `GET /admin/realms/{realm}/vendorResources/get-installations-provider?clientId={clientUuid}&providerId=keycloak-oidc-keycloak-json`.
+    - Do NOT use the standard Keycloak path (`/clients/{id}/installation/providers/...`) — it returns a minimal adapter missing `jwk`, `vendorId`, `homeOrkUrl`.
+    - Save to app config path (e.g., `data/tidecloak.json`).
+    - Verify `jwk`, `vendorId`, `homeOrkUrl`, `client-origin-auth-*` fields are present.
+    - If `jwk` is missing: IGA was not enabled before export. Re-enable IGA and re-export.
+
+## Phase 6: Policy setup (app-level)
+
+14. **Seed Forseti contract template**
+    - On first org access, the app seeds a default `PolicyTemplate` with C# `IAccessPolicy` contract code.
+    - Contract implements `ValidateData` (VVK signature verification), `ValidateApprovers` (tide-realm-admin check), `ValidateExecutor` (org-scoped role check).
+    - This is app-level logic, not a TideCloak admin step.
+
+15. **Create and approve policy roles (BROWSER-ONLY — cannot be scripted)**
+    - App creates pending PolicyApprovals for `appUser` and `orgOwner` during org membership sync.
+    - Admin must approve and commit these PolicyApprovals so `signed_policy_data` is populated.
+    - Until `appUser` is committed with `signed_policy_data`, the crypto policy endpoint returns null and **shared encryption is completely non-functional**. VERIFIED (session-002).
+    - Until `orgOwner` is committed, org admin operations requiring VVK-verified user context fail.
+    - **This step requires the admin's browser** — it cannot be automated from a bootstrap script. The signing ceremony involves `IAMService._tc.createTideRequest()`, operator approval popup, admin-policy fetch (CORS-proxied), and `executeSignRequest()`.
+    - **The app must include an admin signing page** (or equivalent UI) for this step. Without it, shared encryption is broken by default. The init script cannot complete this phase.
+    - **Anti-pattern**: Silently falling back from shared encryption to self-encryption when the policy is unsigned. Self-encrypted data can never be shared. Block the shared mode entirely until the policy is signed and show a clear admin setup CTA. VERIFIED (session-002).
+
+16. **Create org-scoped client roles**
+    - App creates `org:{uuid}:{owner|admin|user|manager|accessAll}` client roles in TideCloak during org sync.
+    - These go through IGA change-sets and must be approved.
+    - `appUser` is added as composite to `org:{uuid}:user` so standard members get encryption capability.
+
+## Phase 7: App readiness
+
+17. **Place adapter JSON in app**
+    - Next.js: `data/tidecloak.json`
+    - React/Vite or Vanilla: `public/tidecloak.json`
+
+18. **Configure CSP**
+    - Add `frame-src '*'` to Content-Security-Policy. Required for ORK enclave iframe.
+
+19. **Start app server**
+    - App must be able to reach TideCloak at the URL in `auth-server-url`.
+    - App must serve the redirect handler at the configured `redirectUri` path.
+    - App must serve `silent-check-sso.html` in `public/` for session refresh.
+
+## Pre-user checklist
+
+Before any user accesses the app, verify:
+
+- [ ] TideCloak healthy (`/health/ready` returns 200)
+- [ ] Realm licensed and IGA enabled
+- [ ] At least one admin with linked Tide account
+- [ ] All pending change-sets approved and committed
+- [ ] Self-encryption roles exist and are in default-roles composite
+- [ ] `appUser` PolicyApproval committed with non-empty `signed_policy_data`
+- [ ] `orgOwner` PolicyApproval committed with non-empty `signed_policy_data`
+- [ ] Forseti contract template seeded
+- [ ] Adapter JSON exported with `jwk`, `vendorId`, `homeOrkUrl`
+- [ ] `sign-idp-settings` called
+- [ ] App server running and reachable
+- [ ] Redirect handler present at `redirectUri` path
+- [ ] CSP includes `frame-src '*'`

package/reference-apps/organisation-password-manager/manifest.yaml

@@ -0,0 +1,86 @@
+# Organisation Password Manager — Scenario Manifest
+
+id: organisation-password-manager
+title: Organisation Password Manager
+category: credential-vault
+description: Shared credential vault with self-encryption plus policy-governed encryption via Forseti contracts
+
+frameworks:
+  - nextjs
+  - react-vite
+  - rust
+  - vanilla
+
+core_patterns:
+  - self-encryption
+  - self-decryption
+  - policy-governed-encryption
+  - forseti
+  - doken
+  - dpop
+  - iga
+  - oidc
+  - vvk
+  - credential-vault
+  - password-manager
+  - e2ee
+  - org-scoped-roles
+
+match_keywords:
+  - 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
+  - sharing of encrypted
+  - sharing encrypted
+  - people can decrypt
+  - others can decrypt
+  - secure data sharing
+  - data sharing
+  - share selectively
+
+bootstrap_required: true
+requires_admin_preapproval: true
+requires_iga: true
+requires_e2ee: true
+encryption_mode: self-encryption + policy-governed
+
+default_roles:
+  - _tide_enabled
+  - _tide_<tag>.selfencrypt
+  - _tide_<tag>.selfdecrypt
+
+policy_roles:
+  - appUser
+  - orgOwner
+
+org_role_pattern: "org:{uuid}:{owner|admin|user|manager}"
+
+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
+
+discriminating_question: Do multiple users need to encrypt/decrypt the same data (shared credentials, team secrets)? If only the encrypting user decrypts, use self-encryption instead of this scenario.
+valid_only_when: Cross-user decryptability is required. At least two users share encrypted data.
+
+notes: Two encryption layers. Self-encryption for per-user vault data. Policy-governed encryption via appUser/orgOwner Forseti contracts for org-scoped access control. Replace <tag> with app name.

package/reference-apps/organisation-password-manager/role-policy-matrix.md

@@ -0,0 +1,59 @@
+# Role-Policy Matrix — Organisation Password Manager
+
+## Tide bootstrap roles
+
+| Role | Purpose | Attached policy | Created by | Approved by | Required before first use | Default / optional | Notes |
+|------|---------|----------------|------------|-------------|--------------------------|-------------------|-------|
+| `_tide_enabled` | Enables Tide operations for user | None (gate role) | Realm template | N/A (declared in realm.json) | Yes | Default | Must be in realm.json. Not auto-created. |
+| `_tide_<tag>.selfencrypt` | Allows user to encrypt data with own key | Voucher gate: selfencrypt | Admin via IGA | Tide realm admin(s) | Yes | Default | Include in default-roles composite so all users get it. |
+| `_tide_<tag>.selfdecrypt` | Allows user to decrypt own encrypted data | Voucher gate: selfdecrypt | Admin via IGA | Tide realm admin(s) | Yes | Default | Include in default-roles composite so all users get it. |
+| `tide-realm-admin` | Full realm administration | N/A | Bootstrap script | N/A (first admin) | Yes (at least one) | Required | Client role on `realm-management`, not a realm role. |
+
+## Policy-governed roles (Forseti contract-backed)
+
+| Role | Purpose | Attached policy | Created by | Approved by | Required before first use | Default / optional | Notes |
+|------|---------|----------------|------------|-------------|--------------------------|-------------------|-------|
+| `appUser` | Crypto policy for encrypt/decrypt operations | Forseti contract; `signed_policy_data` served as active crypto policy | App on first org sync | Tide realm admin(s) via IGA | Yes (for encryption) | Default | PolicyApproval must be committed with non-empty `signed_policy_data` before encryption works. |
+| `orgOwner` | User-context signing with VVK verification | Forseti contract with VVK public key validation | App on first org sync | Tide realm admin(s) via IGA | Yes (for org admin ops) | Default | Contract validates `org:{uuid}:{role}` pattern and verifies user context signature against VVK. |
+
+## Org-scoped client roles (per organisation)
+
+| Role pattern | Purpose | Attached policy | Created by | Approved by | Required before first use | Default / optional | Notes |
+|-------------|---------|----------------|------------|-------------|--------------------------|-------------------|-------|
+| `org:{uuid}:owner` | Org owner (highest privilege) | Inherits `orgOwner` composites + `accessAll` | App on org creation | IGA change-set | No (created per org) | Per-org | Maps to Bitwarden Owner membership type. |
+| `org:{uuid}:admin` | Org administrator | None beyond membership | App on member invite | IGA change-set | No | Per-org | Maps to Bitwarden Admin membership type. |
+| `org:{uuid}:user` | Org member (standard) | Inherits `appUser` composite | App on member invite | IGA change-set | No | Per-org | Maps to Bitwarden User membership type. Gets encryption capability via `appUser`. |
+| `org:{uuid}:manager` | Org manager | None beyond membership | App on member invite | IGA change-set | No | Per-org | Maps to Bitwarden Manager membership type. |
+| `org:{uuid}:accessAll` | Full collection access within org | None | App on org creation | IGA change-set | No | Per-org | Composite of owner role. Grants access to all collections. |
+
+## Key rules
+
+1. `_tide_enabled` must be declared in `realm.json`. It is not auto-created by `setUpTideRealm`.
+2. Self-encryption roles must exist and be assigned before any user attempts to encrypt or decrypt.
+3. `appUser` PolicyApproval must be committed with `signed_policy_data` before the crypto policy endpoint returns usable data.
+4. `orgOwner` PolicyApproval must be committed before org admin operations that require VVK-verified user context.
+5. Role assignment changes go through IGA change-sets when IGA is enabled. Roles appear in JWT after next token refresh (up to 120s delay).
+6. `tide-realm-admin` is a client role on `realm-management`, not a realm role.
+7. All role changes after IGA is enabled require change-set approval (draft -> sign -> commit).
+8. Org-scoped roles use the pattern `org:{uuid}:{suffix}`. The Forseti contract validates this pattern and extracts the org UUID for scope enforcement.
+
+## Forseti contract structure (default template)
+
+The default seeded contract implements `IAccessPolicy` with three validators:
+
+| Validator | What it checks |
+|-----------|---------------|
+| `ValidateData` | Extracts org UUID from executor role. Validates user context array from draft against previous signed user context. Verifies VVK public key signature. |
+| `ValidateApprovers` | Checks that approvers hold `tide-realm-admin` role. |
+| `ValidateExecutor` | Checks that executor holds an `org:{uuid}:{role}` role matching the allowed org. |
+
+## Encryption role naming convention
+
+| Pattern | Mode | Use case |
+|---------|------|----------|
+| `_tide_<tag>.selfencrypt` | Self-encryption | User encrypts with own key. No sharing. |
+| `_tide_<tag>.selfdecrypt` | Self-decryption | User decrypts own data via ORK threshold. |
+| `appUser` | Policy-governed | Crypto policy for encrypt/decrypt. `signed_policy_data` served to clients. |
+| `orgOwner` | Policy-governed | User-context signing with VVK verification for org admin operations. |
+
+This scenario uses both self-encryption and policy-governed encryption.

package/reference-apps/organisation-password-manager/scenario.md

@@ -0,0 +1,107 @@
+# Organisation Password Manager
+
+## What this is
+
+A shared credential vault where organisation members store, encrypt, and retrieve passwords and secrets. Uses two Tide encryption layers:
+
+1. **Self-encryption** — each user's vault data is encrypted with their own Tide-managed key via `_tide_<tag>.selfencrypt` / `_tide_<tag>.selfdecrypt` roles.
+2. **Policy-governed encryption** — org-scoped `appUser` and `orgOwner` roles carry Forseti contracts with `signed_policy_data`. The `appUser` crypto policy governs who can perform encryption/decryption operations. The `orgOwner` contract enforces user-context signing with VVK verification.
+
+No server, admin, or single ORK can read stored credentials.
+
+## When to use this scenario
+
+Use when the user describes:
+- a team or organisation password manager
+- a shared credential vault or secret store
+- a Vaultwarden/Bitwarden-style self-hosted vault with Tide
+- any app where multiple users each store encrypted credentials with org-scoped access control
+
+Do NOT use when:
+- the user describes a single-user private vault with no org structure
+- the user needs only basic auth without encryption
+
+## Core Tide capabilities used
+
+1. **TideCloak OIDC authentication** — zero-knowledge login, no master password stored
+2. **DPoP token binding** — access tokens bound to device/session
+3. **Self-encryption / self-decryption** — per-user E2EE via `_tide_<tag>.selfencrypt` / `_tide_<tag>.selfdecrypt` roles
+4. **Policy-governed encryption** — `appUser` role with Forseti contract and `signed_policy_data` as the active crypto policy for encrypt/decrypt operations
+5. **User-context signing** — `orgOwner` role with Forseti contract that validates user context against VVK public key
+6. **Doken** — delegation token for ORK-mediated crypto operations
+7. **IGA (Identity Governance)** — role/policy changes require multi-admin approval via change-sets
+8. **Forseti contracts** — C# smart contracts enforce role-assignment approval thresholds, org-scoped access, and VVK signature verification
+9. **Org-scoped client roles** — `org:{uuid}:{owner|admin|user|manager}` pattern for per-org membership mapping
+
+## What must exist before first user access
+
+1. TideCloak running with a realm for the app
+2. Realm licensed (`setUpTideRealm`) and IGA enabled (`toggle-iga`)
+3. Admin user created, Tide account linked, `tide-realm-admin` role assigned
+4. Initial client and user change-sets approved and committed
+5. Self-encryption roles (`_tide_<tag>.selfencrypt`, `_tide_<tag>.selfdecrypt`) created and included in the default role composite
+6. `appUser` and `orgOwner` PolicyApprovals created, approved, and committed with `signed_policy_data`
+7. Forseti contract template seeded (default `IAccessPolicy` with org-scoped validation and VVK verification)
+8. `sign-idp-settings` called after any IDP config changes
+9. Adapter JSON exported to app (`tidecloak.json`) with `jwk`, `vendorId`, `homeOrkUrl`, `client-origin-auth-*`
+10. App server running and able to reach TideCloak
+
+## Admin/bootstrap-only steps
+
+- Start TideCloak container
+- Import realm template
+- Call `setUpTideRealm` and `toggle-iga`
+- Create admin user and generate account-linking invite
+- Approve pending change-sets (client, user)
+- Create self-encryption roles if not in realm template
+- Seed default Forseti contract template
+- Upload branding / configure IDP settings + `sign-idp-settings`
+- Export adapter JSON
+
+## Runtime user flow
+
+1. User visits app (web vault or browser extension)
+2. App redirects to TideCloak for OIDC login
+3. TideCloak authenticates via threshold PRISM (zero-knowledge)
+4. TideCloak returns access token + refresh token + doken + id token
+5. App server validates JWT (signature + claims + DPoP)
+6. On first org access, app syncs membership to TideCloak: creates org-scoped client roles (`org:{uuid}:{role}`), creates pending PolicyApprovals for `orgOwner` and `appUser`
+7. User creates vault entries: client fetches crypto policy (`signed_policy_data` from committed `appUser` approval), encrypts fields client-side, sends ciphertext to server
+8. User retrieves entries: client requests decryption via doken + ORK threshold + crypto policy
+9. Plaintext exists only in client memory, never stored server-side
+
+## Default playbook sequence
+
+1. `start-tidecloak-dev`
+2. `bootstrap-realm-from-template`
+3. `initialize-admin-and-link-account`
+4. `configure-e2ee-roles-and-policies` (self-encryption mode + policy-governed mode)
+5. `add-auth-nextjs-fresh` (or framework-appropriate equivalent)
+6. `protect-routes-nextjs`
+7. `protect-api-nextjs`
+8. `verify-jwt-server-side`
+9. `add-rbac-nextjs`
+
+## Key diagnostics
+
+| Symptom | Likely cause |
+|---------|-------------|
+| Login hangs or blank screen | CSP missing `frame-src '*'`, or redirect handler missing |
+| Encryption fails silently | Self-encryption roles not assigned, or doken expired, or `appUser` crypto policy not committed |
+| `get_crypto_policy` returns null | `appUser` PolicyApproval not committed or has empty `signed_policy_data` |
+| Roles missing from JWT | IGA change-set not committed, or token not refreshed (up to 120s delay) |
+| Adapter JSON missing `jwk` | IGA not enabled on realm before export |
+| `client-origin-auth-*` mismatch | `sign-idp-settings` not called after origin change |
+| Decryption returns error | User lacks `_tide_<tag>.selfdecrypt` role, or ORK threshold not met, or crypto policy missing |
+| Org membership sync fails | Client roles not created in TideCloak, or `org:{uuid}:{role}` pattern mismatch |
+| VVK verification fails in contract | VVK public key not available, or user context signature invalid |
+
+## Intentionally configurable
+
+- **Encryption tag name**: `<tag>` in `_tide_<tag>.selfencrypt` is app-specific (e.g., `vaultwarden`, `vault`)
+- **Org-scoped roles**: Apps define org role patterns (e.g., `org:{uuid}:owner`, `org:{uuid}:admin`)
+- **Forseti contract logic**: Default template validates org scope and VVK signatures; apps can customize validation rules
+- **Approval thresholds**: IGA admin quorum and Forseti contract thresholds are deployment-configurable
+- **Browser extension support**: Optional. Requires adding extension redirect URIs to OIDC client config
+- **Database backend**: App-specific choice (SQLite, PostgreSQL, MySQL)
+- **Per-field vs whole-record encryption**: App decides granularity; Tide encrypts whatever the client sends

package/reference-apps/policy-governed-signing/anti-patterns.md

@@ -0,0 +1,67 @@
+# Anti-Patterns — Policy-Governed Signing
+
+Scenario-specific mistakes. Each defeats a security property or causes a setup failure.
+
+## AP-PS01: Skipping IGA before role creation
+
+Creating signing roles before enabling IGA means those role changes are not governed. Enable IGA first, then create roles so they go through the change-set approval flow.
+
+## AP-PS02: Using signing without a committed policy
+
+The signing role must have a committed PolicyApproval with non-empty `signed_policy_data` before ORKs will accept signing requests. If the policy is not committed, `executeSignRequest` will fail. Do not assume signing works immediately after role creation.
+
+## AP-PS03: Hardcoding the signing key
+
+The entire point of this pattern is that no single entity holds the signing key. Do not generate, store, or manage signing keys in the app. The key exists only as threshold shares across independent ORKs.
+
+## AP-PS04: Omitting DPoP on protected API routes
+
+DPoP binds the access token to the device/session. Without DPoP verification on API routes, a stolen access token can be replayed from a different device. Verify DPoP proof on every protected endpoint.
+
+## AP-PS05: Using `createRemoteJWKSet` for JWT verification
+
+Use `createLocalJWKSet(config.jwk)` only. Remote JWKS fetch introduces a network dependency and a potential MITM vector. If `jwk` is missing from the adapter JSON, re-export with IGA enabled.
+
+## AP-PS06: Forgetting `sign-idp-settings` after config changes
+
+Any change to IDP settings (logo, origins, admin domain) must be followed by `sign-idp-settings`. Without it, the ORK enclave rejects the settings as unsigned. Login and signing will fail silently.
+
+## AP-PS07: Weak or missing `ValidateData` in the Forseti contract
+
+The `ValidateData` method is the primary safety gate. If it accepts arbitrary data, the ORKs will sign anything the executor submits. Validate the data structure, size, format, and semantics. For SSH: parse the SSHv2 publickey challenge. For documents: check hash format and size. Never return `PolicyDecision.Allow()` unconditionally.
+
+## AP-PS08: Skipping `ValidateExecutor` in the Forseti contract
+
+The `ValidateExecutor` method must check that the executor's doken contains the required signing role and is not expired. Without it, any authenticated user can request signatures for any role.
+
+## AP-PS09: Using wrong adapter provider ID
+
+The provider ID is `keycloak-oidc-keycloak-json`. The string `tidecloak-oidc-keycloak-json` does not exist. Using the wrong ID returns an error or a generic adapter without Tide fields.
+
+## AP-PS10: Assuming roles appear instantly after IGA commit
+
+After a change-set is committed, roles appear in JWT/doken on the next token refresh. This can take up to 120 seconds. Do not treat immediate post-commit token checks as authoritative.
+
+## AP-PS11: Hiding signing UI without protecting the API
+
+Hiding the "Sign" button for unauthorized users is UI gating only. The API endpoint that handles signing must independently verify JWT signature, claims, roles, and DPoP. A hidden button is not a security boundary.
+
+## AP-PS12: Skipping change-set approval during bootstrap
+
+After IGA is enabled, client and user mutations create draft change-sets. If these are not signed and committed, the changes remain in draft state. The realm appears configured but clients and users are not fully active.
+
+## AP-PS13: Creating policies with wrong model ID
+
+The model ID in the policy must match the request pattern used by the client. `BasicCustom<SSH>:BasicCustom<1>` is for `BasicCustomRequest`. `DynamicCustom<SSH>:DynamicCustom<1>` is for `DynamicCustomRequest`. A mismatch causes ORK rejection.
+
+## AP-PS14: Omitting contract transport from PolicySignRequest
+
+The PolicySignRequest draft must include both the serialized policy bytes and the contract transport (source code + entry type). Without the contract transport, ORKs cannot compile and execute the Forseti contract. The contract ID (SHA-512 of source) must match.
+
+## AP-PS15: Using blocked namespaces in Forseti contracts
+
+The ORK Forseti sandbox blocks: `System.IO`, `System.Net`, `System.Diagnostics`, `System.Threading`, `System.Reflection`, `System.Runtime.InteropServices`, `System.Reflection.Emit`, `Microsoft.Win32`. Hard-blocked: `System.Console`, `System.Runtime.CompilerServices.Unsafe`. Using any blocked namespace causes `BadPolicy.ForbiddenCall`.
+
+## AP-PS16: Not setting custom expiry on PolicySignRequest
+
+`PolicySignRequest.setCustomExpiry()` controls how long the policy remains valid. If not set or set too short, policies expire and signing stops working. The keylessh exemplar uses 604800 seconds (7 days). Choose an appropriate TTL for your use case.