@tideorg/mcp 1.4.0

package/reference-apps/encrypted-communication/scenario.md

@@ -0,0 +1,134 @@
+# Encrypted Real-Time Communication
+
+## What this is
+
+A real-time communication app (chat, video calls, or both) where all user content is end-to-end encrypted. TideCloak handles authentication and protects long-lived private key material at rest via self-encryption. A separate client-side crypto library handles runtime E2E operations (message encryption, media frame encryption, key exchange). The server stores only ciphertext and never sees plaintext content or private keys.
+
+This is a **hybrid encryption** pattern:
+- **Layer 1 (Tide)**: Self-encryption protects the user's private key stored in the database.
+- **Layer 2 (external crypto)**: A client-side library (e.g., libsodium, WebCrypto) uses the decrypted private key for runtime E2E operations.
+
+---
+
+## When to use this scenario
+
+Use when the app needs:
+- Real-time encrypted messaging (1:1 or group)
+- Encrypted voice/video calls
+- Zero-knowledge server (server stores ciphertext only)
+- Per-user asymmetric key pairs with Tide-protected private key storage
+- Forward secrecy via key rotation when group membership changes
+- Runtime encryption that Tide's built-in `doEncrypt`/`doDecrypt` does not cover (e.g., streaming media frame encryption, libsodium `crypto_secretbox`, WebCrypto `AES-GCM`)
+
+Do NOT use when:
+- Data is encrypted at rest and does not need real-time streaming decryption — use `organisation-password-manager` instead
+- Only the encrypting user needs to decrypt — use standard self-encryption via `tide-rbac-and-e2ee`
+- The app needs cryptographic signing, not encryption — use `policy-governed-signing`
+- The app only needs authentication with no encryption — use standard auth playbooks
+
+---
+
+## Core Tide capabilities used
+
+| Capability | Role in this scenario |
+|-----------|----------------------|
+| TideCloak SSO (OIDC) | Core: user authentication, JWT-based identity |
+| Self-encryption (`doEncrypt`/`doDecrypt`) | Core: encrypt/decrypt user's private key for storage |
+| `_tide_<tag>.selfencrypt` / `_tide_<tag>.selfdecrypt` roles | Core: gate access to self-encryption operations |
+| `_tide_enabled` role | Core: required for all Tide operations |
+| Server-side JWT verification | Required: protect API endpoints that store/serve encrypted key material |
+| DPoP (optional but recommended) | Recommended: bind tokens to client for API protection |
+| IGA | Required: approve role assignments before E2E works |
+
+**Not used in the default self-encryption path**: Policy-governed encryption, Forseti contracts, VVK shared encryption, doken-based signing.
+
+**Shared encryption variant**: If the app needs Tide-native shared encryption (recipients decrypt ciphertext via `IAMService.doDecrypt` with policy bytes), add `setup-forseti-e2ee` to the playbook sequence. This requires a Forseti contract, admin signing ceremony, and additional roles. See `role-policy-matrix.md` for details. VERIFIED (LEARNINGS-batch-009 L-06).
+
+---
+
+## What must exist before first user access
+
+1. TideCloak running with a licensed, IGA-enabled realm
+2. Realm roles: `_tide_enabled`, `_tide_<tag>.selfencrypt`, `_tide_<tag>.selfdecrypt` in the default composite
+3. At least one admin user with `tide-realm-admin` linked and initial change requests committed
+4. Adapter JSON exported with `jwk` field
+5. App deployed with TideCloak provider and server-side JWT verification
+6. Database table for storing encrypted key material (public key + Tide-encrypted private key per user)
+
+---
+
+## Bootstrap-only steps (admin)
+
+1. Start TideCloak container
+2. Create realm from template with self-encryption roles
+3. License realm (`setUpTideRealm`)
+4. Enable IGA (`toggle-iga`)
+5. Create admin user, assign `tide-realm-admin`, generate invite link
+6. Admin completes Tide account linking
+7. Approve and commit initial change requests (client, user, role)
+8. Sign IDP settings (`sign-idp-settings`)
+9. Export adapter JSON to app
+
+---
+
+## Runtime user flow
+
+On **first login** for a new user:
+1. User authenticates via TideCloak SSO
+2. App checks database for existing encrypted key material
+3. No keys found → app generates a new asymmetric keypair client-side (e.g., `crypto_box_keypair()`)
+4. App encrypts the private key using `doEncrypt(privateKeyBytes, tag)` (Tide self-encryption)
+5. App stores the encrypted private key and the public key in the database via a protected API endpoint
+6. Private key is now available in memory for runtime E2E operations
+
+On **returning login**:
+1. User authenticates via TideCloak SSO
+2. App fetches encrypted key material from database
+3. App decrypts the private key using `doDecrypt(encryptedPrivateKey, tag)` (Tide self-encryption)
+4. Private key is now available in memory for runtime E2E operations
+
+**Runtime E2E operations** (not Tide — handled by external crypto library):
+- Key exchange: use the decrypted private key + recipient's public key to derive shared secrets
+- Message encryption: symmetric encryption (e.g., `crypto_secretbox`) with conversation keys
+- Media frame encryption: per-frame symmetric encryption for WebRTC Insertable Streams
+- Key rotation: generate new conversation key when group membership changes, re-encrypt for all members
+
+---
+
+## Default playbook sequence
+
+1. `start-tidecloak-dev`
+2. `bootstrap-realm-from-template`
+3. `initialize-admin-and-link-account`
+4. `configure-e2ee-roles-and-policies`
+5. `add-auth-nextjs-fresh` (adapt for React/Vite if not Next.js)
+6. `protect-routes-nextjs`
+7. `protect-api-nextjs`
+8. `verify-jwt-server-side`
+9. `add-rbac-nextjs`
+
+---
+
+## Key diagnostics
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| `doEncrypt` fails with "User has not been given any access to 'tag'" | Missing `_tide_<tag>.selfencrypt` role | Assign role, approve via IGA, re-login |
+| `doDecrypt` fails with same error | Missing `_tide_<tag>.selfdecrypt` role | Assign role, approve via IGA, re-login |
+| `doDecrypt` fails on stored ciphertext | User does not own this ciphertext (self-encryption is identity-bound) | Verify the same user encrypted it |
+| Key material API returns 401 | JWT verification failing | Check token, DPoP proof, adapter `jwk` |
+| Private key decrypts but E2E still fails | Runtime crypto library error, not Tide | Debug the external crypto separately |
+| New user cannot decrypt old group messages | Expected: forward secrecy means pre-join messages are inaccessible | Store key history per version if historical access is needed |
+| Login completes but encrypt/decrypt unavailable | Roles not in token yet (120s delay after IGA commit) | Re-login or wait for token refresh |
+
+---
+
+## Intentionally configurable
+
+- **Crypto library**: libsodium, WebCrypto, tweetnacl, or any client-side crypto library. Tide does not constrain this choice.
+- **Key type**: Ed25519/X25519 (libsodium), ECDH P-256 (WebCrypto), or any asymmetric scheme. The private key is just bytes to `doEncrypt`.
+- **Encryption tag**: Any short alphanumeric string (e.g., `keys`, `self`, `chat`). Must match the `_tide_<tag>` roles in the realm.
+- **Key storage schema**: The database schema for storing encrypted keys is app-defined. Minimum: user ID, public key, encrypted private key.
+- **Key rotation strategy**: App-defined. Common: rotate conversation key on member join/leave for forward secrecy.
+- **Transport**: WebSocket, WebRTC, HTTP polling, or any transport. Tide does not constrain this.
+- **Message format**: App-defined. Tide only touches the private key storage, not the message wire format.

