@tideorg/mcp 1.4.0

package/playbooks/setup-iga-admin-panel.md

@@ -0,0 +1,344 @@
+# Set Up IGA Admin Panel
+
+Build an admin UI for managing IGA change requests with quorum governance.
+
+---
+
+## When to Use
+
+- Building an admin dashboard that lists, approves, rejects, and commits IGA change requests
+- Need to integrate the TideCloak change-request lifecycle into a custom UI
+- Managing role assignments, group changes, or policy updates through quorum-governed workflows
+
+**Do not use** if you only need end-user authentication. See [add-auth-nextjs-fresh.md](add-auth-nextjs-fresh.md) instead.
+
+---
+
+## Prerequisites
+
+- TideCloak instance running and accessible
+- TideCloak realm created with IGA enabled
+- Admin user with sufficient privileges (realm-admin or equivalent)
+- Admin bearer token obtainable (via admin-cli client or service account)
+- Familiarity with the Tide enclave signing flow (required for multi-admin mode)
+
+---
+
+## API Base
+
+All endpoints below are relative to:
+
+```
+{tidecloak-url}/admin/realms/{realm}
+```
+
+Example: `http://localhost:8080/admin/realms/myrealm`
+
+---
+
+## Change Request Lifecycle
+
+```
+1. Admin creates change (role assignment, group change, etc.)
+   -> Draft created automatically (DRAFT/PENDING)
+2. Admin reviews: GET /tide-admin/change-set/all/requests
+3. Admin approves: POST /tide-admin/change-set/sign/batch
+   -> If Tide multi-admin: returns signing challenge for enclave
+   -> Submit signed result: POST /tideAdminResources/add-review
+4. Once enough approvals: POST /tide-admin/change-set/commit/batch
+5. Or cancel: POST /tide-admin/change-set/cancel/batch
+```
+
+---
+
+## Endpoints
+
+### Counts (Lightweight)
+
+```
+GET  /tide-admin/change-set/counts
+```
+
+Use this for dashboard badges and summary views. Avoids fetching full request payloads.
+
+### List Requests
+
+```
+GET  /tide-admin/change-set/all/requests         # All change requests (single call)
+GET  /tide-admin/change-set/users/requests        # User changes only
+GET  /tide-admin/change-set/roles/requests        # Role changes only
+GET  /tide-admin/change-set/clients/requests      # Client changes only
+GET  /tide-admin/change-set/groups/requests       # Group changes only
+```
+
+### Sign / Approve
+
+```
+POST /tide-admin/change-set/sign/batch            # Approve (sign) changes
+```
+
+### Commit / Cancel
+
+```
+POST /tide-admin/change-set/commit/batch          # Commit approved changes
+POST /tide-admin/change-set/cancel/batch          # Cancel pending changes
+```
+
+### Enclave Review and Rejection
+
+```
+POST /tideAdminResources/add-review               # Submit Tide enclave signed review (multipart/form-data)
+POST /tideAdminResources/add-rejection            # Reject a change (multipart/form-data)
+```
+
+**Content-type warning**: Both `add-review` and `add-rejection` use `multipart/form-data`, NOT JSON. All other mutation endpoints (`sign/batch`, `commit/batch`, `cancel/batch`) use `application/json`. If you send JSON to `add-rejection`, the server silently ignores the payload.
+
+```typescript
+// Rejection example — must use FormData, not JSON
+const formData = new FormData();
+formData.append("changeSetId", draftRecordId);
+formData.append("actionType", actionType);
+formData.append("changeSetType", changeSetType);
+
+await fetch(`${TC_URL}/admin/realms/${realm}/tideAdminResources/add-rejection`, {
+  method: 'POST',
+  headers: { 'Authorization': `Bearer ${adminToken}` },
+  body: formData  // NOT JSON.stringify
+});
+```
+
+### Activity and Comments
+
+```
+GET  /tide-admin/change-set/{id}/activity         # Activity log + comments
+POST /tide-admin/change-set/{id}/comments         # Add comment to change request
+```
+
+---
+
+## Approve (Sign) Request -- Code Example
+
+```typescript
+const response = await fetch(`${TC_URL}/admin/realms/${realm}/tide-admin/change-set/sign/batch`, {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${adminToken}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    changeSets: [{
+      changeSetId: "draft-record-id",
+      changeSetType: "USER_ROLE",
+      actionType: "CREATE",
+      policyRoleId: "optional-role-uuid",  // omit to use tide-realm-admin policy
+      dynamicData: ["optional-base64"]     // custom Forseti contract input
+    }]
+  })
+});
+
+// If Tide multi-admin mode:
+// response[0].requiresApprovalPopup === true
+// -> decode changeSetDraftRequests (base64)
+// -> present to Tide enclave for admin signing
+// -> submit via POST /tideAdminResources/add-review
+```
+
+---
+
+## TypeScript Client (KcAdminClient) Usage
+
+```typescript
+import KcAdminClient from "@keycloak/keycloak-admin-client";
+
+const client = new KcAdminClient({ baseUrl: "http://localhost:8080" });
+await client.auth({
+  username: "admin",
+  password: "admin",
+  grantType: "password",
+  clientId: "admin-cli"
+});
+
+// Counts
+const counts = await client.tideUsersExt.getChangeSetCounts();
+
+// All requests
+const all = await client.tideUsersExt.getAllChangeSetRequests();
+
+// Approve
+await client.tideUsersExt.approveDraftChangeSet({
+  changeSets: [{ changeSetId: "id", changeSetType: "USER_ROLE", actionType: "CREATE" }]
+});
+
+// Commit
+await client.tideUsersExt.commitDraftChangeSet({
+  changeSets: [{ changeSetId: "id", changeSetType: "USER_ROLE", actionType: "CREATE" }]
+});
+
+// Activity and comments
+const activity = await client.tideUsersExt.getChangeSetActivity({ id: "draft-id" });
+await client.tideUsersExt.addChangeSetComment({ id: "draft-id", comment: "LGTM" });
+```
+
+---
+
+## Policy Management Endpoints
+
+```
+PUT  /tide-admin/forseti-contracts               # Create/update Forseti contract
+GET  /tide-admin/forseti-contracts               # List contracts
+POST /tide-admin/policy-templates                # Create policy template
+GET  /tide-admin/policy-templates                # List templates
+PUT  /tide-admin/ssh-policies                    # Attach policy to role
+GET  /tide-admin/ssh-policies                    # List role policies
+POST /tide-iga-provider/role-policy/{roleId}/init-cert  # Store signed policy on role (JSON: initCert required, initCertSig optional; no doken field)
+GET  /tide-admin/role-policies                   # Roles with policy status
+```
+
+---
+
+## ChangeSetType Values
+
+**VERIFIED** (vendor confirmation, GAP-041 resolved). Full enum (14 values):
+
+| Value | Description | Draft Status |
+|-------|-------------|-------------|
+| `DEFAULT_ROLES` | Default role assignment | ACTIVE (auto) |
+| `USER` | User creation | DRAFT |
+| `USER_ROLE` | User-to-role assignment | DRAFT |
+| `USER_GROUP_MEMBERSHIP` | User-to-group membership | DRAFT |
+| `ROLE` | Role definition change | ACTIVE (auto, creation) / DRAFT (deletion if users assigned) |
+| `COMPOSITE_ROLE` | Composite role change | DRAFT |
+| `CLIENT` | Client configuration change | DRAFT (when users exist) |
+| `CLIENT_DEFAULT_USER_CONTEXT` | Client scope mappings | DRAFT |
+| `CLIENT_FULLSCOPE` | Client full-scope toggle | DRAFT |
+| `GROUP` | Group definition change | — |
+| `GROUP_ROLE` | Group-to-role assignment | DRAFT |
+| `GROUP_MOVE` | Group hierarchy change | DRAFT |
+| `REALM_LICENSING` | Realm license change | DRAFT |
+| `POLICY` | Policy change (derived from USER_ROLE) | DRAFT |
+
+**ACTIVE vs DRAFT**: Role creation and default-role assignment get ACTIVE status (recorded for audit but non-blocking — no sign/commit needed). All other actions get DRAFT status requiring quorum sign/commit. Master realm and IGA-disabled realms are always exempt.
+
+## Status Values
+
+| Value | Meaning |
+|-------|---------|
+| `DRAFT` | Just created, not yet submitted for review |
+| `PENDING` | Awaiting approvals |
+| `APPROVED` | Enough approvals received, ready to commit |
+| `DENIED` | Rejected by reviewer |
+| `ACTIVE` | Committed and applied |
+
+---
+
+## Admin Panel Requirements
+
+A working IGA admin panel must include:
+
+1. **Pending list** -- Display all change requests in `DRAFT` or `PENDING` status. Use `GET /tide-admin/change-set/all/requests` and filter by status.
+
+2. **Approve button** -- Triggers `POST /tide-admin/change-set/sign/batch` with selected change set IDs.
+
+3. **Enclave popup** -- When `requiresApprovalPopup === true` in the sign response, decode `changeSetDraftRequests` (base64) and present the Tide enclave iframe for the admin to complete threshold signing. Submit the signed result via `POST /tideAdminResources/add-review`.
+
+4. **Batch support** -- The sign, commit, and cancel endpoints accept arrays. The UI should support selecting multiple change requests and acting on them in a single call.
+
+5. **Role check** -- Only users with admin roles should see the panel. Verify the admin token includes the required realm-admin or delegated role before rendering the UI. This is UI gating only; the server enforces authorization on every API call.
+
+---
+
+## Verification Checklist
+
+### Lifecycle
+
+- [ ] Creating a role assignment produces a DRAFT change request visible via `GET .../all/requests`
+- [ ] Signing a change request transitions status from DRAFT/PENDING toward APPROVED
+- [ ] In multi-admin mode, signing returns `requiresApprovalPopup === true` and enclave flow completes
+- [ ] Committing an APPROVED change request applies the change and sets status to ACTIVE
+- [ ] Cancelling a PENDING change request removes it from the pending list
+
+### Endpoints
+
+- [ ] `GET .../counts` returns correct totals matching the full request list
+- [ ] `GET .../all/requests` returns all change types (user, role, client, group)
+- [ ] `POST .../sign/batch` accepts an array and processes all items
+- [ ] `POST .../commit/batch` and `POST .../cancel/batch` work with arrays
+- [ ] `POST /tideAdminResources/add-review` accepts the enclave-signed payload
+- [ ] `POST /tideAdminResources/add-rejection` rejects and sets status to DENIED
+- [ ] `GET .../{id}/activity` returns audit trail with timestamps
+- [ ] `POST .../{id}/comments` persists and appears in activity
+
+### Authorization
+
+- [ ] Unauthenticated requests return 401
+- [ ] Non-admin tokens return 403
+- [ ] Admin tokens with correct roles return 200
+
+---
+
+## Common Failures
+
+### Sign Response Ignored in Multi-Admin Mode
+
+**Symptom**: Approve button appears to succeed but change request stays in PENDING.
+
+**Cause**: The `requiresApprovalPopup` flag was not checked. In multi-admin mode, signing returns a challenge that must be completed through the Tide enclave.
+
+**Fix**: After calling `sign/batch`, check `response[0].requiresApprovalPopup`. If `true`, decode `changeSetDraftRequests`, present the enclave iframe, and submit the signed result via `POST /tideAdminResources/add-review`.
+
+---
+
+### Committing Before Enough Approvals
+
+**Symptom**: `POST .../commit/batch` returns an error or silently fails.
+
+**Cause**: The change request has not reached APPROVED status. Quorum threshold not met.
+
+**Fix**: Check the status before committing. Only commit change requests with status `APPROVED`. If still `PENDING`, more admin approvals are needed.
+
+---
+
+### Wrong ChangeSetType in Payload
+
+**Symptom**: 400 Bad Request or unexpected behavior when signing/committing.
+
+**Cause**: The `changeSetType` in the request body does not match the actual type of the draft record.
+
+**Fix**: Read the `changeSetType` from the `GET .../all/requests` response and pass it back exactly. Do not hardcode a type.
+
+---
+
+### Missing Authorization Header
+
+**Symptom**: 401 on all admin API calls.
+
+**Cause**: Admin token not included or expired.
+
+**Fix**: Obtain a fresh admin token before each batch of calls. If using `KcAdminClient`, call `client.auth(...)` and handle token refresh.
+
+---
+
+### Rejection Silently Fails
+
+**Symptom**: Clicking "Reject" appears to succeed, but the change request stays in PENDING. No error returned.
+
+**Cause**: The rejection endpoint (`POST /tideAdminResources/add-rejection`) expects `multipart/form-data`. If you send `Content-Type: application/json`, the server accepts the request but ignores the payload fields.
+
+**Fix**: Use `FormData`, not `JSON.stringify`. Do not set `Content-Type` manually — the browser sets the correct multipart boundary automatically. See the code example in the Endpoints section above.
+
+---
+
+### Counts Out of Sync with List
+
+**Symptom**: Dashboard badge shows a different number than the actual list.
+
+**Cause**: `GET .../counts` and `GET .../all/requests` called at different times; a change was created or committed between calls.
+
+**Fix**: Refresh counts after any mutation (sign, commit, cancel). Do not cache counts across operations.
+
+---
+
+## References
+
+- Source: `sources/docs/CHANGE_REQUEST_API.md` (normative), operational exemplars (keylessh, forseti-crypto-quickstart, tidecloak-test-cases)
+- Content-type asymmetry confirmed by: CHANGE_REQUEST_API.md, forseti-crypto-quickstart `tidecloakApi.ts` (uses FormData for `add-review`)

