@tideorg/mcp 1.4.0

package/playbooks/initialize-admin-and-link-account.md

@@ -0,0 +1,235 @@
+# Initialize Admin and Link Tide Account
+
+Create the realm admin user, assign `tide-realm-admin`, generate the invite link, wait for account linking, approve user change requests, configure the IdP domain, and export the adapter JSON.
+
+---
+
+## When to Use
+
+- After `bootstrap-realm-from-template` — realm exists with IGA enabled, client change requests approved
+- Admin user does not yet exist in the realm
+
+**Do not use** if the admin already has `tideUserKey` set. Check: `curl -H "Authorization: Bearer $TOKEN" "$TIDECLOAK_URL/admin/realms/$REALM_NAME/users?username=admin" | jq -r '.[0].attributes.tideUserKey[0] // empty'`.
+
+---
+
+## Prerequisites
+
+- TideCloak running with realm created and IGA enabled (playbook `bootstrap-realm-from-template` complete)
+- `curl`, `jq` installed
+- A browser to open the invite link (interactive step)
+
+---
+
+## Steps
+
+### Step 1: Create admin user
+
+```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}"
+ADMIN_EMAIL="${ADMIN_EMAIL:-admin@yourorg.com}"
+
+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)"
+curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/users" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{\"username\":\"admin\",\"email\":\"$ADMIN_EMAIL\",\"enabled\":true}"
+```
+
+### Step 1b: Approve user creation change request (if any)
+
+With IGA enabled, user creation usually generates a change request. Approve before proceeding. **Note**: When the master admin token creates the first user, IGA may not generate a change request (the master admin bypasses realm-level IGA). The `approve_and_commit` function handles this gracefully — if no requests exist, it skips. VERIFIED (atproto-learnings L-02).
+
+```bash
+sleep 2
+approve_and_commit users
+```
+
+(Use the `approve_and_commit` function from `bootstrap-realm-from-template`.)
+
+**Failure if skipped**: User lookup in Step 2 returns `null`. Role lookup returns `{"error":"..."}` which gets passed as the role mapping body, producing `Invalid json representation for RoleRepresentation`.
+
+### Step 2: Assign tide-realm-admin role
+
+`tide-realm-admin` is a **client role** on the `realm-management` client, not a realm role.
+
+```bash
+TOKEN="$(get_token)"
+USER_ID=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/users?username=admin" \
+  -H "Authorization: Bearer $TOKEN" | jq -r '.[0].id')
+
+if [ -z "$USER_ID" ] || [ "$USER_ID" = "null" ]; then
+  echo "ERROR: Could not find admin user. Was the user change request approved?"
+  exit 1
+fi
+
+TOKEN="$(get_token)"
+CLIENT_UUID=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/clients?clientId=realm-management" \
+  -H "Authorization: Bearer $TOKEN" | jq -r '.[0].id')
+
+ROLE_JSON=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/clients/$CLIENT_UUID/roles/tide-realm-admin" \
+  -H "Authorization: Bearer $TOKEN")
+
+# Validate we got a role, not an error
+if echo "$ROLE_JSON" | jq -e '.error' > /dev/null 2>&1; then
+  echo "ERROR: tide-realm-admin role not found: $ROLE_JSON"
+  exit 1
+fi
+
+TOKEN="$(get_token)"
+curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/users/$USER_ID/role-mappings/clients/$CLIENT_UUID" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "[$ROLE_JSON]"
+```
+
+### Step 3: Generate invite link
+
+Use the required-action-link endpoint. **Do not use `execute-actions-email`** — it fails on the dev image without SMTP configuration (`"Invalid sender address 'null'"`). The direct link method works without SMTP. VERIFIED (LEARNINGS-batch-008 L-05).
+
+```bash
+TOKEN="$(get_token)"
+INVITE_LINK=$(curl -s -X POST \
+  "$TIDECLOAK_URL/admin/realms/$REALM_NAME/tideAdminResources/get-required-action-link?userId=$USER_ID&lifespan=43200" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '["link-tide-account-action"]')
+
+echo "====================================="
+echo "Open this link in a browser to link your admin Tide account:"
+echo "$INVITE_LINK"
+echo "====================================="
+```
+
+**This is an interactive step.** The admin must open the link in a browser and complete the Tide account linking flow. The script cannot automate this — it requires the user's browser.
+
+### Step 4: Wait for account linking
+
+```bash
+echo "Waiting for admin to link Tide account..."
+while true; do
+  TOKEN="$(get_token)"
+  KEY=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/users?username=admin" \
+    -H "Authorization: Bearer $TOKEN" | jq -r '.[0].attributes.tideUserKey[0] // empty')
+  [ -n "$KEY" ] && echo "Account linked." && break
+  sleep 5
+done
+```
+
+### Step 5: Approve user change requests
+
+```bash
+# Reuse approve_and_commit from bootstrap-realm-from-template
+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 users
+approve_and_commit roles
+approve_and_commit clients
+```
+
+**Sweep all types.** Account linking generates a user change request for the `tideUserKey` attribute write. The IGA toggle and setUpTideRealm may also have generated accumulated client change requests. Approve all three types here. VERIFIED (atproto-learnings L-06, L-07).
+
+### Step 6: Update CustomAdminUIDomain
+
+Required for enclave approval popups to work from the app origin.
+
+```bash
+TOKEN="$(get_token)"
+INST=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/identity-provider/instances/tide" \
+  -H "Authorization: Bearer $TOKEN")
+UPDATED=$(echo "$INST" | jq --arg d "$CLIENT_APP_URL" '.config.CustomAdminUIDomain=$d')
+curl -s -X PUT "$TIDECLOAK_URL/admin/realms/$REALM_NAME/identity-provider/instances/tide" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" -d "$UPDATED"
+
+curl -s -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/vendorResources/sign-idp-settings" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### Step 7: Export adapter JSON
+
+```bash
+TOKEN="$(get_token)"
+CLIENT_UUID=$(curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/clients?clientId=$CLIENT_NAME" \
+  -H "Authorization: Bearer $TOKEN" | jq -r '.[0].id')
+
+ADAPTER_OUTPUT="${ADAPTER_OUTPUT:-./data/tidecloak.json}"
+curl -s "$TIDECLOAK_URL/admin/realms/$REALM_NAME/vendorResources/get-installations-provider?clientId=$CLIENT_UUID&providerId=keycloak-oidc-keycloak-json" \
+  -H "Authorization: Bearer $TOKEN" > "$ADAPTER_OUTPUT"
+
+echo "Adapter config saved to $ADAPTER_OUTPUT"
+```
+
+Verify the export:
+```bash
+node -e "const c=require('$ADAPTER_OUTPUT'); console.log('jwk:', !!c.jwk, 'vendorId:', !!c.vendorId, 'homeOrkUrl:', !!c.homeOrkUrl)"
+```
+
+---
+
+## Verification
+
+- [ ] Admin user exists with `tideUserKey` attribute set
+- [ ] `tide-realm-admin` assigned (client role on `realm-management`)
+- [ ] No pending user change requests remain
+- [ ] CustomAdminUIDomain matches app origin
+- [ ] Adapter JSON at `$ADAPTER_OUTPUT` contains `jwk`, `vendorId`, `homeOrkUrl`
+
+---
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Invite link returns 404 | `requiredActions` missing from realm template | Use full template with `link-tide-account-action` |
+| "Could not find configuration for Required Action" | Tide env vars missing from container | Restart container with all required env vars |
+| `tideUserKey` never appears | Admin didn't complete the linking flow | Open invite link in browser, complete the flow |
+| Enclave popups don't work from app | CustomAdminUIDomain not set | Run Step 6 |
+| Adapter JSON missing `jwk` | IGA not enabled | Run `toggle-iga` from `bootstrap-realm-from-template` Step 5 |
+
+---
+
+## Anti-Patterns
+
+- **Do not** auto-approve IGA role assignments from the backend. `requiresApprovalPopup: true` means the browser enclave is required for VVK-signed UserContexts.
+- **Do not** skip the invite link step. Account linking is interactive by design.
+- **Do not** use `hasRealmRole("tide-realm-admin")` to check admin status. It is a client role on `realm-management`. Use `hasClientRole("tide-realm-admin", "realm-management")`.
+
+---
+
+## Next Step
+
+Bootstrap is complete. Proceed to app integration:
+- Fresh app → playbook `add-auth-nextjs-fresh`
+- E2EE needed → playbook `configure-e2ee-roles-and-policies`

package/playbooks/migrate-from-existing-auth.md

@@ -0,0 +1,198 @@
+# Migrate from Existing Auth to TideCloak
+
+Replace your current identity provider with TideCloak while keeping standard OIDC flows intact.
+
+---
+
+## When to Use
+
+- Migrating from vanilla Keycloak to TideCloak
+- Migrating from Auth0, Okta, or any other OIDC-compliant provider
+- Want distributed key signing, zero-knowledge passwords, or quorum governance without rewriting auth flows
+
+**Do not use** if starting a greenfield project. See [add-auth-nextjs-fresh.md](add-auth-nextjs-fresh.md) instead.
+
+---
+
+## From Keycloak
+
+Keycloak to TideCloak is the simplest path. TideCloak uses the same admin console, same OIDC endpoints, and same SDK surface.
+
+### Steps
+
+1. **Deploy TideCloak** in place of (or alongside) your Keycloak instance.
+2. **Download the new adapter config** (`tidecloak.json`) from the TideCloak admin console:
+   - Clients -> {your-client} -> Installation -> Keycloak OIDC JSON
+3. **Replace `keycloak.json` with `tidecloak.json`** in your application:
+   ```bash
+   # Backup existing config
+   cp data/keycloak.json data/keycloak.json.bak
+
+   # Replace with TideCloak adapter
+   cp tidecloak.json data/keycloak.json
+   # Or rename to tidecloak.json and update your config loader path
+   ```
+4. **No code changes needed.** Same SDK, same OIDC protocol. The application does not need to know it is talking to TideCloak instead of Keycloak.
+
+### What to verify after swap
+
+```bash
+# Confirm discovery endpoint responds
+curl -s http://localhost:8080/realms/{realm}/.well-known/openid-configuration | jq .issuer
+
+# Confirm JWKS endpoint responds
+curl -s http://localhost:8080/realms/{realm}/protocol/openid-connect/certs | jq .keys[0].kty
+```
+
+---
+
+## From Other OIDC Providers (Auth0, Okta, etc.)
+
+Any application using standard OIDC can point to TideCloak by updating configuration values. No TideCloak-specific SDK is required for basic authentication.
+
+### Steps
+
+1. **Deploy TideCloak.**
+2. **Create a realm and client** in TideCloak matching your existing client configuration (redirect URIs, scopes, grant types).
+3. **Update your application's OIDC configuration:**
+
+   | Setting | Old value (example: Auth0) | New value (TideCloak) |
+   |---------|---------------------------|----------------------|
+   | Discovery endpoint | `https://tenant.auth0.com/.well-known/openid-configuration` | `http://localhost:8080/realms/{realm}/.well-known/openid-configuration` |
+   | Issuer URL | `https://tenant.auth0.com/` | `http://localhost:8080/realms/{realm}` |
+   | Client ID | Your Auth0 client ID | Your TideCloak client ID |
+   | Client secret (if confidential) | Your Auth0 client secret | Your TideCloak client secret |
+
+4. **Standard OIDC -- no TideCloak SDK required for basic auth.** Your existing OIDC library (e.g., `openid-client`, `next-auth` with generic provider, `passport-openidconnect`) works without changes beyond the config values above.
+5. **Add TideCloak SDK only if you need Tide-specific features:**
+   ```bash
+   npm install @tidecloak/js
+   # or
+   npm install @tidecloak/react
+   ```
+   The SDK is required for E2EE features (`doEncrypt()` / `doDecrypt()`) and direct enclave interactions. It is not required for login, logout, or token verification.
+
+---
+
+## What Stays the Same
+
+These are standard OIDC behaviors. TideCloak does not change them:
+
+- **OIDC/OAuth 2.0 flows** -- Authorization Code, PKCE, Client Credentials all work identically.
+- **JWT format and claims structure** -- Access tokens are standard JWTs. No proprietary wrapper.
+- **JWKS verification endpoint** -- `GET /realms/{realm}/protocol/openid-connect/certs` returns standard JWK set. Existing JWT verification code works without modification.
+- **Role claim paths** -- `realm_access.roles` for realm roles, `resource_access.{client}.roles` for client roles. Same as Keycloak.
+- **Redirect URI patterns** -- Same configuration, same behavior.
+
+---
+
+## What You Gain
+
+These improvements are invisible to the application. No code changes required to benefit:
+
+| Feature | What it means |
+|---------|--------------|
+| **VVK threshold signing** | JWTs are signed by a distributed Vendor Verification Key. No single signing key exists to steal. Compromise of one node does not compromise tokens. |
+| **Zero-knowledge passwords** | User passwords are never stored as hashes. The server never sees the plaintext password. Credential database breaches yield nothing usable. |
+| **Quorum governance** | Admin changes (role assignments, policy updates) require multiple admin approvals before taking effect. Single compromised admin cannot unilaterally escalate privileges. |
+| **Optional E2EE** | `doEncrypt()` / `doDecrypt()` available via TideCloak SDK for end-to-end encrypted data fields. Requires `@tidecloak/js` or `@tidecloak/react`. |
+
+---
+
+## Verification Checklist
+
+### Discovery and Tokens
+
+- [ ] `GET /realms/{realm}/.well-known/openid-configuration` returns valid JSON with correct `issuer`
+- [ ] `GET /realms/{realm}/protocol/openid-connect/certs` returns JWKS with at least one key
+- [ ] Application obtains access token via Authorization Code flow
+- [ ] Access token decodes to standard JWT with expected claims (`sub`, `realm_access`, `iss`)
+
+### Login and Logout
+
+- [ ] Login redirects to TideCloak login page (not old provider)
+- [ ] Successful login redirects back to application with valid tokens
+- [ ] Logout clears session and redirects correctly
+- [ ] Silent token refresh works (no forced re-login after token expiry)
+
+### JWT Verification
+
+- [ ] Existing server-side JWT verification code accepts TideCloak tokens without modification
+- [ ] `iss` claim matches the new TideCloak issuer URL
+- [ ] Role claims at `realm_access.roles` are populated correctly
+
+### No Residual Old Auth
+
+- [ ] No requests to old provider endpoints in browser network tab
+- [ ] No old provider cookies or tokens in browser storage
+- [ ] No old provider SDKs still loaded in the application bundle
+
+---
+
+## Common Failures
+
+### Issuer Mismatch
+
+**Symptom**: JWT verification fails. Error message mentions issuer validation.
+
+**Cause**: Application still expects the old provider's issuer URL (e.g., `https://tenant.auth0.com/`) but receives TideCloak's issuer (`http://localhost:8080/realms/myrealm`).
+
+**Fix**: Update the expected issuer in your JWT verification configuration to match TideCloak's issuer URL exactly. Check trailing slashes.
+
+---
+
+### CORS Errors After Switch
+
+**Symptom**: Browser console shows CORS errors on token or JWKS requests.
+
+**Cause**: TideCloak's Web Origins configuration does not include your application's origin.
+
+**Fix**: In TideCloak admin console: Clients -> {your-client} -> Settings -> Web Origins. Add your application origin (e.g., `http://localhost:3000`).
+
+---
+
+### Redirect URI Mismatch
+
+**Symptom**: Login fails with "Invalid redirect_uri" error on TideCloak login page.
+
+**Cause**: The redirect URI your application sends does not match any URI registered in TideCloak.
+
+**Fix**: In TideCloak admin console: Clients -> {your-client} -> Settings -> Valid Redirect URIs. Add all URIs your application uses (including `http://localhost:*` for development).
+
+---
+
+### Old Provider Tokens Cached
+
+**Symptom**: Application appears logged in but API calls fail with 401. Or infinite redirect loop.
+
+**Cause**: Browser still holds tokens or cookies from the old provider.
+
+**Fix**: Clear site data in browser DevTools (Application -> Storage -> Clear site data). Test in incognito window for a clean session.
+
+---
+
+### Client Secret Not Configured (Confidential Clients)
+
+**Symptom**: Token exchange fails with 401 from TideCloak token endpoint.
+
+**Cause**: Confidential client in TideCloak does not have the client secret configured, or the application is sending the old provider's secret.
+
+**Fix**: In TideCloak admin console: Clients -> {your-client} -> Credentials. Copy the secret and update your application's configuration.
+
+---
+
+### Role Claims Missing or Different Path
+
+**Symptom**: Application cannot find user roles after migration.
+
+**Cause**: Old provider used a custom claim path (e.g., Auth0 namespaced claims like `https://myapp.com/roles`). TideCloak uses standard Keycloak paths.
+
+**Fix**: Update role extraction code to read from `realm_access.roles` (realm roles) or `resource_access.{client}.roles` (client roles). If your application hardcodes a custom claim namespace, replace it.
+
+---
+
+## References
+
+- Source: SDK documentation, operational exemplars
+- Keycloak migration: same admin console, same OIDC endpoints, config swap only
+- Generic OIDC migration: config-only change, no SDK required for basic auth