package/reference-apps/git-pr-signing-service/anti-patterns.md

@@ -0,0 +1,61 @@
+# Anti-Patterns — Git PR Signing Service
+
+Scenario-specific mistakes. Each defeats a security property or causes a setup failure. Inherits all anti-patterns from `policy-governed-signing` (AP-PS01 through AP-PS16).
+
+## AP-GS01: Signing commits without webhook signature verification
+
+The service receives GitHub webhooks to trigger the signing flow. If it does not verify the HMAC-SHA256 webhook signature, an attacker can forge webhook payloads to trigger signing of arbitrary commits. Verify every webhook payload against the shared secret before processing.
+
+## AP-GS02: Using cosign or gitsign as intermediary
+
+cosign is for OCI container image signing. gitsign is for local developer-side signing via Fulcio/Rekor. Neither maps to a server-side PR-based signing service. Use the GitHub Git Data API directly to create signed commits.
+
+## AP-GS03: Signing without quorum — single admin approval
+
+The entire point of threshold signing with Forseti governance is that no single individual can authorize a signature. If the Forseti contract threshold is 1, any single compromised admin account can sign arbitrary code. Set threshold >= 2 for production.
+
+## AP-GS04: Trusting GitHub PR metadata without re-validating
+
+The webhook payload includes PR metadata (author, branch, reviewers, labels). The Forseti contract's `ValidateData` must parse and validate the actual commit bytes, not trust metadata from the webhook. Webhook payloads are GitHub's representation; the commit bytes are the cryptographic truth.
+
+## AP-GS05: Storing the threshold Ed25519 private key
+
+The threshold private key never exists in complete form anywhere. The service receives only the raw 64-byte signature from ORKs, never the key. If you find yourself storing, generating, or assembling a private key, you have broken I-01 (never-whole-key).
+
+## AP-GS06: Skipping SSH wire format wrapping
+
+GitHub requires SSH signature format (`BEGIN SSH SIGNATURE` block) for commit verification. Submitting the raw 64-byte Ed25519 signature to the Git Data API will not produce a "Verified" badge. The wrapping is a non-cryptographic transformation that must happen after ORK signing and before the GitHub API call.
+
+## AP-GS07: Using master admin credentials in the service
+
+The service must use admin OIDC tokens acquired via browser login for Tide operations (approval collection, signing requests). It must use GitHub App installation tokens for GitHub API calls. Do not embed `admin`/`password` or GitHub personal access tokens in the service. See AP-41.
+
+## AP-GS08: Allowing merge without signing service status check
+
+If branch protection does not require the signing service's status check, developers can merge PRs directly — bypassing threshold signing entirely. The branch protection rule is the enforcement point that routes all merges through the service.
+
+## AP-GS09: Signing merge commits for the wrong branch
+
+The Forseti contract should validate that the target branch matches the signing role's scope (e.g., `git-sign:main` should only sign merges to `main`). Without this check, a `git-sign:main` approval could be used to sign a merge to any branch.
+
+## AP-GS10: Not verifying GitHub App token permissions at startup
+
+The service authenticates to GitHub as a GitHub App installation. If the App's permissions are insufficient (missing `checks:write`, `contents:write`, or `pull_requests:read`), operations fail at runtime with opaque 403 errors. Verify permissions at service startup.
+
+## AP-GS11: Assuming signed commits appear instantly
+
+After creating a signed commit via the GitHub Git Data API and updating the branch ref, GitHub may take a few seconds to process the signature verification. Do not assert "Verified" badge presence immediately after the API call. The check run should be updated to success after the ref update, not after badge verification.
+
+## AP-GS12: Re-using admin dokens across PRs
+
+Each signing operation should use fresh admin approvals (dokens) specific to that PR's commit bytes. Re-using dokens from a previous PR approval would sign different data than what the admins reviewed. The Forseti contract's `ValidateData` should include PR-specific context to prevent replay.
+
+## AP-GS13: Using GitHub merge API for tree computation
+
+`POST /repos/{owner}/{repo}/merges` creates a **real merge commit** and advances the base branch. It is NOT a dry-run. Using it to compute the merge tree SHA causes PRs to be merged without threshold signatures — defeating the entire purpose of the signing service.
+
+**Correct**: Use `GET /repos/{owner}/{repo}/git/commits/{headSha}` to read the head commit's tree SHA (no side effects). Build the merge commit payload from the tree SHA and both parent SHAs.
+
+**Wrong**: `POST /repos/{owner}/{repo}/merges` with `base` and `head` — this performs a real merge.
+
+VERIFIED (LEARNINGS-ratidefy-batch-001 L-14).