package/playbooks/setup-server-delegation.md

@@ -0,0 +1,142 @@
+# Setup Server-Side Delegation
+
+For apps where the backend needs to call TideCloak admin APIs on behalf of authenticated users.
+
+---
+
+## When to Use
+
+- Your server manages users, roles, or policies via TideCloak admin API
+- You need server-side role management or access approvals
+- You want to avoid using master admin credentials from your server
+
+---
+
+## Prerequisites
+
+- TideCloak bootstrapped and running
+- `tidecloak.json` exported with `jwk`, `vendorId`, `homeOrkUrl`
+- App has working Tide login (provider wired, DPoP enabled)
+- Node.js 18+ on the server (Ed25519 support)
+
+---
+
+## Steps
+
+### 1. Install server SDK
+
+```bash
+npm install @tidecloak/server
+```
+
+### 2. Create delegation instance
+
+```ts
+// server/lib/delegation.ts
+import { TideDelegation } from '@tidecloak/server';
+
+let _delegation: TideDelegation | null = null;
+
+export function getDelegation(): TideDelegation {
+  if (!_delegation) {
+    _delegation = new TideDelegation({
+      tidecloakUrl: process.env.TIDECLOAK_URL || config['auth-server-url'],
+      realm: process.env.TIDECLOAK_REALM || config.realm,
+      clientId: process.env.TIDECLOAK_CLIENT_ID || config.resource,
+    });
+  }
+  return _delegation;
+}
+```
+
+Use a lazy singleton. Do not create a new instance per request.
+
+### 3. Wire delegation exchange endpoint
+
+```ts
+app.post('/api/delegation', authenticate, getDelegation().handleDelegation());
+```
+
+This endpoint receives signed delegation artifacts from the browser and exchanges them with TideCloak for a delegation token.
+
+### 4. Add delegation middleware to admin routes
+
+```ts
+app.get('/api/admin/users',
+  authenticate,
+  requireAdmin,
+  getDelegation().requireDelegation(),
+  async (req, res) => {
+    const adminUrl = `${tidecloakUrl}/admin/realms/${realm}`;
+    const users = await req.delegation.fetch(`${adminUrl}/users`);
+    res.json(users);
+  }
+);
+```
+
+The middleware:
+- Checks if a cached delegation token exists for this user session
+- If yes: attaches `req.delegation` with `token` and `fetch()` helper
+- If no: responds 419 with a delegation challenge
+
+### 5. Wrap browser fetch with createTideFetch
+
+```ts
+import { createTideFetch } from '@tidecloak/js';
+
+// Wrap the app's fetch function
+const appFetch = createTideFetch(window.fetch);
+
+// Use appFetch for all server calls that may need delegation
+const users = await appFetch('/api/admin/users');
+```
+
+`createTideFetch` intercepts 419 responses, handles the delegation signing flow with the browser's DPoP key, and retries the original request.
+
+### 6. Optional: scope delegation roles
+
+```ts
+// Only include specific roles in the delegation token
+getDelegation().requireDelegation({
+  roles: {
+    realm: ['admin'],
+    clients: { 'my-app': ['manage-users'] }
+  }
+})
+```
+
+If `roles` is specified, only listed roles appear in the delegation token. Unlisted realms/clients are stripped. Cannot add roles the user does not have.
+
+---
+
+## Verification
+
+- [ ] `@tidecloak/server` in server package.json
+- [ ] `/api/delegation` POST route wired with `handleDelegation()`
+- [ ] Admin routes use `requireDelegation()` middleware
+- [ ] Browser uses `createTideFetch` wrapper
+- [ ] Admin API calls succeed: user list, role management, etc.
+- [ ] 419 responses are handled transparently (no user-visible interruption)
+- [ ] Delegation token is cached (no 419 on every request)
+
+---
+
+## Troubleshooting
+
+**Repeated 419 responses**
+Check that `/api/delegation` is wired correctly and the `authenticate` middleware sets `req.accessToken`.
+
+**"No pending delegation challenge"**
+Server restarted between 419 and delegation POST. Browser retries automatically.
+
+**"Delegation exchange failed"**
+Check TideCloak has `tide-chain-of-trust` client authenticator enabled and `DelegationToken:1` in VRK model whitelist. A VRK rotation is needed after adding the model ID.
+
+**"DPoP is not initialized"**
+`signDelegationRequest` needs the DPoP provider. Ensure `useDPoP` is in the TideCloakProvider config object.
+
+**Delegation token has wrong roles**
+If using scoped delegation, everything not listed is excluded. Omit `roles` for full permissions.
+
+**Admin API returns 403**
+The user does not have the required role (e.g., `tide-realm-admin` on `realm-management`). Delegation can only use roles the user already has.

