@tideorg/mcp 1.4.0

package/reference-apps/git-pr-signing-service/scenario.md

@@ -0,0 +1,169 @@
+# Git PR Signing Service
+
+## What this is
+
+A server-side service that threshold-signs git merge commits after admin approval. Developers push code and open pull requests as normal. The service receives GitHub webhooks, presents PRs for admin review in a web UI, and after Forseti-governed quorum approval, signs the merge commit using Tide ORK threshold cryptography. The signed commit appears on GitHub with a "Verified" badge.
+
+No single entity holds the signing key. The key exists only as threshold shares across independent ORKs.
+
+## When to use this scenario
+
+Use when the user describes:
+- a service that signs git commits using threshold cryptography
+- enterprise code signing with multi-admin approval
+- GitHub verified commits without developer-held keys
+- a PR approval workflow that produces signed merges
+- removing GPG/SSH key management from individual developers
+- organizational governance over code signing
+
+Do NOT use when:
+- the user needs local `git commit -S` signing at the developer's machine (no server-side service exists for this yet — see GAP-063, GAP-064)
+- the user needs to sign container images (use cosign or standard `policy-governed-signing`)
+- the user needs SSH challenge signing (use `policy-governed-signing` directly)
+- the user needs only authentication with no signing
+
+## Core Tide capabilities used
+
+1. **TideCloak OIDC authentication** — zero-knowledge login via threshold PRISM (admins only; developers do not interact with Tide)
+2. **DPoP token binding** — access tokens bound to admin's device/session
+3. **Doken** — delegation token authorizing ORK-mediated signing operations
+4. **Forseti contracts** — C# contracts validate commit content, approver roles, and executor identity before ORKs produce signature
+5. **Policy:1 auth flow** — policy-based authorization; ORKs check contract before producing signature
+6. **IGA (Identity Governance)** — role and policy changes require multi-admin approval via change-sets
+7. **BasicCustomRequest** — request pattern for submitting commit bytes to ORKs for signing
+
+## Architecture
+
+```
+Developer              GitHub                Signing Service                    Tide ORKs
+   |                      |                   (browser)     (server)                |
+   |-- git push / open PR |                      |             |                   |
+   |                      |-- webhook: PR ------>|             |                   |
+   |                      |                      |-- pending ->|                   |
+   |                      |<-- status check -----|             |                   |
+   |                      |                      |             |                   |
+   |                      |    Admins log in via TideCloak OIDC                    |
+   |                      |    (standard browser, SWE iframe, PRISM)               |
+   |                      |                      |             |                   |
+   |                      |    Admin 1 reviews code, approves (doken collected)    |
+   |                      |    Admin 2 reviews code, approves (doken collected)    |
+   |                      |                      |             |                   |
+   |                      |    Quorum met. Last approving admin triggers signing:  |
+   |                      |                      |             |                   |
+   |                      |                      |-- GET commit data -->|           |
+   |                      |                      |<-- commit bytes ----|           |
+   |                      |                      |                     |           |
+   |                      |                      |-- ORK signing (browser) ------->|
+   |                      |                      |   createTideRequest + execute   |
+   |                      |                      |   Forseti validates:            |
+   |                      |                      |     - commit (ValidateData)     |
+   |                      |                      |     - approvers (ValidateAppr)  |
+   |                      |                      |     - executor (ValidateExec)   |
+   |                      |                      |<-- Ed25519 64-byte sig ---------|
+   |                      |                      |                     |           |
+   |                      |                      |-- POST sig ------->|           |
+   |                      |                      |   (server wraps SSH + GitHub)   |
+   |                      |<-- signed commit, update ref -------------|           |
+   |                      |                      |-- set status: success           |
+   |                      |                      |                                 |
+   |                      |-- Verified badge shown                                 |
+```
+
+**Critical**: ORK signing happens in the admin's browser, not server-side. The JS SDK's `createTideRequest` + `executeSignRequest` require the authenticated TideCloak session (doken, PRISM state) which only exists in the browser context. The server receives the raw 64-byte signature and handles SSH wrapping + GitHub API calls. VERIFIED (LEARNINGS-ratidefy-batch-001 L-10).
+
+## GitHub integration components
+
+| Component | GitHub feature | Purpose |
+|-----------|---------------|---------|
+| Webhook receiver | `pull_request` event webhook | Notifies service of new/updated PRs |
+| Status check | Checks API (`POST /repos/{owner}/{repo}/check-runs`) | Blocks merge until service approves and signs |
+| Commit signing | Git Data API (`POST /repos/{owner}/{repo}/git/commits` with `signature`) | Creates signed merge commit |
+| Branch protection | Required status checks + required reviews | Enforces that all merges go through the service |
+| Bot identity | GitHub App or bot account with Ed25519 SSH signing key | Public key for "Verified" badge verification |
+
+## Ed25519 to SSH signature format
+
+Tide ORKs produce raw 64-byte Ed25519 signatures. GitHub requires SSH signature wire format for commit verification.
+
+The wrapping is a non-cryptographic transformation:
+1. Take raw 64-byte Ed25519 signature from ORKs
+2. Wrap in SSH signature format: `BEGIN SSH SIGNATURE` block
+3. Namespace: `git`
+4. Hash algorithm: `sha512`
+5. Signature blob: SSH-encoded Ed25519 signature
+
+The threshold Ed25519 public key is uploaded to the service's GitHub App (or bot account) as an SSH signing key. GitHub verifies the signature against that key.
+
+VERIFIED — GitHub docs explicitly list `ssh-ed25519` as a supported key type for commit verification.
+
+## GitHub Verified Badge Requirements
+
+For a signed commit to show the green "Verified" badge on GitHub, three things must align:
+
+1. **SSH signing key registered**: The threshold Ed25519 public key must be added to a GitHub account as a **Signing Key** (Settings → SSH and GPG Keys → type: Signing Key).
+2. **Committer email matches**: The commit's `committer.email` field must match the email of the GitHub account that has the signing key registered. A mismatch produces `unknown_signature_type` instead of "Verified".
+3. **SSH wire format correct**: The raw signature must be properly wrapped in `BEGIN SSH SIGNATURE` block with correct namespace and hash algorithm.
+
+**SSH key derivation from tidecloak.json**:
+The threshold Ed25519 public key is in the adapter JSON's `jwk.keys[0].x` field (base64url-encoded 32-byte key). Convert to SSH format: `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA<base64> <comment>`.
+
+**GitHub App limitation**: GitHub App bot accounts (e.g., `ratidefy[bot]`) cannot have SSH keys added via the UI. Use a dedicated machine user account for the committer identity.
+
+VERIFIED (LEARNINGS-ratidefy-batch-001 L-26).
+
+## What must exist before first use
+
+1. TideCloak running with a realm for the signing service
+2. Realm licensed (`setUpTideRealm`) and IGA enabled (`toggle-iga`)
+3. Admin user(s) created, Tide accounts linked, `tide-realm-admin` role assigned
+4. Initial change-sets approved and committed
+5. `sign-idp-settings` called after IDP config changes
+6. Adapter JSON exported with `jwk`, `vendorId`, `homeOrkUrl`, `client-origin-auth-*`
+7. At least one signing role created (e.g., `git-sign:main`) via admin UI
+8. Signing policy created, approved, and committed for each role
+9. GitHub App registered with webhook URL, permissions for checks + contents + pull_requests
+10. Threshold Ed25519 public key uploaded to GitHub App/bot as SSH signing key
+11. Branch protection rules configured: require signing service status check
+12. Service running with JWT + DPoP verification on protected endpoints
+
+## Key diagnostics
+
+| Symptom | Likely cause |
+|---------|-------------|
+| No webhook received | GitHub App not installed on repo, webhook URL wrong, or service not reachable |
+| Status check stays pending | Service received webhook but admin approval quorum not met |
+| Signing fails with "No doken available" | Admin not authenticated or doken expired |
+| Forseti contract rejects | ValidateData failed (check commit payload parsing), or executor lacks signing role |
+| Merge commit not "Verified" | Public key not uploaded to GitHub, SSH wire format wrong, or wrong key used |
+| 401 from GitHub API | GitHub App token expired or insufficient permissions |
+| Webhook signature invalid | Webhook secret mismatch between GitHub App config and service |
+
+## Intentionally configurable
+
+- **Signing role naming**: `git-sign:<branch>` is the default pattern. Apps may use `git-sign:<repo>`, `git-sign:*` (all branches), or other patterns.
+- **Approval quorum**: Number of admin approvals before signing. Configurable in Forseti contract `threshold` parameter.
+- **ValidateData logic**: What the contract validates about the commit. Apps may check: target branch, author identity, commit message format, modified file paths, PR metadata.
+- **Approval type**: Implicit (doken-only) or explicit (requires operator approval popup).
+- **Branch scope**: Which branches require signed merges. Configurable via GitHub branch protection rules.
+- **GitHub identity**: GitHub App (preferred for organizations) or bot account (simpler for personal repos).
+
+## Relationship to policy-governed-signing
+
+This scenario is a specialization of `policy-governed-signing` for the git/GitHub domain. It inherits all invariants, anti-patterns, and Forseti contract patterns from the parent scenario. The key differences:
+
+| Aspect | policy-governed-signing | git-pr-signing-service |
+|--------|------------------------|------------------------|
+| Trigger | User action in app | GitHub webhook (PR event) |
+| Data signed | App-specific (SSH challenge, document hash, etc.) | Git merge commit bytes |
+| Signature format | Raw Ed25519 | Ed25519 wrapped in SSH wire format |
+| Signature delivery | Returned to app/user | Pushed to GitHub via Git Data API |
+| Developer interaction with Tide | Direct (signs in app) | None (developers push code normally) |
+| External integration | None | GitHub webhooks, Checks API, Git Data API |
+| UI | App-specific signing UI | PR review + approval dashboard |
+
+## What this scenario does NOT cover
+
+- **Local git signing**: Developer-side `git commit -S` with Tide. Blocked by GAP-063 (no Go SDK) and GAP-064 (no CLI auth). The browser-bridge pattern (LEARNINGS-cosign-batch-001 L-08) is a potential future path.
+- **Container image signing**: Use cosign or standard `policy-governed-signing`.
+- **CI/CD pipeline signing**: The service IS the signer. No separate CI integration needed.
+- **Tag signing**: Architecturally similar to commit signing. Same service can sign tags via GitHub Git Data API (`POST /repos/{owner}/{repo}/git/tags`). Not yet documented as a separate flow.