package/reference-apps/git-pr-signing-service/bootstrap-sequence.md

@@ -0,0 +1,157 @@
+# Bootstrap Sequence — Git PR Signing Service
+
+All steps must complete before the service can sign merge commits. Order matters.
+
+## Phase 1: TideCloak infrastructure
+
+1. **Start TideCloak container**
+   - Use `tidecloak-dev` (development) or `tidecloak-stg-dev` (staging with ORK env vars).
+   - 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 for the signing service, `_tide_enabled` role, default-roles composite, protocol mappers.
+   - Template should include redirect URIs for the signing service's web UI.
+
+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`.
+
+5. **Enable IGA**
+   - `POST /admin/realms/{realm}/tide-admin/toggle-iga` with form-urlencoded `isIGAEnabled=true`.
+   - Must happen after licensing.
+
+## Phase 3: Approve initial change-sets
+
+6. **Approve client change-sets**
+   - List: `GET /admin/realms/{realm}/tide-admin/change-set/clients/requests`.
+   - For each: sign (`POST .../change-set/sign`) then commit (`POST .../change-set/commit`).
+
+## Phase 4: Admin user setup
+
+7. **Create admin user(s)**
+   - `POST /admin/realms/{realm}/users` with username, email, enabled=true.
+   - Create at least as many admins as your signing policy threshold requires (e.g., 2 for threshold=2).
+
+8. **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}`.
+
+9. **Generate account-linking invites**
+   - For each admin: `POST /admin/realms/{realm}/tideAdminResources/get-required-action-link?userId={userId}&lifespan=43200` with body `["link-tide-account-action"]`.
+   - Each admin must complete linking in a browser.
+
+10. **Wait for account linking**
+    - Poll `GET /admin/realms/{realm}/users/{userId}` until `attributes.tideUserKey` and `attributes.vuid` are present for each admin.
+
+## Phase 5: Approve user change-sets
+
+11. **Approve user change-sets**
+    - List: `GET /admin/realms/{realm}/tide-admin/change-set/users/requests`.
+    - For each: sign then commit.
+
+## Phase 6: IDP settings and adapter export
+
+12. **Sign IDP settings**
+    - `POST /admin/realms/{realm}/vendorResources/sign-idp-settings`.
+    - Required after any IDP config change.
+
+13. **Export adapter JSON**
+    - `GET /admin/realms/{realm}/vendorResources/get-installations-provider?clientId={clientUUID}&providerId=keycloak-oidc-keycloak-json`.
+    - Save to `data/tidecloak.json`.
+    - Verify `jwk`, `vendorId`, `homeOrkUrl`, `client-origin-auth-*` fields are present.
+
+## Phase 7: Signing role and policy setup
+
+14. **Create signing roles**
+    - Create client roles: `git-sign:main`, `git-sign:develop`, etc. as needed.
+    - Create service executor role: `signing-service`.
+    - Role creation goes through IGA change-sets. Approve and commit.
+
+15. **Assign signing roles**
+    - Assign `git-sign:<branch>` roles to admin users who will approve PRs for those branches.
+    - Assign `signing-service` role to the service's own identity (if using a service account pattern) or to the admin who triggers the signing execution.
+    - Role assignments go through IGA change-sets. Approve and commit.
+
+16. **Create and approve signing policies**
+    - Create a PolicySignRequest with:
+      - Forseti contract: `GitCommitSigningPolicy` (see role-policy-matrix.md)
+      - Parameters: `Role` = `git-sign:main`, `Resource` = client ID, `threshold` = 2
+      - Model ID: `BasicCustom<GitSign>:BasicCustom<1>`
+      - Contract transport: source + entry type
+    - PolicyApproval must be signed and committed so `signed_policy_data` is populated.
+    - Repeat for each branch that needs a separate signing policy.
+
+## Phase 8: GitHub App setup
+
+17. **Register GitHub App**
+    - Create a GitHub App (or bot account) in the target organization.
+    - Permissions required: `checks: write`, `contents: write`, `pull_requests: read`.
+    - Subscribe to webhook events: `pull_request`.
+    - Set webhook URL to the signing service's webhook endpoint (e.g., `https://signing-service.example.com/api/webhook/github`).
+    - Set webhook secret. Store it securely in the service's environment.
+
+18. **Upload threshold public key and configure committer identity**
+    - Export the threshold Ed25519 public key from the adapter JSON's `jwk.keys[0].x` field (base64url-encoded 32-byte key).
+    - Convert to SSH format: `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA<base64> <comment>`.
+    - Add it to a GitHub account as a **Signing Key** (Settings → SSH and GPG Keys → type: Signing Key).
+    - **Critical**: The commit's `committer.email` must match this GitHub account's email. Mismatch produces `unknown_signature_type` instead of "Verified". VERIFIED (LEARNINGS-ratidefy-batch-001 L-26).
+    - **GitHub App limitation**: Bot accounts (e.g., `myapp[bot]`) cannot have SSH keys. Use a dedicated machine user account.
+    - GitHub will verify commit signatures against this key.
+
+19. **Install GitHub App on repositories**
+    - Install the App on the target repositories (or organization-wide).
+    - Verify webhook delivery: push a test PR and confirm the service receives the event.
+
+20. **Configure branch protection**
+    - On each target branch, enable branch protection rules:
+      - Require status checks to pass: add the signing service's check name.
+      - Optionally: require reviews (GitHub-native reviews in addition to Tide-governed approval).
+    - This ensures PRs cannot be merged without the signing service's approval.
+
+## Phase 9: Service readiness
+
+21. **Place adapter JSON in service**
+    - `data/tidecloak.json` for Next.js service.
+
+22. **Configure environment**
+    - `GITHUB_APP_ID` — GitHub App ID
+    - `GITHUB_PRIVATE_KEY` — GitHub App private key (for API authentication)
+    - `GITHUB_WEBHOOK_SECRET` — webhook HMAC secret
+    - `CLIENT_ADAPTER` — (optional) adapter JSON for containerized deployment
+
+23. **Configure CSP**
+    - `frame-src '*'` for ORK enclave iframe.
+
+24. **Start service**
+    - Service must reach TideCloak at `auth-server-url`.
+    - Service must reach GitHub API (`api.github.com`).
+    - Service must serve the redirect handler at configured `redirectUri` path.
+
+## Pre-use checklist
+
+Before the signing service is operational, verify:
+
+- [ ] TideCloak healthy (`/health/ready` returns 200)
+- [ ] Realm licensed and IGA enabled
+- [ ] At least N admins with linked Tide accounts (where N >= signing threshold)
+- [ ] All pending change-sets approved and committed
+- [ ] Signing roles created and assigned (`git-sign:<branch>`, `signing-service`)
+- [ ] Signing PolicyApproval committed with non-empty `signed_policy_data` for each role
+- [ ] Adapter JSON exported with `jwk`, `vendorId`, `homeOrkUrl`
+- [ ] `sign-idp-settings` called
+- [ ] GitHub App registered with correct permissions and webhook events
+- [ ] Threshold Ed25519 public key uploaded to GitHub App/bot as SSH signing key
+- [ ] GitHub App installed on target repositories
+- [ ] Branch protection rules require signing service status check
+- [ ] Webhook delivery confirmed (test PR triggers service)
+- [ ] Service running with JWT + DPoP verification on admin endpoints
+- [ ] Webhook signature verification active (HMAC-SHA256)
+- [ ] Redirect handler present at `redirectUri` path
+- [ ] CSP includes `frame-src '*'`

