@tideorg/mcp 1.4.0

package/playbooks/add-rbac-nextjs.md

@@ -0,0 +1,190 @@
+# Add Role-Based Access Control (RBAC) in Next.js
+
+Implement role-based access control using Tide JWT roles.
+
+---
+
+## When to Use
+
+- Need different access levels (admin, editor, viewer)
+- Need fine-grained permissions
+- Have configured roles in TideCloak realm
+- Roles assigned to users via IGA
+
+---
+
+## Prerequisites
+
+**Required — do not skip**:
+
+1. API protection implemented: [protect-api-nextjs.md](protect-api-nextjs.md) **must be completed first**. That playbook creates the files this playbook imports (`lib/auth/tideJWT.ts`, `lib/auth/protect.ts`, `lib/auth/tidecloakConfig.ts`) and installs `jose`.
+2. Roles created in TideCloak Admin Console
+3. Users assigned roles (via IGA if enabled)
+
+**Verify before proceeding**:
+```bash
+# These files must exist (created by protect-api-nextjs.md)
+ls lib/auth/tideJWT.ts lib/auth/protect.ts lib/auth/tidecloakConfig.ts
+# jose must be installed
+grep '"jose"' package.json
+```
+
+If any are missing, complete [protect-api-nextjs.md](protect-api-nextjs.md) first.
+
+---
+
+## Role Storage in Tide
+
+Roles appear in JWT token:
+
+```json
+{
+  "realm_access": {
+    "roles": ["admin", "offline_access", "_tide_enabled"]
+  },
+  "resource_access": {
+    "my-client": {
+      "roles": ["manage-account"]
+    }
+  }
+}
+```
+
+**Realm roles**: Global to realm (`realm_access.roles`)
+**Client roles**: Specific to client (`resource_access.{client-id}.roles`)
+
+---
+
+## Client-Side RBAC (UI Gating Only)
+
+```typescript
+// components/AdminPanel.tsx
+'use client';
+
+import { useTideCloak } from '@tidecloak/nextjs';
+
+export function AdminPanel() {
+  const { hasRealmRole } = useTideCloak();
+
+  if (!hasRealmRole('admin')) {
+    return <div>Access denied</div>;
+  }
+
+  return (
+    <div>
+      <h1>Admin Panel</h1>
+      {/* admin content */}
+    </div>
+  );
+}
+```
+
+**Warning**: This is UI gating. Real enforcement happens server-side.
+
+---
+
+## Server-Side RBAC (Real Authorization)
+
+```typescript
+// app/api/admin/users/route.ts
+import { withRole } from '@/lib/auth/protect';
+
+// Requires 'admin' role
+export const GET = withRole('admin', async (req, jwt) => {
+  return Response.json({ users: [...] });
+});
+```
+
+**Multiple roles** (any match):
+
+```typescript
+// lib/auth/protect.ts
+export function withAnyRole(roles: string[], handler: AuthenticatedHandler) {
+  return withAuth(async (req, jwt) => {
+    const hasAnyRole = roles.some(role => hasRole(jwt, role));
+    if (!hasAnyRole) {
+      return Response.json({ error: 'Forbidden' }, { status: 403 });
+    }
+    return handler(req, jwt);
+  });
+}
+
+// Usage
+export const GET = withAnyRole(['admin', 'editor'], async (req, jwt) => {
+  return Response.json({ data: [...] });
+});
+```
+
+---
+
+## Role Hierarchies
+
+TideCloak supports composite roles. Define in Admin Console:
+
+1. Create `super-admin` role
+2. Add `admin`, `editor`, `viewer` as composite roles
+3. Assign `super-admin` to user → user inherits all roles
+
+---
+
+## E2EE Role-Based Encryption
+
+Tide E2EE uses tag-based roles for **self-encryption** (user-bound, private data):
+
+**Role pattern**: `_tide_<tag>.selfencrypt`, `_tide_<tag>.selfdecrypt`
+
+```typescript
+// Client-side E2EE with role enforcement (self-encryption)
+const { doEncrypt, doDecrypt } = useTideCloak();
+
+// Requires _tide_ssn.selfencrypt role
+const ciphertext = await doEncrypt('ssn', '123-45-6789');
+
+// Requires _tide_ssn.selfdecrypt role
+const plaintext = await doDecrypt('ssn', ciphertext);
+```
+
+Fabric enforces roles cryptographically. See [canon/concepts.md#tag-based-e2ee-roles](../canon/concepts.md#tag-based-e2ee-roles).
+
+**Self-encryption is user-bound**: only the encrypting user can decrypt. Giving another user the `selfdecrypt` role does NOT let them decrypt your data. For shared data between users, use policy-governed VVK encryption with a Forseti contract instead. See [setup-forseti-e2ee.md](setup-forseti-e2ee.md) and [canon/anti-patterns.md AP-24](../canon/anti-patterns.md#ap-24-using-self-encryption-for-shared-data-between-users).
+
+---
+
+## Verification Checklist
+
+- [ ] Admin API rejects non-admin users (403)
+- [ ] Role-based UI elements show/hide correctly
+- [ ] Multiple roles (OR condition) work
+- [ ] Composite roles inherit permissions
+- [ ] E2EE roles enforce encrypt/decrypt access
+
+---
+
+## Common Failures
+
+### Role Always Missing in JWT
+
+**Fix**: See [diagnose-missing-roles-or-claims.md](diagnose-missing-roles-or-claims.md).
+
+---
+
+## Do Not Do This
+
+### ❌ Do Not Mix Tide Roles with App Roles
+
+```typescript
+// ❌ WRONG: Confuse E2EE role with app admin role
+if (hasRealmRole('_tide_ssn.selfencrypt')) {
+  // Grant admin access (WRONG)
+}
+```
+
+**Why**: `_tide_*` roles are for E2EE, not app permissions. See [canon/anti-patterns.md AP-18](../canon/anti-patterns.md#ap-18-mixing-tide-roles-with-application-roles).
+
+---
+
+## References
+
+- [protect-api-nextjs.md](protect-api-nextjs.md) - API protection
+- [canon/concepts.md](../canon/concepts.md#tag-based-e2ee-roles) - E2EE roles
+- [diagnose-missing-roles-or-claims.md](diagnose-missing-roles-or-claims.md) - Debug roles

package/playbooks/bootstrap-realm-from-template.md

@@ -0,0 +1,170 @@
+# Bootstrap Realm from Template
+
+Create a TideCloak realm from the canonical template, initialize Tide licensing and IGA, and approve the initial client change requests.
+
+---
+
+## When to Use
+
+- After `start-tidecloak-dev` — TideCloak is running but has no realm
+- Automating realm setup instead of clicking through Admin Console
+- Rebuilding a realm from scratch
+
+**Do not use** if the realm already exists. Check: `curl -sf -H "Authorization: Bearer $TOKEN" http://localhost:8080/admin/realms/$REALM_NAME > /dev/null && echo "Exists"`.
+
+---
+
+## Prerequisites
+
+- TideCloak running and reachable (playbook `start-tidecloak-dev` complete)
+- `curl`, `jq` installed
+- `templates/shared/realm.json.template` available (or equivalent realm template)
+
+---
+
+## Steps
+
+### Step 1: Get master admin token
+
+```bash
+TIDECLOAK_URL="${TIDECLOAK_URL:-http://localhost:8080}"
+REALM_NAME="${REALM_NAME:-myapp}"
+CLIENT_NAME="${CLIENT_NAME:-myclient}"
+CLIENT_APP_URL="${CLIENT_APP_URL:-http://localhost:3000}"
+
+get_token() {
+  curl -s -X POST "$TIDECLOAK_URL/realms/master/protocol/openid-connect/token" \
+    -H "Content-Type: application/x-www-form-urlencoded" \
+    -d "username=admin&password=password&grant_type=password&client_id=admin-cli" \
+    | jq -r '.access_token'
+}
+TOKEN="$(get_token)"
+```
+
+### Step 2: Prepare realm template
+
+```bash
+TMP_REALM="$(mktemp)"
+cp templates/shared/realm.json.template "$TMP_REALM"
+sed -i "s|REALM_NAME|$REALM_NAME|g" "$TMP_REALM"
+sed -i "s|CLIENT_NAME|$CLIENT_NAME|g" "$TMP_REALM"
+sed -i "s|CLIENT_APP_URL|$CLIENT_APP_URL|g" "$TMP_REALM"
+```
+
+The template contains placeholders: `REALM_NAME`, `CLIENT_NAME`, `CLIENT_APP_URL`. All three must be replaced before import.
+
+### Step 3: Import realm
+
+```bash
+TOKEN="$(get_token)"
+curl -s -X POST "$TIDECLOAK_URL/admin/realms" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  --data-binary @"$TMP_REALM"
+rm -f "$TMP_REALM"
+```
+
+### Step 4: Initialize Tide realm
+
+```bash
+TOKEN="$(get_token)"
+curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/vendorResources/setUpTideRealm" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  --data-urlencode "email=admin@yourorg.com" \
+  --data-urlencode "isRagnarokEnabled=true"
+```
+
+This activates the Tide license and generates the VRK. No manual "Manage License" step needed.
+
+**Critical:** Content-Type must be `application/x-www-form-urlencoded`. JSON causes failure.
+
+### Step 5: Enable IGA
+
+```bash
+TOKEN="$(get_token)"
+curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/toggle-iga" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  --data-urlencode "isIGAEnabled=true"
+```
+
+### Step 6: Approve and commit client change requests
+
+Realm creation + Tide setup generates change requests that must be approved before proceeding.
+
+```bash
+approve_and_commit() {
+  local TYPE=$1
+  TOKEN="$(get_token)"
+  local requests=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/$TYPE/requests" \
+    -H "Authorization: Bearer $TOKEN" 2>/dev/null || echo "[]")
+
+  echo "$requests" | jq -c '.[]' | while read -r req; do
+    local id=$(echo "$req" | jq -r .draftRecordId)
+    local cst=$(echo "$req" | jq -r .changeSetType)
+    local at=$(echo "$req" | jq -r .actionType)
+    local payload="{\"changeSetId\":\"$id\",\"changeSetType\":\"$cst\",\"actionType\":\"$at\"}"
+
+    TOKEN="$(get_token)"
+    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/sign" \
+      -H "Authorization: Bearer $TOKEN" \
+      -H "Content-Type: application/json" -d "$payload"
+
+    curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tide-admin/change-set/commit" \
+      -H "Authorization: Bearer $TOKEN" \
+      -H "Content-Type: application/json" -d "$payload"
+  done
+}
+
+approve_and_commit clients
+```
+
+---
+
+## Verification
+
+- [ ] `curl -H "Authorization: Bearer $TOKEN" "$TIDECLOAK_URL/admin/realms/$REALM_NAME"` returns realm JSON
+- [ ] Realm has Tide IdP listed: `curl -H "Authorization: Bearer $TOKEN" "$TIDECLOAK_URL/admin/realms/$REALM_NAME/identity-provider/instances"` includes `tide`
+- [ ] IGA is enabled
+- [ ] No pending client change requests remain
+
+---
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| "Could not create tide realm" | JSON sent to `setUpTideRealm` instead of form data | Use `application/x-www-form-urlencoded` |
+| "email is null or empty" | Missing email parameter | Add `--data-urlencode "email=..."` |
+| 404 on setUpTideRealm | Wrong path (`/tide-admin/setUpTideRealm`) | Correct path: `/vendorResources/setUpTideRealm` |
+| Realm import fails | Placeholders not replaced in template | Verify `sed` replaced all three: `REALM_NAME`, `CLIENT_NAME`, `CLIENT_APP_URL` |
+| Missing `link-tide-account-action` | Minimal realm template used | Use full template from `templates/shared/realm.json.template` |
+
+---
+
+## Anti-Patterns
+
+- **Do not** create a minimal realm.json. Every section in the template is required.
+- **Do not** skip IGA enablement. The `jwk` field in adapter JSON only appears with IGA enabled.
+- **Do not** reorder steps. License before IGA. IGA before change request approval.
+- **Do not** leave license activation as a manual step. `setUpTideRealm` handles it automatically.
+- **Do not** blindly set `registrationAllowed: true`. This is a deployment decision — open registration lets any user sign up via Tide IdP. For invite-only apps, keep it `false` and use admin invite links (`tideAdminResources/get-required-action-link`). The admin invite link bypasses the registration gate. VERIFIED (LEARNINGS-batch-008 L-01).
+- **Do not** use the standard Keycloak adapter export path (`/clients/{id}/installation/providers/...`). Use `vendorResources/get-installations-provider?clientId={uuid}&providerId=keycloak-oidc-keycloak-json`. The standard path returns a minimal adapter missing `jwk`, `vendorId`, `homeOrkUrl`. VERIFIED (LEARNINGS-batch-008 L-04).
+
+### Realm Deletion on Dev Image (H2)
+
+If re-running bootstrap against an existing realm, delete the old realm first. On the H2 dev database, `DELETE /admin/realms/{realm}` fails with FK constraint violations on composite roles. Use this sequence:
+
+1. Disable IGA: `POST /tide-admin/toggle-iga` with `isIGAEnabled=false`
+2. Delete Tide IdP: `DELETE /identity-provider/instances/tide`
+3. Strip ALL composite roles (realm-level and per-client) — remove composites from `default-roles-*`, `realm-admin`, `manage-account`, etc.
+4. Delete realm: `DELETE /admin/realms/{realm}`
+
+Or: stop the container, delete `data/keycloakdb*`, restart. VERIFIED (LEARNINGS-batch-008 L-06).
+
+---
+
+## Next Step
+
+Proceed to playbook `initialize-admin-and-link-account`.

package/playbooks/configure-e2ee-roles-and-policies.md

@@ -0,0 +1,196 @@
+# Configure E2EE Roles and Policies
+
+Create encryption/decryption realm roles, assign them to default users, and approve the resulting change requests. Optionally deploy a Forseti contract for shared (policy-governed) encryption.
+
+This is realm-level preparation. App-level E2EE wiring (`doEncrypt`/`doDecrypt`) is covered in playbook `setup-forseti-e2ee` and skill `tide-rbac-and-e2ee`.
+
+---
+
+## When to Use
+
+- After `initialize-admin-and-link-account` — admin linked, adapter exported
+- App needs self-encryption (private data, only the encrypting user can decrypt)
+- App needs shared encryption (policy-governed, multiple users can decrypt)
+
+**Do not use** if E2EE roles already exist. Check: `curl -H "Authorization: Bearer $TOKEN" "$TIDECLOAK_URL/admin/realms/$REALM_NAME/roles" | jq '.[].name' | grep '_tide_'`.
+
+---
+
+## Prerequisites
+
+- TideCloak running with realm fully bootstrapped (all three prior playbooks complete)
+- Admin has linked Tide account
+- Decision: which data tags to protect (e.g., `secret`, `medical`, `vault`)
+
+---
+
+## Two Encryption Models
+
+Choose the right model before creating roles.
+
+| Model | SDK method | Who can decrypt | Roles needed |
+|-------|-----------|----------------|--------------|
+| Self-encryption | `doEncrypt`/`doDecrypt` (no policy) | Only the encrypting user | `_tide_{tag}.selfencrypt`, `_tide_{tag}.selfdecrypt` |
+| Policy-governed (VVK) | `IAMService.doEncrypt(data, policyBytes)` | Any user whose doken satisfies the Forseti contract | `_tide_{tag}.selfencrypt`, `_tide_{tag}.selfdecrypt` (voucher gates) + a regular role for the contract |
+
+Self-encryption is simpler. Start here unless you explicitly need sharing.
+
+**After completing this playbook**: Self-encryption works immediately. Shared encryption does NOT — it additionally requires the admin signing ceremony from `setup-forseti-e2ee`. That ceremony is browser-only (cannot be scripted) and must happen before any user can encrypt shared data. If the app offers a "shared" mode, it must be blocked/gated until the signing ceremony is complete. VERIFIED (session-002).
+
+**Anti-pattern:** Using self-encryption (`doEncrypt`/`doDecrypt` without policy) for shared data. Ciphertext is bound to the encrypting user's identity. Another user with the same `selfdecrypt` role cannot decrypt it. VERIFIED.
+
+**Anti-pattern:** Renaming `selfencrypt`/`selfdecrypt` to `encrypt`/`decrypt` to "enable sharing". The role suffix does not change the encryption model. The SDK call path determines self vs shared. See AP-26.
+
+**If self-encryption fails**, fix the self-encryption setup (roles, IGA approval, re-login). Do not switch models as a "fix". See T-13.
+
+---
+
+## Steps: Self-Encryption Roles
+
+### Step 1: Add roles to realm template
+
+Add role entries for each tag to `templates/shared/realm.json.template` under `roles.realm`, and include them in the default composite role:
+
+```json
+{ "name": "_tide_secret.selfencrypt", "description": "Encrypt data with tag: secret" },
+{ "name": "_tide_secret.selfdecrypt", "description": "Decrypt data with tag: secret" }
+```
+
+Update the default composite:
+```json
+{
+  "name": "default-roles-REALM_NAME",
+  "composites": { "realm": ["_tide_enabled", "appUser", "_tide_secret.selfencrypt", "_tide_secret.selfdecrypt"] }
+}
+```
+
+See `templates/shared/role-matrix.md` for the full role reference.
+
+### Step 2: Create roles via API (existing realm)
+
+If the realm already exists (no template re-import), create roles via API:
+
+```bash
+TOKEN="$(get_token)"
+for ROLE in "_tide_secret.selfencrypt" "_tide_secret.selfdecrypt"; do
+  curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/roles" \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/json" \
+    -d "{\"name\":\"$ROLE\",\"description\":\"E2EE role for tag: secret\"}"
+done
+```
+
+### Step 3: Assign roles to default composite
+
+```bash
+TOKEN="$(get_token)"
+DEFAULT_ROLE_ID=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/roles/default-roles-$REALM_NAME" \
+  -H "Authorization: Bearer $TOKEN" | jq -r '.id')
+
+ROLES_JSON=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/roles" \
+  -H "Authorization: Bearer $TOKEN" \
+  | jq '[.[] | select(.name | startswith("_tide_secret."))]')
+
+curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/roles-by-id/$DEFAULT_ROLE_ID/composites" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "$ROLES_JSON"
+```
+
+### Step 4: Approve change requests
+
+Role assignments produce IGA change requests that must be approved:
+
+```bash
+approve_and_commit roles
+```
+
+(Use the `approve_and_commit` function from prior playbooks.)
+
+### Step 5: Users must re-login
+
+After roles are committed, users must log out and back in (or call `forceUpdateToken()`) for the new roles to appear in their doken. Token refresh delay is up to 120 seconds.
+
+---
+
+## Steps: Policy-Governed Encryption (Shared)
+
+For shared data where multiple users need to decrypt, you need voucher gate roles AND a regular role checked by a Forseti contract.
+
+### Step 1: Create all three role types
+
+```bash
+TOKEN="$(get_token)"
+for ROLE in "_tide_shared.selfencrypt" "_tide_shared.selfdecrypt" "shared-data-access"; do
+  curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/roles" \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/json" \
+    -d "{\"name\":\"$ROLE\"}"
+done
+```
+
+| Role | Purpose |
+|------|---------|
+| `_tide_shared.selfencrypt` | Voucher gate — enables `vendorsign` action at ORK |
+| `_tide_shared.selfdecrypt` | Voucher gate — enables `vendordecrypt` action at ORK |
+| `shared-data-access` | Forseti contract checks this for actual access control |
+
+Add all three to the default composite role.
+
+### Step 2: Forseti contract deployment (browser signing flow only)
+
+**There is no REST API for deploying Forseti contracts.** The endpoint `PUT /tide-admin/forseti-contracts` does not exist on the dev or staging image (returns 404/405). VERIFIED (learning-batch-003, L-06; session-001, RB-010).
+
+The contract is deployed as part of the PolicySignRequest flow in the admin's browser:
+1. Embed the contract C# source code in the admin page
+2. Compute the SHA-512 hash client-side as the `contractId`
+3. Use `policyRequest.addForsetiContractToUpload(contractSource)` during the signing flow
+
+The contract source code is included in the signing request and uploaded to the ORKs automatically. No prior deployment step is needed.
+
+See `setup-forseti-e2ee.md` for the full browser-based signing flow.
+
+### Step 3: Policy signing (frontend only)
+
+Policy signing requires the admin's browser enclave. It cannot be done from a script.
+
+The admin must:
+1. Log in to the app as `tide-realm-admin`
+2. Sign the role policy (init-cert) via approval popup
+3. Sign the encryption policy via approval popup
+
+Both policies must be signed before the group is usable. See playbook `setup-forseti-e2ee` for the full frontend flow.
+
+**Anti-pattern:** Trying to sign policies from the init script or backend. Signing requires `requiresApprovalPopup: true` → browser enclave. The script can prepare (deploy contracts, attach policies), but signing must happen from the frontend. VERIFIED.
+
+---
+
+## Verification
+
+- [ ] `_tide_{tag}.selfencrypt` and `_tide_{tag}.selfdecrypt` roles exist in realm
+- [ ] Roles are in the default composite (or assigned to target users)
+- [ ] All role change requests approved and committed
+- [ ] (Self-encryption) `doEncrypt`/`doDecrypt` works in app after user re-login
+- [ ] (Shared encryption) Forseti contract deployed, both policies signed by admin
+
+---
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `doEncrypt` throws "unauthorized" | User lacks `_tide_{tag}.selfencrypt` role | Create and assign the role, approve via IGA |
+| "vendordecrypt voucher not allowed" | User lacks `_tide_{tag}.selfdecrypt` role | Same — create, assign, approve |
+| "Policy supplied has not been signed" | Admin policy not signed via browser enclave | Admin must sign both policies from frontend |
+| Decrypt fails for another user (self-encryption) | Self-encryption binds to encrypting user | Use policy-governed VVK encryption for sharing |
+| Roles assigned but encrypt still fails | User hasn't refreshed token | Log out/in or call `forceUpdateToken()` |
+
+---
+
+## Anti-Patterns
+
+- **Do not** assign decrypt roles to all users by default for shared data. Encrypt roles can be broad; decrypt roles are your access control boundary.
+- **Do not** encrypt everything with the same tag. Different sensitivity levels should use different tags mapped to different roles.
+- **Do not** skip tags on encrypted fields. Tags define who can decrypt.
+- **Do not** use the built-in `GenericRealmAccessThresholdRole` contract for production. Deploy a custom Forseti contract.
+- **Do not** use `_tide_*` roles in your Forseti contract's `ValidateExecutor`. Those are voucher gates only. Use a regular realm role for access control.