@tideorg/mcp 1.4.0

package/playbooks/diagnose-broken-login.md

@@ -0,0 +1,234 @@
+# Diagnose Broken Login
+
+Symptom-led troubleshooting for login failures.
+
+---
+
+## Pre-Flight: Is Tide Actually Installed?
+
+Before diagnosing specific symptoms, verify a real Tide integration exists:
+
+```bash
+# 1. SDK installed?
+grep '@tidecloak/nextjs' package.json
+# If missing: npm install @tidecloak/nextjs
+
+# 2. Provider in layout?
+grep 'TideCloakProvider\|Providers' app/layout.tsx
+# If missing: no Tide provider wrapping the app
+
+# 3. Config file present?
+test -f data/tidecloak.json && echo "Found" || echo "Missing"
+# If missing: export adapter JSON from TideCloak Admin Console
+```
+
+**If check 1 or 2 fails**, stop. The app does not have a Tide integration. Complete [add-auth-nextjs-fresh.md](add-auth-nextjs-fresh.md) (or [add-auth-nextjs-existing.md](add-auth-nextjs-existing.md) for existing apps) first, then return here.
+
+**If only check 3 fails**, export the adapter JSON from TideCloak Admin Console and place it at `data/tidecloak.json`. DPoP is configured per-client in TideCloak Admin, not in the provider props. See [add-auth-nextjs-fresh.md Step 2](add-auth-nextjs-fresh.md#step-2-export-adapter-json-from-tidecloak).
+
+---
+
+## Pre-Flight: Is Adapter Config Present and Correctly Located?
+
+Before symptom-specific debugging, verify the adapter config file:
+
+```bash
+# Filename must be tidecloak.json (not adapter.json, not keycloak.json)
+
+# Next.js (server-side):
+test -f data/tidecloak.json && echo "Found data/tidecloak.json" || echo "Missing"
+
+# React/Vite or Vanilla JS (client-side):
+test -f public/tidecloak.json && echo "Found public/tidecloak.json" || echo "Missing"
+
+# Wrong filename?
+ls data/adapter.json data/keycloak.json public/adapter.json public/keycloak.json 2>/dev/null && echo "WRONG FILENAME — rename to tidecloak.json"
+
+# Does code point to the right path?
+grep -r 'configUrl\|tidecloak\.json\|adapter\.json' app/providers.tsx src/main.tsx public/auth.js 2>/dev/null
+```
+
+**If file is missing**: Export from TideCloak admin console. See [add-auth-nextjs-fresh.md Step 2](add-auth-nextjs-fresh.md#step-2-export-adapter-json-from-tidecloak).
+
+**If wrong filename**: Rename to `tidecloak.json`. The SDK does not look for `adapter.json` or `keycloak.json`.
+
+**If wrong location**: Next.js server-side code reads from `data/tidecloak.json`. React/Vite/Vanilla JS client-side SDK fetches from `public/tidecloak.json` via `configUrl`. See [canon/invariants.md I-05](../canon/invariants.md#i-05-adapter-json-configuration-required).
+
+---
+
+## Symptom: Login Hangs Indefinitely
+
+**What you see**: Click login, redirect to TideCloak, enter credentials, spinner forever.
+
+**Diagnostic steps**:
+
+```bash
+# 1. Check browser console
+# Look for: "Refused to frame" CSP error
+
+# 2. Check CSP headers
+curl -I http://localhost:3000 | grep -i content-security-policy
+
+# 3. Check silent SSO file
+curl http://localhost:3000/silent-check-sso.html
+# Should return HTML
+```
+
+**Fix**: Add Tide domains to CSP. See [add-auth-nextjs-fresh.md Step 6](add-auth-nextjs-fresh.md#step-6-configure-csp-for-swe-iframe).
+
+**Full guide**: [canon/troubleshooting.md T-01](../canon/troubleshooting.md#t-01-login-hangs-indefinitely).
+
+---
+
+## Symptom: Login Succeeds but User Lands on 404
+
+**What you see**: Credentials accepted at TideCloak, but browser shows 404 or blank page after redirect.
+
+**Diagnostic**:
+```bash
+# Check redirect URI in adapter config
+jq '.["auth-server-url"], .resource' data/tidecloak.json 2>/dev/null
+
+# Check redirect handler exists
+# App Router:
+test -f app/auth/redirect/page.tsx && echo "Found" || echo "Missing"
+# Pages Router:
+test -f pages/auth/redirect.tsx && echo "Found" || echo "Missing"
+```
+
+**Fix**: Create the redirect handler at the configured redirect path. See [canon/redirect-handler.md](../canon/redirect-handler.md) for framework-specific examples and [add-auth-nextjs-fresh.md Step 6](add-auth-nextjs-fresh.md#step-6-create-post-auth-redirect-handler).
+
+---
+
+## Symptom: Redirect URI Mismatch
+
+**What you see**: TideCloak error page: "Invalid redirect_uri".
+
+**Diagnostic**:
+```bash
+# Check client config
+# TideCloak Admin → Clients → {client} → Settings → Valid Redirect URIs
+```
+
+**Fix**: Add app URL to valid redirect URIs:
+- `http://localhost:3000/*` (dev)
+- `https://app.example.com/*` (prod)
+
+---
+
+## Symptom: Cannot Find Module @tidecloak/nextjs
+
+**What you see**: Import error on SDK package.
+
+**Diagnostic**:
+```bash
+cat package.json | grep tidecloak
+# Should show: "@tidecloak/nextjs": "..."
+```
+
+**Fix**:
+```bash
+npm install @tidecloak/nextjs
+```
+
+All `@tidecloak` packages are available on public npm registry.
+
+---
+
+## Symptom: Config Not Loading
+
+**What you see**: Provider fails to initialize, or auth-server-url / realm / clientId are undefined.
+
+**Diagnostic**:
+```bash
+# Check tidecloak.json exists at the correct path
+test -f data/tidecloak.json && echo "Found" || echo "MISSING — export from TideCloak admin"
+
+# Check it has required Tide fields
+node -e "const c=require('./data/tidecloak.json'); console.log('realm:', c.realm, 'url:', c['auth-server-url'], 'jwk:', !!c.jwk)"
+
+# Check provider imports it
+grep "tidecloak.json" app/providers.tsx src/app/providers.tsx 2>/dev/null
+```
+
+**Fix**: The app should load config from `data/tidecloak.json`, not from `NEXT_PUBLIC_TIDECLOAK_*` env vars. If `providers.tsx` uses env vars instead of importing the JSON file, replace with:
+```typescript
+import tcConfig from '../../data/tidecloak.json';
+// ...
+<TideCloakProvider config={tcConfig}>
+```
+
+Do not create `NEXT_PUBLIC_TIDECLOAK_URL`, `NEXT_PUBLIC_TIDECLOAK_REALM`, `NEXT_PUBLIC_TIDECLOAK_CLIENT_ID`, or `NEXT_PUBLIC_TIDECLOAK_REDIRECT_URI` env vars. These values are in `tidecloak.json`.
+
+---
+
+## Symptom: Silent Refresh Fails
+
+**What you see**: User logged out after 10 minutes.
+
+**Diagnostic**:
+```bash
+# Check silent SSO file
+curl http://localhost:3000/silent-check-sso.html
+# Should return HTML
+
+# Check browser console for 404
+# DevTools → Console → Filter: silent-check-sso
+```
+
+**Fix**: Create `public/silent-check-sso.html`. See [add-auth-nextjs-fresh.md Step 5](add-auth-nextjs-fresh.md#step-5-create-silent-sso-file).
+
+**Full guide**: [canon/troubleshooting.md T-04](../canon/troubleshooting.md#t-04-silent-token-refresh-fails).
+
+---
+
+## Symptom: Infinite Redirect Loop
+
+**What you see**: Page redirects to login, login redirects to page, repeat forever.
+
+**Diagnostic**: Check if login page has auth guard.
+
+**Fix**: Remove auth guard from login/public pages:
+```typescript
+// app/login/page.tsx
+export default function LoginPage() {
+  // NO AuthGuard here
+  return <div>Login</div>;
+}
+```
+
+---
+
+## Symptom: CORS Errors
+
+**What you see**: Browser console: "CORS policy: No 'Access-Control-Allow-Origin'".
+
+**Diagnostic**: Check TideCloak client Web Origins.
+
+**Fix**:
+1. TideCloak Admin → Clients → {client} → Settings
+2. Web Origins: Add `http://localhost:3000` and `https://app.example.com`
+3. Save
+
+---
+
+## Quick Diagnostic Checklist
+
+Run these in order:
+
+- [ ] TideCloak reachable: `curl ${TIDECLOAK_URL}/.well-known/openid-configuration`
+- [ ] Adapter config filename is `tidecloak.json` (not `adapter.json` or `keycloak.json`)
+- [ ] Adapter config at correct location: `data/tidecloak.json` (Next.js) or `public/tidecloak.json` (React/Vite/Vanilla)
+- [ ] Adapter JSON valid: `jq 'has("jwk") and has("vendorId") and has("homeOrkUrl")' data/tidecloak.json`
+- [ ] Env vars set: `cat .env.local | grep NEXT_PUBLIC`
+- [ ] CSP configured: `curl -I http://localhost:3000 | grep CSP`
+- [ ] Silent SSO file: `curl http://localhost:3000/silent-check-sso.html`
+- [ ] Redirect handler exists at configured redirectUri path
+- [ ] Browser console clean (no errors)
+
+---
+
+## References
+
+- [canon/troubleshooting.md](../canon/troubleshooting.md) - Complete troubleshooting
+- [add-auth-nextjs-fresh.md](add-auth-nextjs-fresh.md) - Setup checklist

package/playbooks/diagnose-missing-roles-or-claims.md

@@ -0,0 +1,253 @@
+# Diagnose Missing Roles or Claims
+
+Troubleshoot missing or incorrect JWT claims.
+
+---
+
+## Pre-Check: Is There a Real JWT?
+
+Before inspecting claims, confirm the app is using real Tide JWTs, not fake auth:
+
+```bash
+# Check for fake/hardcoded tokens
+grep -r "auth_token\|fake.*token\|hardcoded\|FAKE_USERS" lib/ app/ --include="*.ts" --include="*.tsx"
+# If matches: the app is using fake auth, not Tide. Fix the auth system first.
+
+# Check for cookie-based auth instead of JWT
+grep -r "cookies.*auth\|cookie.*token" app/api/ --include="*.ts"
+# If matches: API reads auth from cookies, not Authorization header. See protect-api-nextjs.md.
+```
+
+If the app has no real Tide integration (no `@tidecloak/nextjs` in package.json, no `TideCloakProvider` in layout), stop. Complete [add-auth-nextjs-fresh.md](add-auth-nextjs-fresh.md) first. Role diagnostics only apply to apps with working Tide auth.
+
+---
+
+## Symptom: Role Check Always Fails
+
+**What you see**: `hasRealmRole('admin')` returns false even for admin users.
+
+**Diagnostic steps**:
+
+### Step 1: Check JWT Contents
+
+```typescript
+// Client-side
+const { getValueFromToken, getValueFromIdToken } = useTideCloak();
+console.log('User sub:', getValueFromToken("sub"));
+console.log('Realm roles:', getValueFromToken("realm_access")?.roles);
+console.log('Resource access:', getValueFromToken("resource_access"));
+```
+
+Or decode JWT manually:
+```bash
+# Get token from browser DevTools → Application → Local Storage
+# Paste at jwt.io to decode
+```
+
+### Step 2: Verify Role Name
+
+Common mismatches:
+- Looking for `'admin'` but role is `'realm-admin'`
+- Case sensitivity: `'Admin'` vs `'admin'`
+- Client role vs realm role
+
+```typescript
+// Check both realm and client roles
+function hasAnyRole(user: any, role: string): boolean {
+  // Realm roles
+  const realmRoles = user?.realm_access?.roles || [];
+  if (realmRoles.includes(role)) return true;
+
+  // Client roles
+  const resourceAccess = user?.resource_access || {};
+  for (const client of Object.values(resourceAccess)) {
+    const clientRoles = (client as any)?.roles || [];
+    if (clientRoles.includes(role)) return true;
+  }
+
+  return false;
+}
+```
+
+---
+
+## Symptom: User Has No Roles
+
+**What you see**: `getValueFromToken("realm_access")?.roles` is empty array or undefined.
+
+**Diagnostic**:
+
+```bash
+# Check user in TideCloak Admin
+# Admin Console → Users → {user} → Role Mappings
+# Should show assigned roles
+```
+
+**Causes**:
+
+1. **Roles not assigned**: Assign in TideCloak Admin
+2. **IGA pending**: If IGA enabled, role assignment needs quorum approval
+3. **Default roles missing**: Realm missing default composite role
+
+**Fix (assign role)**:
+
+1. TideCloak Admin → Users → {user} → Role Mappings
+2. Assign role → {role-name}
+3. If IGA enabled: Approve change-set (requires quorum)
+4. User logout/login to get new token
+
+**Fix (default roles)**:
+
+1. TideCloak Admin → Realm Settings → User Registration → Default Roles
+2. Add a `_tide_*` role (e.g., `_tide_enabled`) and application default role
+3. New users auto-receive these roles
+
+---
+
+## Symptom: Custom Claim Missing
+
+**What you see**: `getValueFromToken("custom_field")` returns undefined.
+
+**Diagnostic**:
+
+Check if protocol mapper exists:
+
+```bash
+# TideCloak Admin → Client Scopes → roles → Mappers
+# Or: Clients → {client} → Client Scopes → roles → Mappers
+```
+
+**Fix (add protocol mapper)**:
+
+1. Client Scopes → roles → Mappers → Create
+2. Mapper Type: "User Attribute"
+3. User Attribute: `customField` (user attribute name)
+4. Token Claim Name: `custom_field` (claim name in JWT)
+5. Claim JSON Type: String
+6. Add to ID token: ON
+7. Add to access token: ON
+8. Save
+
+**Fix (set user attribute)**:
+
+1. Users → {user} → Attributes
+2. Key: `customField`, Value: `some-value`
+3. Save
+
+User must logout/login to get updated token.
+
+---
+
+## Symptom: `tideuserkey` or `vuid` Missing
+
+**What you see**: Tide-specific claims missing.
+
+**Cause**: Protocol mappers not configured or account not linked.
+
+**Diagnostic**:
+
+```bash
+# Check user attributes
+curl "${TIDECLOAK_URL}/admin/realms/${REALM}/users/${USER_ID}" | \
+  jq '.attributes | {tideUserKey, vuid}'
+# Should show values
+
+# Check protocol mappers
+curl "${TIDECLOAK_URL}/admin/realms/${REALM}/clients/${CLIENT_ID}/protocol-mappers/models" | \
+  jq '.[] | select(.name | contains("tide"))'
+```
+
+**Fix**: See [canon/troubleshooting.md T-07](../canon/troubleshooting.md#t-07-account-linking-stuck) for account linking.
+
+---
+
+## Symptom: Roles Change But Token Doesn't Update
+
+**What you see**: Assigned new role in TideCloak, but `getValueFromToken("realm_access")?.roles` still shows old values.
+
+**Cause**: Token cached. JWT claims frozen at issue time.
+
+**Fix**:
+
+```bash
+# User must logout/login to get fresh token
+```
+
+Or force refresh:
+
+```typescript
+// Client-side
+const { logout, login } = useTideCloak();
+
+async function forceTokenRefresh() {
+  await logout();
+  await login();
+}
+```
+
+---
+
+## Symptom: E2EE Role Not Working
+
+**What you see**: `doEncrypt('tag', data)` fails even though user has role.
+
+**Diagnostic**:
+
+```bash
+# Check exact role name
+# Should be: _tide_{tag}.selfencrypt
+# Not: _tide_encrypt or tide_{tag}
+```
+
+**Fix**:
+
+1. TideCloak Admin → Roles → Create Role
+2. Name: `_tide_ssn.selfencrypt` (exact pattern)
+3. Assign to user
+4. Create matching decrypt role: `_tide_ssn.selfdecrypt`
+5. User logout/login
+
+---
+
+## Quick Diagnostic Script
+
+```typescript
+// Add to app for debugging
+function debugAuth() {
+  const { authenticated, getValueFromToken, getValueFromIdToken } = useTideCloak();
+
+  console.log('=== Auth Debug ===');
+  console.log('Authenticated:', authenticated);
+  console.log('User sub:', getValueFromToken("sub"));
+  console.log('User name:', getValueFromIdToken("preferred_username"));
+  console.log('Realm roles:', getValueFromToken("realm_access")?.roles);
+  console.log('Resource access:', getValueFromToken("resource_access"));
+  console.log('Tide claims:', {
+    tideuserkey: getValueFromToken("tideuserkey"),
+    vuid: getValueFromToken("vuid")
+  });
+}
+
+// Call from browser console
+debugAuth();
+```
+
+---
+
+## Known Issues
+
+### `_tide_*` Role Required
+
+**Required for all Tide operations**: Every user must have at least one role starting with `_tide_` (e.g., `_tide_enabled`). This role assignment enables the Tide Voucher system to fund user operations.
+
+**Why**: The Vendor uses the `_tide_*` role to verify the user is Tide-enabled before assigning Vouchers. Without this role, Tide-related requests (including authorization) will be rejected.
+
+**Fix**: Add a `_tide_*` role to realm default roles. Common convention: `_tide_enabled`.
+
+---
+
+## References
+
+- [add-rbac-nextjs.md](add-rbac-nextjs.md) - RBAC implementation
+- [canon/troubleshooting.md T-07](../canon/troubleshooting.md#t-07-account-linking-stuck) - Account linking
+- [canon/concepts.md#tag-based-e2ee-roles](../canon/concepts.md#tag-based-e2ee-roles) - E2EE roles