package/reference-apps/git-pr-signing-service/manifest.yaml

@@ -0,0 +1,80 @@
+# Git PR Signing Service — Scenario Manifest
+
+id: git-pr-signing-service
+title: Git PR Signing Service
+category: threshold-signing
+description: Enterprise PR-based commit signing service. GitHub webhook triggers admin review in web UI; Forseti-governed threshold signing produces signed merge commits with GitHub "Verified" badge. No developer holds a signing key.
+
+frameworks:
+  - nextjs
+
+core_patterns:
+  - forseti
+  - doken
+  - dpop
+  - iga
+  - oidc
+  - threshold-signing
+  - policy-signing
+  - basic-custom-request
+  - policy-sign-request
+  - client-roles
+  - signing
+  - github-webhook
+  - github-api
+  - ssh-signature-format
+
+match_keywords:
+  - 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
+  - sign git tags
+  - sign pull requests
+
+bootstrap_required: true
+requires_admin_preapproval: true
+requires_iga: true
+requires_e2ee: false
+signing_mode: policy-governed
+
+default_roles:
+  - _tide_enabled
+
+policy_roles: []
+
+signing_role_pattern: "git-sign:<branch>"
+
+default_playbooks:
+  - start-tidecloak-dev
+  - bootstrap-realm-from-template
+  - initialize-admin-and-link-account
+  - add-auth-nextjs-fresh
+  - protect-routes-nextjs
+  - protect-api-nextjs
+  - verify-jwt-server-side
+  - add-rbac-nextjs
+  - setup-github-app-signing
+
+discriminating_question: Does the app sign git commits or merges via a server-side service with admin approval? If the app signs SSH challenges, documents, or transactions directly, use `policy-governed-signing` instead.
+valid_only_when: App is a server-side service that receives GitHub webhooks, collects admin approvals, and threshold-signs merge commits via the GitHub API.
+
+notes: >
+  This is a specialization of policy-governed-signing for the git/GitHub domain.
+  The signing service is a Next.js web app — admins authenticate via browser OIDC.
+  Developers never interact with Tide directly; they push code and open PRs as normal.
+  The service signs merge commits via GitHub Git Data API after Forseti-governed admin approval.
+  Ed25519 threshold signatures must be wrapped in SSH wire format for GitHub verification.
+  Requires a GitHub App (or bot account) with the threshold Ed25519 public key registered as an SSH signing key.
+  cosign and gitsign are NOT used — they target container images and local git signing respectively.