package/reference-apps/iga-admin-governance/anti-patterns.md

@@ -0,0 +1,133 @@
+# IGA Admin Governance — Anti-Patterns
+
+Scenario-specific mistakes for IGA admin governance panels. General Tide anti-patterns (I-01 through I-16, AP-01 through AP-42) still apply.
+
+---
+
+## AP-G01: Skipping IGA enablement
+
+**Mistake**: Building the governance panel without enabling IGA on the realm. No change requests are created for admin mutations.
+
+**Why it fails**: Without `toggle-iga`, admin actions execute immediately. The governance panel has nothing to review.
+
+**Fix**: Enable IGA (`toggle-iga`) during bootstrap before building the panel.
+
+---
+
+## AP-G02: Using JSON for add-review or add-rejection
+
+**Mistake**: Sending `application/json` to `/tideAdminResources/add-review` or `/tideAdminResources/add-rejection`.
+
+**Why it fails**: These endpoints require `multipart/form-data`. JSON submissions return 415 or are silently ignored.
+
+**Fix**: Use `FormData` for add-review and add-rejection. All other mutation endpoints (sign/batch, commit/batch, cancel/batch) use JSON.
+
+---
+
+## AP-G03: Treating sign as commit
+
+**Mistake**: Calling only `sign/batch` and assuming the change is applied.
+
+**Why it fails**: Signing records an approval. The change does not take effect until `commit/batch` is called after the quorum threshold is met.
+
+**Fix**: After sign succeeds and approval count >= threshold, call `commit/batch`.
+
+---
+
+## AP-G04: Caching change-set counts across mutations
+
+**Mistake**: Fetching counts once and not refreshing after sign, commit, or cancel.
+
+**Why it fails**: Counts change after every mutation. Stale counts cause the UI to show incorrect badge numbers and confuse admins.
+
+**Fix**: Refresh counts after every mutation (sign, commit, cancel, add-review, add-rejection).
+
+---
+
+## AP-G05: Ignoring enclave challenge in MultiAdmin mode
+
+**Mistake**: Not handling the enclave approval popup when multiple admins exist. The sign response indicates `requiresApprovalPopup: true` but the app treats it as a normal success.
+
+**Why it fails**: In MultiAdmin mode, `sign/batch` returns an enclave challenge (base64 `changeSetDraftRequests`). The admin must sign this in the enclave popup and submit via `add-review`. Without this, the approval is not recorded.
+
+**Fix**: Check the sign response for `requiresApprovalPopup`. If true, present the enclave challenge to the admin and submit the result via `add-review` (FormData).
+
+---
+
+## AP-G06: Relying on client-side role checks for governance access
+
+**Mistake**: Using `hasClientRole('tide-realm-admin', 'realm-management')` on the client side as the only access control for the governance panel.
+
+**Why it fails**: Client-side role checks are UI gating only. An attacker can call governance API routes directly. The admin endpoints themselves are protected by TideCloak, but the app's proxy/API routes may not be.
+
+**Fix**: Server-side JWT verification on every governance API route. Check `resource_access['realm-management'].roles` includes `tide-realm-admin` in the verified JWT payload.
+
+---
+
+## AP-G07: Calling TideCloak admin API directly from the browser
+
+**Mistake**: Making browser-side `fetch` calls directly to TideCloak admin endpoints (e.g., `http://localhost:8080/admin/realms/...`).
+
+**Why it fails**: CORS blocks cross-origin requests from the app domain to TideCloak. Even if CORS is configured, exposing the admin API directly to the browser is an unnecessary attack surface.
+
+**Fix**: Create same-origin API routes in the app that proxy requests to TideCloak admin endpoints server-side. The proxy forwards the admin's token and returns the TideCloak response.
+
+---
+
+## AP-G08: Using master admin credentials in the governance app
+
+**Mistake**: Calling TideCloak admin API with `grant_type=password&username=admin&password=password` from the governance app's API routes.
+
+**Why it fails**: Master admin credentials are bootstrap-only. Using them in the app bypasses IGA (master realm is exempt from IGA). Actions performed with master credentials are not governed.
+
+**Fix**: Forward the logged-in admin user's token to TideCloak admin API. The admin user must have `tide-realm-admin` on the governed realm.
+
+---
+
+## AP-G09: Treating `tide-realm-admin` as a realm role
+
+**Mistake**: Checking `hasRealmRole('tide-realm-admin')` or looking in `realm_access.roles` for it.
+
+**Why it fails**: `tide-realm-admin` is a **client role** on the `realm-management` client. It does not appear in `realm_access`.
+
+**Fix**: Check `resource_access['realm-management'].roles` in the JWT payload. Client-side: use `hasClientRole('tide-realm-admin', 'realm-management')`.
+
+---
+
+## AP-G10: Not handling licensing and ragnarok request paths
+
+**Mistake**: Assuming all change-set requests are under `/tide-admin/change-set/...`.
+
+**Why it fails**: Licensing requests use `/tideAdminResources/change-set/licensing/requests`. Ragnarok requests use `/ragnarok/change-set/offboarding/requests`. These are under different path prefixes.
+
+**Fix**: Fetch licensing and ragnarok requests from their specific endpoints if the governance panel supports those change-set types.
+
+---
+
+## AP-G11: Building policy management without IGA change-set support
+
+**Mistake**: Adding realm policy or role-policy management UI without also building the change-set approval workflow for policy changes.
+
+**Why it fails**: Policy mutations (create, delete) also generate IGA change requests that must be approved and committed. Without the change-set workflow, policies stay in pending state.
+
+**Fix**: Implement the full change-set lifecycle (sign → commit) for policy change requests. The `POLICY` change-set type covers realm policy mutations.
+
+---
+
+## AP-G12: Omitting DPoP on admin API calls
+
+**Mistake**: Using regular `fetch` with `Bearer` token for governance API calls when DPoP is enabled on the realm client.
+
+**Why it fails**: DPoP-bound tokens require the DPoP proof header. Without it, TideCloak rejects the request with 400 "DPoP proof is missing".
+
+**Fix**: Use `secureFetch` (or the DPoP-aware fetch wrapper) for all governance API calls. Ensure the admin user's token is DPoP-bound.
+
+---
+
+## AP-G13: Single admin assumes governance is complete
+
+**Mistake**: Deploying with only one admin user and assuming the governance panel is fully operational.
+
+**Why it fails**: With one admin, all changes are FirstAdmin-signed (immediate, no popup). This provides audit logging but not true multi-admin governance. If the goal is quorum enforcement, a single admin defeats the purpose.
+
+**Fix**: For real governance, ensure at least two linked admin users. Document that FirstAdmin mode is bootstrap-only or single-admin-acceptable depending on the deployment's security requirements.