package/playbooks/start-tidecloak-dev.md

@@ -0,0 +1,130 @@
+# Start TideCloak for Development
+
+Start a TideCloak container for local development. This produces a running server — no realm, no client, no admin user yet.
+
+---
+
+## When to Use
+
+- First step of any TideCloak bootstrap
+- Rebuilding a local TideCloak after a wipe
+- Need a clean TideCloak for testing
+
+**Do not use** if TideCloak is already running and healthy. Check: `curl -sf http://localhost:8080 > /dev/null && echo "Running"`.
+
+---
+
+## Prerequisites
+
+- Docker installed and running (`docker info` succeeds)
+- `sudo` access (data directory permissions)
+- Port 8080 available (or adjust mapping)
+
+---
+
+## Steps
+
+### Step 1: Choose image
+
+| Need | Image |
+|------|-------|
+| Standard development and production | `tideorg/tidecloak-dev:latest` |
+| Staging / testing pre-release features | `tideorg/tidecloak-stg-dev:latest` |
+
+Both images include the full Tide protocol. `tidecloak-dev` is the production image. `tidecloak-stg-dev` is the development/staging image for testing.
+
+**Do not append `start-dev` or any command** to `docker run`. TideCloak images have a pre-configured entrypoint. Appending `start-dev` (a vanilla Keycloak convention) breaks Tide initialization.
+
+### Step 2: Clean previous state
+
+```bash
+docker stop tidecloak 2>/dev/null; docker rm tidecloak 2>/dev/null
+mkdir -p ./data
+sudo rm -f ./data/keycloakdb* 2>/dev/null
+sudo chown -R 1000:1000 ./data
+```
+
+Check port conflict:
+```bash
+lsof -i :8080 >/dev/null 2>&1 && echo "ERROR: Port 8080 in use" && exit 1
+```
+
+### Step 3: Start container
+
+**Dev image (recommended for development):**
+
+No ORK/threshold env vars needed — the dev image has built-in defaults.
+
+```bash
+sudo docker run -d --name tidecloak \
+  -v "$(pwd)/data:/opt/keycloak/data/h2" \
+  -p 8080:8080 \
+  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
+  -e KC_BOOTSTRAP_ADMIN_PASSWORD=password \
+  tideorg/tidecloak-dev:latest
+```
+
+**Staging image (pre-release testing only):**
+
+Requires ORK, threshold, and payer config.
+
+```bash
+sudo docker run -d --name tidecloak \
+  -v "$(pwd)/data:/opt/keycloak/data/h2" \
+  -p 8080:8080 \
+  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
+  -e KC_BOOTSTRAP_ADMIN_PASSWORD=password \
+  -e KC_HOSTNAME="${TIDECLOAK_URL:-http://localhost:8080}" \
+  -e SYSTEM_HOME_ORK=https://sork1.tideprotocol.com \
+  -e USER_HOME_ORK=https://sork1.tideprotocol.com \
+  -e THRESHOLD_T=3 \
+  -e THRESHOLD_N=5 \
+  -e PAYER_PUBLIC=20000011d6a0e8212d682657147d864b82d10e92776c15ead43dcfdc100ebf4dcfe6a8 \
+  tideorg/tidecloak-stg-dev:latest
+```
+
+### Step 4: Wait for readiness
+
+```bash
+for i in {1..15}; do
+  curl -sf http://localhost:8080 > /dev/null 2>&1 && echo "TideCloak ready" && break
+  echo "Waiting (attempt $i/15)..."
+  sleep 5
+done
+```
+
+TideCloak typically takes 30–60 seconds to start. If it does not respond after 15 attempts, check `docker logs tidecloak`.
+
+---
+
+## Verification
+
+- [ ] `docker ps` shows `tidecloak` running
+- [ ] `curl -sf http://localhost:8080` returns 200
+- [ ] `docker logs tidecloak` shows no fatal errors
+
+---
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Container exits immediately | Stale H2 DB files | `sudo rm -f ./data/keycloakdb*` and restart |
+| `AccessDeniedException` in logs | Wrong data directory mount or permissions | Mount `./data` not `.`, run `sudo chown -R 1000:1000 ./data` |
+| Port already in use | Another container or service on 8080 | `docker rm -f $(docker ps -q --filter publish=8080)` |
+| Exit code 2, HTTPS warnings | Named volume from previous docker-compose | `docker volume rm <volume_name>`, use fresh `./data` |
+
+---
+
+## Anti-Patterns
+
+- **Do not** mount project root as data volume. Use `./data` subdirectory.
+- **Do not** omit Tide env vars (`SYSTEM_HOME_ORK`, `USER_HOME_ORK`, etc.) when using the staging image. The dev image has built-in defaults and does not need them.
+- **Do not** use `THRESHOLD_T=1` anywhere. Single-ORK compromise.
+- **Do not** reuse data directory across environments. Clean between setups.
+
+---
+
+## Next Step
+
+Proceed to playbook `bootstrap-realm-from-template`.