package/reference-apps/git-pr-signing-service/role-policy-matrix.md

@@ -0,0 +1,99 @@
+# Role-Policy Matrix — Git PR Signing Service
+
+## 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-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. |
+
+## Signing roles (Forseti contract-backed)
+
+| Role | Purpose | Attached policy | Created by | Approved by | Required before first use | Default / optional | Notes |
+|------|---------|----------------|------------|-------------|--------------------------|-------------------|-------|
+| `git-sign:<branch>` (e.g., `git-sign:main`) | Authorizes signing merge commits to a specific branch | Forseti contract with `signed_policy_data`; validates commit content, approvers, executor | Admin via service UI | Tide realm admin(s) via IGA | Yes (for that branch) | Per-branch | PolicyApproval must be committed before signing works. |
+| `git-sign:*` (optional) | Authorizes signing merge commits to any branch | Same Forseti contract, wildcard match | Admin via service UI | Tide realm admin(s) via IGA | No | Optional | Use for admins who can approve merges to any branch. |
+
+## Service identity roles
+
+| Role | Purpose | Created by | Notes |
+|------|---------|------------|-------|
+| `signing-service` (client role) | Identifies the service as the signing executor | Admin during bootstrap | The Forseti contract's `ValidateExecutor` checks for this role. Ensures only the service (not individual admins) can execute the signing request. |
+
+## Key rules
+
+1. `_tide_enabled` must be declared in `realm.json`. Not auto-created by `setUpTideRealm`.
+2. Signing roles are client roles on the service's OIDC client, not realm roles.
+3. Each signing role requires a committed PolicyApproval with `signed_policy_data` before ORKs authorize signing.
+4. Role assignment changes go through IGA change-sets. Roles appear in JWT/doken after next token refresh (up to 120s delay).
+5. `tide-realm-admin` is a client role on `realm-management`, not a realm role.
+6. Admins who review and approve PRs need both `tide-realm-admin` and the relevant `git-sign:<branch>` role.
+7. The service itself needs a service identity with the `signing-service` role for `ValidateExecutor`.
+
+## Forseti contract for git commit signing
+
+```csharp
+using Ork.Forseti.Sdk;
+
+public class GitCommitSigningPolicy : IAccessPolicy
+{
+    [PolicyParam] public string Role { get; set; }       // e.g. "git-sign:main"
+    [PolicyParam] public string Resource { get; set; }    // client ID
+    [PolicyParam] public int threshold { get; set; }      // e.g. 2 admins
+
+    public PolicyDecision ValidateData(DataContext ctx)
+    {
+        // Parse the git commit payload
+        // Validate:
+        //   - target branch matches the role suffix
+        //   - author identity is present
+        //   - commit message is non-empty
+        // Optional checks:
+        //   - reject commits modifying protected paths (e.g., .github/workflows/)
+        //   - require commit message format (conventional commits, ticket reference)
+        //   - enforce repo allow-list
+        //   - validate PR metadata (reviewers, labels, checks passed)
+        return PolicyDecision.Allow();
+    }
+
+    public PolicyDecision ValidateApprovers(ApproversContext ctx)
+    {
+        var approvers = DokenDto.WrapAll(ctx.Dokens);
+        return Decision.RequireAnyWithRole(approvers, Role, Resource, threshold);
+    }
+
+    public PolicyDecision ValidateExecutor(ExecutorContext ctx)
+    {
+        var executor = new DokenDto(ctx.Doken);
+        return Decision.RequireNotExpired(executor)
+            .And(Decision.RequireRole(executor, "signing-service", Resource));
+    }
+}
+```
+
+**Contract notes**:
+- `ValidateData` receives the commit bytes that will be signed. Parse them to extract branch, author, message, and file changes.
+- `ValidateApprovers` checks that enough admins with the `git-sign:<branch>` role approved the PR.
+- `ValidateExecutor` checks the service's identity, not an individual admin. The service is the entity that submits the signing request after collecting approvals.
+- Use `BasicCustomRequest` (model ID: `BasicCustom<GitSign>:BasicCustom<1>`). The commit content is known at request creation time and does not change.
+
+## Policy parameters
+
+| Parameter | Type | Required | Example | Purpose |
+|-----------|------|----------|---------|---------|
+| `Role` | string | Yes | `git-sign:main` | The client role required for approvers |
+| `Resource` | string | Yes | `git-pr-signing-service` | The client ID for role lookup |
+| `threshold` | number | Yes | `2` | Minimum number of admin approvals before signing |
+
+## Approval flow
+
+1. PR opened on GitHub
+2. Service receives webhook, creates check run (pending)
+3. Admins log in to service via TideCloak OIDC
+4. Each admin reviews code in service UI, clicks "Approve" (collects doken as approval)
+5. When `threshold` approvals collected, service creates `BasicCustomRequest` with commit bytes
+6. Service attaches admin dokens as approvers and its own doken as executor
+7. ORKs execute Forseti contract: validate commit, check approver roles, verify service identity
+8. If contract allows, ORKs produce Ed25519 signature
+9. Service wraps signature in SSH format, creates signed commit via GitHub API
+10. Service updates check run to success, merges PR