package/reference-apps/iga-admin-governance/bootstrap-sequence.md

@@ -0,0 +1,153 @@
+# IGA Admin Governance — 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:
+   ```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.
+
+   Realm template must include: `_tide_enabled` in default composite, `tidebrowser` flow, `link-tide-account-action`, Tide protocol mappers (`tideUserKey`, `vuid`), `UPDATE_PASSWORD` disabled.
+
+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"
+   ```
+   **Content-Type**: `application/x-www-form-urlencoded`, NOT JSON.
+
+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/commit initial client change request:
+   ```bash
+   # Get pending client changes
+   CLIENTS=$(curl -s "http://localhost:8080/admin/realms/$REALM/tide-admin/change-set/clients/requests" \
+     -H "Authorization: Bearer $TOKEN")
+   # Extract changeSets array, then sign and commit
+   ```
+
+---
+
+## Phase 3: First Admin User
+
+7. Create admin user (include `firstName` and `lastName` to avoid `VERIFY_PROFILE` block):
+   ```bash
+   curl -s -X POST "http://localhost:8080/admin/realms/$REALM/users" \
+     -H "Authorization: Bearer $TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{"username":"admin1","enabled":true,"firstName":"Admin","lastName":"One","email":"admin1@example.com"}'
+   ```
+
+8. Approve/commit user creation change request.
+
+9. Assign `tide-realm-admin` client role on `realm-management`:
+   - Look up user ID
+   - Look up `realm-management` client UUID
+   - Look up `tide-realm-admin` role within that client
+   - Assign the role to the user
+
+10. Approve/commit role assignment change request.
+
+11. Generate invite link:
+    ```bash
+    curl -s -X POST "http://localhost:8080/admin/realms/$REALM/tideAdminResources/get-required-action-link?userId=$USER_ID&lifespan=43200" \
+      -H "Authorization: Bearer $TOKEN" \
+      -H "Content-Type: application/json" \
+      -d '["link-tide-account-action"]'
+    ```
+
+12. First admin opens invite link and completes Tide account linking.
+
+---
+
+## Phase 4: IDP Settings
+
+13. If the governance panel is hosted on a separate domain from TideCloak:
+    - Update `CustomAdminUIDomain` on the Tide IDP instance
+    - Call `sign-idp-settings`:
+      ```bash
+      curl -s -X POST "http://localhost:8080/admin/realms/$REALM/vendorResources/sign-idp-settings" \
+        -H "Authorization: Bearer $TOKEN"
+      ```
+    `sign-idp-settings` is ALWAYS required after any Tide IDP config change.
+
+---
+
+## Phase 5: Second Admin (for quorum)
+
+14. Create second admin user (same as steps 7-12 but for admin2).
+
+15. Approve/commit second user creation and role assignment.
+    - If still in FirstAdmin mode (one linked admin), signing is immediate.
+    - Once second admin is linked, future approvals require MultiAdmin enclave flow.
+
+---
+
+## Phase 6: Adapter Export
+
+16. 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" > data/tidecloak.json
+    ```
+    Verify `jwk` field is present (requires IGA to be enabled).
+
+---
+
+## Phase 7: App Readiness
+
+17. Install SDK, wire provider with DPoP, create redirect handler.
+18. Implement server-side JWT verification with `tide-realm-admin` role check on governance API routes.
+19. Build governance UI: change-set list, approve, commit, cancel.
+20. Optional: add policy management tabs (realm policy, Forseti contracts, role policies).
+
+---
+
+## Pre-User Checklist
+
+Before any admin uses the governance panel:
+
+- [ ] TideCloak running and reachable
+- [ ] Realm created with `_tide_enabled`, `tidebrowser`, protocol mappers
+- [ ] Realm licensed (`setUpTideRealm`)
+- [ ] IGA enabled (`toggle-iga`)
+- [ ] At least one admin user with `tide-realm-admin` linked
+- [ ] All initial change requests (client, user, role) approved and committed
+- [ ] IDP settings signed (`sign-idp-settings`)
+- [ ] Adapter JSON exported with `jwk` field
+- [ ] App deployed with DPoP-enabled provider
+- [ ] Server-side JWT verification on governance API routes
+- [ ] At least two linked admins for quorum governance (optional for FirstAdmin-only mode)
+- [ ] Change-set list/approve/commit UI functional

package/reference-apps/iga-admin-governance/manifest.yaml

@@ -0,0 +1,87 @@
+# IGA Admin Governance Panel — Scenario Manifest
+
+id: iga-admin-governance
+title: IGA Admin Governance Panel
+category: admin-governance
+description: Admin dashboard for reviewing, approving, and committing IGA change requests with multi-admin quorum enforcement
+
+frameworks:
+  - nextjs
+  - react-vite
+  - vanilla
+
+core_patterns:
+  - iga
+  - change-set
+  - quorum
+  - multi-admin
+  - enclave-signing
+  - dpop
+  - oidc
+  - admin-panel
+  - governance
+  - approval-workflow
+  - policy-management
+  - forseti
+  - role-policy
+
+match_keywords:
+  - admin panel
+  - admin dashboard
+  - admin governance
+  - iga panel
+  - iga dashboard
+  - iga admin
+  - change request
+  - change requests
+  - approval workflow
+  - approval dashboard
+  - governance panel
+  - governance dashboard
+  - review and approve
+  - multi-admin
+  - quorum approval
+  - admin approval
+  - change-set management
+  - change set management
+  - policy management panel
+  - manage change requests
+  - approve changes
+  - admin console
+
+bootstrap_required: true
+requires_admin_preapproval: true
+requires_iga: true
+requires_e2ee: false
+governance_mode: multi-admin-quorum
+
+default_roles:
+  - _tide_enabled
+  - tide-realm-admin
+
+admin_role: tide-realm-admin
+admin_role_type: client
+admin_role_client: realm-management
+min_admins_for_quorum: 2
+
+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
+  - setup-iga-admin-panel
+  - add-rbac-nextjs
+
+default_skills:
+  - tide-setup
+  - tide-integration
+  - tide-route-and-api-protection
+  - tide-rbac-and-e2ee
+
+discriminating_question: Does the app need a custom admin UI for reviewing and approving IGA change requests (user/role/group/client mutations)? If the built-in TideCloak Admin Console is sufficient, this scenario is not needed.
+valid_only_when: App requires a custom governance dashboard for IGA change request lifecycle management. Not needed if built-in TideCloak Admin Console handles all governance.
+
+notes: No encryption layer. This is a governance/admin tool. At least two linked admin users required for quorum. Content-type asymmetry between endpoints (JSON for sign/commit, FormData for add-review/add-rejection). Enclave popup flow required for MultiAdmin signing mode.

package/reference-apps/iga-admin-governance/role-policy-matrix.md

@@ -0,0 +1,67 @@
+# IGA Admin Governance — 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 for all users | Realm template | Auto (in default composite) | Yes | Default | Must be in `default-roles-{realm}` composite |
+| `tide-realm-admin` | Client (`realm-management`) | Full admin access to TideCloak governance | Built-in | IGA quorum (after first admin) | Yes | Default for admins | This is a **client role**, not a realm role. Do not use `hasRealmRole('tide-realm-admin')`. |
+
+---
+
+## Application Roles
+
+This scenario does not define app-specific roles beyond the admin role. The governance panel serves admins who already have `tide-realm-admin`.
+
+Apps that embed the governance panel alongside user-facing features may add their own application roles (e.g., `admin`, `manager`). These are separate from `tide-realm-admin` and do not affect IGA governance behavior.
+
+---
+
+## Key rules
+
+1. **`tide-realm-admin` is a client role on `realm-management`**. Check it with `hasClientRole('tide-realm-admin', 'realm-management')` on the client side, or check `resource_access['realm-management'].roles` in the server-side JWT payload.
+
+2. **Quorum requires at least two linked admin users.** A single admin operates in FirstAdmin mode (VRK-signed, no popup). Two or more admins operate in MultiAdmin mode (enclave challenge popup).
+
+3. **All admin mutations in an IGA-enabled realm create draft change requests.** These must be signed and committed before they take effect. The governance panel is the tool for this.
+
+4. **Change-set types are fixed by TideCloak.** The app does not define new types. Known types: `USER`, `USER_ROLE`, `COMPOSITE_ROLE`, `CLIENT`, `GROUP_ROLE`, `GROUP_MEMBERSHIP`, `GROUP_MOVE`, `REALM_LICENSE`, `POLICY`, `DEFAULT_ROLES`, `REALM_SETTINGS`, `RAGNAROK`.
+
+5. **`DEFAULT_ROLES` and role creation are ACTIVE (auto-approved).** They appear in the change-set list for audit but do not require sign/commit. All other types require quorum approval.
+
+6. **Quorum threshold**: `max(1, floor(TotalAdmins * 0.7))`. Not configurable by the app.
+
+---
+
+## Policy Layer (optional features)
+
+The governance panel may optionally include policy management. These are NOT required for the core change-request workflow.
+
+| Feature | Endpoint pattern | Purpose | Notes |
+|---------|-----------------|---------|-------|
+| Realm policy | `GET/POST/DELETE /tide-admin/realm-policy/*` | View and manage the realm-level Forseti policy | Lifecycle: none → pending → committed. Requires sign/commit flow. |
+| Policy templates | `GET/POST/PUT/DELETE /tide-admin/policy-templates/*` | CRUD for reusable policy templates | Templates are building blocks. Not policies themselves. |
+| SSH/role policies | `GET/PUT/DELETE /tide-admin/ssh-policies` | Attach Forseti contracts to specific roles | Despite the name, not SSH-specific. Sets approval type, execution type, threshold. |
+| Forseti contracts | `GET/PUT /tide-admin/forseti-contracts` | List and register Forseti contracts | Contracts are stored server-side. SDK signing flow deploys them to ORKs. |
+| Role policies view | `GET /tide-admin/role-policies` | Combined view of all role-policy attachments | Read-only summary. Useful for auditing which roles have policies attached. |
+
+---
+
+## Change-Set Endpoints (core governance)
+
+| Operation | Endpoint | Method | Content-Type | Notes |
+|-----------|---------|--------|-------------|-------|
+| List counts | `/tide-admin/change-set/counts` | GET | — | Returns per-type counts |
+| List all requests | `/tide-admin/change-set/all/requests` | GET | — | Returns all pending changes grouped by type |
+| List by type | `/tide-admin/change-set/{type}/requests` | GET | — | `{type}` = users, roles, clients, groups |
+| Sign (approve) | `/tide-admin/change-set/sign/batch` | POST | `application/json` | Body: `{ changeSets: [...] }` |
+| Commit | `/tide-admin/change-set/commit/batch` | POST | `application/json` | Body: `{ changeSets: [...] }` |
+| Cancel | `/tide-admin/change-set/cancel/batch` | POST | `application/json` | Body: `{ changeSets: [...] }` |
+| Add review (enclave) | `/tideAdminResources/add-review` | POST | **`multipart/form-data`** | Used after enclave challenge in MultiAdmin mode |
+| Add rejection | `/tideAdminResources/add-rejection` | POST | **`multipart/form-data`** | Content-type asymmetry: NOT JSON |
+| Activity | `/tide-admin/change-set/{id}/activity` | GET | — | Returns approvals, rejections, comments |
+| Add comment | `/tide-admin/change-set/{id}/comments` | POST | `application/json` | |
+| Licensing requests | `/tideAdminResources/change-set/licensing/requests` | GET | — | Different path prefix from other types |
+| Ragnarok requests | `/ragnarok/change-set/offboarding/requests` | GET | — | Different path prefix |