@tideorg/mcp 1.4.0

package/skills/tide-learning-capture/SKILL.md

@@ -0,0 +1,174 @@
+# Role: Learning Capture
+
+---
+
+## Purpose
+
+Convert raw session findings into structured pack learnings, refinement backlog entries, and pack update candidates. This skill closes the feedback loop: real-world build failures become pack improvements.
+
+---
+
+## Boundary
+
+| This skill owns | Does NOT own |
+|----------------|-------------|
+| Formatting raw findings into L-## entries | Deciding whether to apply the fix |
+| Creating RB-### backlog entries | Applying patches to canon/playbooks/skills |
+| Creating PUC-### update candidates | Reviewing or accepting implementations |
+| Assigning severity and affected layer | Running evals or regression tests |
+| Detecting duplicates against existing learnings | Changing MCP server code |
+
+This skill captures and structures. It does not patch. Hand the structured output to the appropriate specialist or reteach pass.
+
+---
+
+## When to Trigger
+
+- After a build session where something went wrong or behaved unexpectedly
+- After a reviewer flags an issue that is not yet in the pack
+- When raw notes exist but are not yet in the standard format
+- When the user says "capture this", "log this finding", or "reteach"
+
+---
+
+## When NOT to Trigger
+
+- For app-specific bugs that do not affect pack guidance
+- For issues already captured in an existing LEARNINGS file (check first)
+- For fixes that are already PATCHED in the refinement backlog
+
+---
+
+## Inputs
+
+The skill accepts one or more raw findings. Each finding must include:
+
+1. **What happened** — the observed behavior
+2. **What should have happened** — the expected behavior
+3. **Where it happened** — which playbook, skill, scenario, canon file, or template was involved
+
+Optional but valuable:
+- Error messages or logs
+- The user request that triggered the issue
+- Which MCP tool or scenario was in use
+
+---
+
+## Output Format
+
+### Step 1: LEARNINGS entry (L-##)
+
+Write to `notes/test-findings/LEARNINGS-<batch-name>.md`. Use the next available L-## number within that file.
+
+Each entry follows this exact structure:
+
+```markdown
+## L-##: <short title>
+
+**Finding**: <what happened and what the agent or user observed>
+
+**Root cause**: <why it happened — which pack artifact gave wrong guidance, or what was missing>
+
+**Proposed fix (pack layer)**: <which file(s) to change and what the change should be>
+
+**Scenario affected**: <which scenario(s) or "all scenarios">
+
+**Regression test**: <how to verify the fix works — ideally a concrete check>
+```
+
+Rules:
+- If the finding is app-specific and does not affect pack guidance, mark it `**Status**: App-specific. Not a pack issue.` and stop. Do not create RB or PUC entries.
+- If the finding duplicates an existing learning, reference it instead: `**Status**: Duplicate of LEARNINGS-batch-007 L-03. No new entry needed.`
+
+### Step 2: Refinement backlog entry (RB-###)
+
+Append one row to `notes/refinement-backlog.md`. Use the next available RB-### number.
+
+Format:
+
+```
+| RB-### | <issue summary> | <LEARNINGS file> L-##: <evidence> | <file(s) to patch> | <severity> | OPEN | <eval ID or "—"> |
+```
+
+Severity levels:
+- **HIGH** — agent produces broken or insecure output
+- **MEDIUM** — agent produces suboptimal output or user must manually correct
+- **LOW** — cosmetic, documentation, or edge case
+
+### Step 3: Pack update candidate (PUC-###)
+
+Append to `notes/pack-update-candidates.md`. Use the next available PUC-### number.
+
+Format:
+
+```markdown
+## PUC-###: <short title> (RB-###)
+
+**Change**: <what to change, in one sentence>
+
+**Files**:
+- <file path 1>
+- <file path 2>
+
+**Why this layer**: <why this is the right file to patch, not a different one>
+
+**MCP**: <"No MCP code change needed" or describe the MCP change>
+```
+
+---
+
+## Duplicate Detection
+
+Before creating any new entry, check:
+
+1. Scan existing `notes/test-findings/LEARNINGS*.md` files for similar root causes
+2. Scan `notes/refinement-backlog.md` for matching RB entries
+3. If a match exists and is PATCHED, check whether this is a regression (same issue returned) or a new variant
+
+If duplicate: reference the existing entry and note whether it's a confirmed regression or a false alarm.
+
+---
+
+## Numbering
+
+- **L-## numbers** are scoped per LEARNINGS file. Each file starts at L-01.
+- **RB-### numbers** are global across the refinement backlog. Continue from the highest existing number.
+- **PUC-### numbers** are global across pack-update-candidates. Continue from the highest existing number.
+
+To find the next number, read the tail of the respective file.
+
+---
+
+## Batch Naming
+
+Name the LEARNINGS file based on context:
+- Session-based: `LEARNINGS-session-###.md` (for interactive build sessions)
+- Batch-based: `LEARNINGS-batch-###.md` (for eval runs or bulk testing)
+- Project-based: `<project>-learnings-batch-####.md` (for findings from a specific external project)
+
+---
+
+## Anti-Patterns
+
+- **Do not create learnings for things that work correctly.** Only capture deviations.
+- **Do not propose fixes outside the pack.** If the issue is in the SDK or TideCloak itself, note it as `**Status**: SDK/platform issue. Outside pack scope.` and stop after the L-## entry.
+- **Do not combine multiple root causes into one entry.** If one session surfaced three issues, create three separate L-## entries, three RB rows, and three PUC sections.
+- **Do not mark severity based on frequency.** A rare issue that produces insecure output is HIGH. A common issue that produces a cosmetic glitch is LOW.
+- **Do not skip the duplicate check.** The most common waste is re-capturing something already patched.
+
+---
+
+## Handoff Trace
+
+The skill emits a `[CAPTURE]` block when complete:
+
+```
+[CAPTURE]
+Batch: <LEARNINGS file name>
+Entries: L-01 through L-##
+Backlog: RB-### through RB-###
+Candidates: PUC-### through PUC-###
+Duplicates skipped: <count or "none">
+Next: reteach pass to apply PUC entries, or manual review
+[/CAPTURE]
+```

package/skills/tide-rbac-and-e2ee/SKILL.md

@@ -0,0 +1,214 @@
+# Role: IAM / Policy Engineer
+
+---
+
+## Purpose
+
+Add role-based access control to protected APIs using verified JWT claims. Optionally add self-encryption (user-bound E2EE) using Tide's tag-based role system. Both features require prior auth + API protection.
+
+---
+
+## When to Trigger
+
+- User asks to "add roles", "add RBAC", "add permissions", or "add access levels"
+- User asks to "encrypt data", "add E2EE", or "add field-level encryption" — **but first check the sharing gate below**
+- User asks about `_tide_*` roles or tag-based encryption roles
+- Agent detects API routes that verify JWT but do not check roles
+
+### Scenario-disambiguation gate (I-17)
+
+Before starting encryption or RBAC work, resolve these branches:
+
+| Branch | How to resolve |
+|--------|---------------|
+| Self-encryption vs shared encryption | Does anyone other than the encrypting user need to decrypt? If yes → `setup-forseti-e2ee`, not this skill. |
+| Simple RBAC vs policy governance | Does the app need multi-admin approval, IGA change-sets, or Forseti contracts? If yes → `setup-forseti-e2ee` or `setup-iga-admin-panel`. |
+| RBAC only vs RBAC + E2EE | Does the user need encryption at all, or just role-based access control? |
+
+**Mandatory sharing gate** (instance of I-17 for encryption):
+
+If the user's request mentions ANY of the following, **STOP** and route to playbook `setup-forseti-e2ee` instead of this skill:
+- "share", "sharing", "shared"
+- "other users can decrypt", "recipients", "chosen people"
+- "cross-user", "multi-user", "group encryption"
+- "encrypt for others", "selective access"
+- any indication that someone other than the encrypting user needs to decrypt
+
+Self-encryption (this skill) is **permanently user-bound**. It cannot be upgraded to shared encryption later. The SDK call path must be different from the start (`IAMService.doEncrypt(data, policyBytes)` instead of `doEncrypt`/`doDecrypt`). Building self-encryption first and trying to add sharing is a known failure mode (AP-24, session-001).
+
+---
+
+## When NOT to Trigger
+
+- App is not Tide-enabled. Route to `tide-setup` skill.
+- API routes do not verify JWT yet. Route to `tide-route-and-api-protection` skill first. RBAC on unverified tokens is meaningless.
+- User needs shared/group encryption (policy-governed VVK encryption with Forseti contracts). That is covered by playbook `setup-forseti-e2ee`, not this skill. This skill covers self-encryption only.
+- User asks about Keycloak-to-TideCloak migration. Not yet documented (GAP-023).
+
+**Early sharing detection**: If the user request mentions any of: "sharing", "share encrypted", "chosen recipients", "other users can decrypt", "cross-user decryption", "encrypt for others", "selective sharing" — route directly to `setup-forseti-e2ee`. Do NOT start with self-encryption and attempt to add sharing later. Self-encryption cannot be upgraded to shared encryption by renaming roles or changing parameters. The SDK call path must be different from the start. VERIFIED (session-001, F-07).
+
+---
+
+## Required Repo Inspection
+
+```bash
+# 1. Confirm API protection exists (hard prerequisite)
+ls lib/auth/tideJWT.ts lib/auth/protect.ts lib/auth/tidecloakConfig.ts 2>/dev/null
+# ALL three must exist. If any is missing, complete tide-route-and-api-protection first.
+
+# 2. Check jose is installed
+grep '"jose"' package.json
+
+# 3. Check existing role usage
+grep -r 'hasRole\|withRole\|realm_access\|resource_access' app/api/ lib/auth/ --include="*.ts" 2>/dev/null
+
+# 4. Check for E2EE usage
+grep -r 'doEncrypt\|doDecrypt' app/ components/ --include="*.tsx" --include="*.ts" 2>/dev/null
+
+# 5. Check for _tide_* role references
+grep -r '_tide_' app/ components/ lib/ --include="*.ts" --include="*.tsx" 2>/dev/null
+```
+
+If check 1 fails, stop. The `tide-route-and-api-protection` skill must be completed first.
+
+---
+
+## Preconditions
+
+- Tide setup complete (SDK, provider, adapter JSON)
+- Login working
+- Server-side JWT verification implemented (`lib/auth/tideJWT.ts` with `verifyTideJWT()` and `hasRole()`)
+- Auth middleware implemented (`lib/auth/protect.ts` with `withAuth()` and `withRole()`)
+- Roles created in TideCloak Admin Console and assigned to users (via IGA if enabled)
+
+---
+
+## Execution Workflow
+
+### Part 1: Server-Side RBAC
+
+**Playbook**: `add-rbac-nextjs`
+
+Follow the playbook to apply `withRole()` to API routes and optionally add client-side `hasRealmRole()` / `hasClientRole()` for UI gating.
+
+**Key facts** (not repeated from playbook — these are pitfalls the playbook assumes you know):
+
+- Roles live in `realm_access.roles` (realm) and `resource_access.{client}.roles` (client). The server-side `hasRole()` utility from `verify-jwt-server-side` checks both.
+- The client SDK hook exports `hasRealmRole(role)` and `hasClientRole(role, client?)`. There is no generic `hasRole()` on the hook.
+- `tide-realm-admin` is a **client role** on `realm-management`, not a realm role. Use `hasClientRole('tide-realm-admin', 'realm-management')`, not `hasRealmRole('tide-realm-admin')`. (AP-29)
+- Client-side `hasRealmRole()` / `hasClientRole()` from `useTideCloak()` is UX only — the API still enforces server-side.
+
+### Part 2: Self-Encryption (E2EE) — private data only, NO sharing
+
+**STOP CHECK**: Did the user's request mention sharing, recipients, or multiple users decrypting? If yes, do NOT proceed. Route to `setup-forseti-e2ee` immediately. Self-encryption CANNOT be shared. This is not fixable by renaming roles.
+
+Self-encryption is user-bound. Only the encrypting user can decrypt their own data. For shared encryption between users, use policy-governed VVK encryption instead (playbook `setup-forseti-e2ee`).
+
+**Playbook**: `add-rbac-nextjs` (E2EE section) covers the implementation steps: creating `_tide_{tag}.selfencrypt` / `_tide_{tag}.selfdecrypt` roles, calling `doEncrypt` / `doDecrypt`, and storing ciphertext.
+
+**Prerequisites for E2EE** (verify before starting):
+- IGA enabled on the realm (adapter JSON must have `jwk` field)
+- Tag roles created and assigned to users in TideCloak
+- Users have at least one `_tide_*` role for voucher gating
+
+**Key facts not in the playbook**:
+- Tags are fully application-defined, case-sensitive, max ~237 chars. See `canon/feature-mapping.md`.
+- The server stores ciphertext only. It cannot decrypt — decryption requires live Fabric threshold participation in the user's browser.
+- Use `TEXT` or `BYTEA` DB columns. `VARCHAR(512)` covers plaintexts up to ~150 bytes after base64 overhead.
+
+---
+
+## Safety Checks
+
+- **Do not mix `_tide_*` roles with app roles.** `_tide_ssn.selfencrypt` is for E2EE voucher gating, not for granting admin access.
+- **Self-encryption is NOT shared encryption.** Only the encrypting user can decrypt. For shared data, use Forseti-governed VVK encryption (playbook `setup-forseti-e2ee`).
+- **Do not rename roles to enable sharing.** Changing `selfencrypt` → `encrypt` in role names does not switch encryption models. The SDK call path determines self vs shared. See AP-26 in `canon/anti-patterns.md`.
+- **E2EE requires online Fabric access.** No offline decryption. No server-side decryption. Do not cache session keys. (I-11, AP-04)
+- **Do not invent E2EE patterns** not covered by `canon/feature-mapping.md` or the `add-rbac-nextjs` playbook.
+- **Token refresh delay**: After IGA role assignment, roles appear in JWT/doken after next token refresh (up to 120s).
+
+---
+
+## Verification Checklist
+
+### RBAC
+- [ ] API with `withRole('admin')` returns 403 for non-admin user
+- [ ] API with `withRole('admin')` returns 200 for admin user
+- [ ] Client-side `hasRole('admin')` shows correct UI for each role
+- [ ] Composite roles (if used) propagate permissions correctly
+- [ ] Bypassing UI (direct curl) still enforces role server-side
+
+### Self-Encryption (if applicable)
+- [ ] `doEncrypt('tag', data)` succeeds for user with `_tide_{tag}.selfencrypt` role
+- [ ] `doDecrypt('tag', ciphertext)` returns original data for same user
+- [ ] `doEncrypt` fails for user without the selfencrypt role
+- [ ] `doDecrypt` by a different user fails (expected behavior — self-encryption is user-bound; A-27 INFERRED, not runtime-confirmed)
+- [ ] Ciphertext stored in DB is not plaintext
+
+---
+
+## Repair Path
+
+### Role always missing (403 for everyone)
+1. Decode JWT: `node -e "console.log(JSON.parse(atob('TOKEN_PAYLOAD_PART')))"` — check `realm_access.roles`
+2. Verify role exists in TideCloak Admin Console → Roles
+3. Verify role is assigned to user → Users → Role Mappings
+4. If IGA is enabled, verify the role assignment change-set was approved and committed
+5. Wait up to 120s or force token refresh (logout/login)
+6. See playbook `diagnose-missing-roles-or-claims`
+
+### E2EE fails with "User has not been given any access"
+
+**This is a self-encryption setup problem.** Do not rename roles or switch encryption models.
+
+1. Check user has `_tide_{tag}.selfencrypt` or `_tide_{tag}.selfdecrypt` role
+2. Check user has at least one `_tide_*` role for voucher gating
+3. Check tag name matches exactly (case-sensitive)
+4. Check adapter JSON has `jwk` field (IGA must be enabled)
+5. Check IGA change requests for roles are approved and committed
+6. User must re-login after role assignment (up to 120s propagation delay)
+
+**Forbidden response**: Do not rename `_tide_{tag}.selfencrypt` to `_tide_{tag}.encrypt`. The role suffix does not change the encryption model. See AP-26 and T-13.
+
+**If the user actually needs cross-user decryptability**: This is a different encryption model. Route to playbook `setup-forseti-e2ee`. It requires a Forseti contract, policy signing, and `IAMService.doEncrypt(data, signedPolicyBytes)`. Do not attempt this by renaming roles.
+
+### E2EE ciphertext is undefined or empty
+1. Check Fabric connectivity (SWE iframe loads, no CSP errors)
+2. Check browser console for ORK errors
+3. Ensure `doEncrypt` is called after user is authenticated
+
+### Policy commit fails with "Policy supplied has not been signed"
+
+This is a policy-flow failure, not a role issue. See T-14.
+
+1. Check admin policy was fetched from `GET /realms/{realm}/tide-policy-resources/admin-policy`
+2. Check admin policy bytes were base64-decoded before use
+3. Check `addPolicy(adminPolicyBytes)` was called after approval, not during request construction
+4. Check URL construction has no double slashes (strip trailing slash from `auth-server-url`)
+
+---
+
+## Handoff Trace
+
+```
+[TRACE]
+Scenario: <scenario>
+Role: IAM / Policy Engineer
+Reason: <RBAC needed | self-encryption needed | shared encryption needed>
+Preconditions: JWT verification exists (lib/auth/tideJWT.ts), sharing gate resolved
+Next: Reviewer / QA Engineer | STOP
+[/TRACE]
+```
+
+---
+
+## Do Not Do This
+
+- **Do not implement RBAC without prior JWT verification.** Role checks on unverified tokens are meaningless.
+- **Do not use `_tide_*` roles for application permissions.** They are for E2EE voucher gating. Use separate realm or client roles for app-level access control.
+- **Do not implement offline decryption** or cache decrypted session keys. (AP-04)
+- **Do not use self-encryption for data that multiple users need to access.** Use policy-governed VVK encryption with a Forseti contract instead. (AP-24 in canon/anti-patterns.md)
+- **Do not assume E2EE is available without IGA.** The `jwk` field (required for E2EE) is only in the adapter JSON when IGA is enabled.
+- **Do not store decrypted data server-side.** The whole point of Tide E2EE is that plaintext exists only in the user's browser.
+- **Do not rename `selfencrypt`/`selfdecrypt` to `encrypt`/`decrypt` to "fix" encryption failures or enable sharing.** The role suffix is a naming convention. The SDK call path determines the encryption model. See AP-26.
+- **Do not treat policy commit failure as a role issue.** Missing admin policy on commit is a bootstrap/policy-flow failure. See T-14.

package/skills/tide-reviewer/SKILL.md

@@ -0,0 +1,133 @@
+# Role: Reviewer / QA Engineer
+
+---
+
+## Purpose
+
+Check implementation work against pack doctrine, security invariants, scenario correctness, and anti-patterns. The Reviewer is a compliance/sanity/security gate — not a second builder.
+
+---
+
+## Boundary
+
+| This subagent owns | Does NOT own |
+|-------------------|-------------|
+| Compliance checking against canon/invariants | Writing new features |
+| Scenario correctness verification | Performing setup or bootstrap |
+| Security invariant validation | Fixing detected issues (hand back to the responsible subagent) |
+| Anti-pattern detection | Broad refactoring or rewrites |
+| Stale convention detection | Playbook execution |
+| Accept / warn / reject decisions | Final user-facing output |
+
+The Reviewer detects problems. It does not fix them. When it finds an issue, it reports the issue and names the subagent that should fix it.
+
+---
+
+## When to Trigger
+
+- After a major build or scaffold pass (Setup + Integration + Protection)
+- After auth/bootstrap setup completes
+- After route/API protection work completes
+- After RBAC/E2EE work completes
+- Before final handoff to the user
+- Before writing learnings back into the pack
+- When the orchestrator wants a compliance gate before proceeding
+
+The Reviewer is optional per-step but **mandatory before handing the app to the user**. No implementation is delivered without a review pass. If the Reviewer rejects, the named specialist fixes the issue, then the Reviewer runs again.
+
+---
+
+## When NOT to Trigger
+
+- During initial planning or routing (that is the orchestrator's job)
+- As a replacement for running a subagent (the Reviewer reviews, it does not build)
+- On trivial single-file changes that don't touch auth, config, or security
+
+---
+
+## What the Reviewer Checks
+
+### Scenario correctness
+- [ ] Was a scenario match attempted before building? (I-17)
+- [ ] If a scenario matched, was its manifest used for roles/policies/playbooks?
+- [ ] Was scenario ambiguity resolved before action, not after?
+- [ ] If no scenario matched, was generic routing used correctly?
+
+### Setup/bootstrap compliance
+- [ ] Was bootstrap completed before integration? (I-18 ordering)
+- [ ] Does the realm template include all required sections? (tidecloak-bootstrap canon)
+- [ ] Is `tidecloak.json` present with `jwk`, `vendorId`, `homeOrkUrl`?
+- [ ] Are master admin credentials absent from generated app code? (AP-41)
+- [ ] Was the init-script path used when available?
+
+### Integration compliance
+- [ ] Is `useDPoP` inside the config object, not as a JSX prop? (AP-42, session-002)
+- [ ] Does `next.config.ts` have `strictExportPresence = false`? (not `reexportExportsPresence`)
+- [ ] Does `next.config.ts` have the `@tidecloak/react` ESM alias? (AP-42)
+- [ ] Does `public/tide_dpop_auth.html` exist? (I-12, L-07)
+- [ ] Does `next.config.ts` have `rewrites()` for `/tide_dpop/:path*` and DPoP-specific `headers()` with `script-src 'unsafe-inline'`? (I-12)
+- [ ] Does `public/silent-check-sso.html` exist? (I-07)
+- [ ] Does the redirect handler exist at the configured `redirectUri`? (I-16)
+- [ ] Is CSP set to `frame-src '*'`? (I-06)
+
+### Protection compliance
+- [ ] Do protected APIs verify JWT server-side? (I-03)
+- [ ] Is `createLocalJWKSet(config.jwk)` used, not `createRemoteJWKSet`? (I-04)
+- [ ] Is DPoP enforced when `cnf.jkt` is present in the token?
+- [ ] Are `hasRealmRole()` / `hasClientRole()` used only for UI gating, not API auth? (I-08)
+
+### RBAC/E2EE compliance
+- [ ] If sharing was requested, was policy-governed encryption used (not self-encryption)? (AP-24)
+- [ ] Were roles NOT renamed to enable sharing? (AP-26)
+- [ ] Is `hasClientRole('tide-realm-admin', 'realm-management')` used for admin checks, not `hasRealmRole`? (AP-29)
+- [ ] If shared encryption: does an admin signing page/flow exist? Is shared mode gated on signed policy?
+- [ ] No silent fallback from shared to self-encryption?
+
+### Config artifact compliance
+- [ ] Is the adapter file named `tidecloak.json` (not `adapter.json` or `keycloak.json`)?
+- [ ] Is it at the correct path (`data/` for Next.js, `public/` for React/Vite)?
+- [ ] Are no `NEXT_PUBLIC_TIDECLOAK_*` env vars created? (AP-38)
+- [ ] Does the provider load config from `tidecloak.json`, not env vars?
+
+### Stale convention detection
+- [ ] No `reexportExportsPresence` in webpack config (invalid property)
+- [ ] No `require.resolve()` for `@tidecloak/react` alias (throws ERR_PACKAGE_PATH_NOT_EXPORTED)
+- [ ] No `middleware.ts` on Next.js 16+ (should be `proxy.ts`)
+- [ ] No `hasRole()` from the SDK hook (should be `hasRealmRole` / `hasClientRole`)
+- [ ] No `tidecloak-oidc-keycloak-json` provider ID (does not exist)
+
+---
+
+## Conclusions
+
+The Reviewer must conclude with one of:
+
+| Conclusion | Meaning | Action |
+|-----------|---------|--------|
+| **ACCEPT** | All checks pass. No issues found. | Proceed to handoff. |
+| **ACCEPT_WITH_WARNINGS** | Minor issues found that do not block functionality. | List warnings. Proceed with awareness. |
+| **REJECT_AND_REROUTE** | Critical issue found. Name the subagent that must fix it. | Do not proceed. Route back to the named subagent. |
+
+---
+
+## Handoff Trace
+
+The Reviewer emits a `[REVIEW]` block instead of a `[TRACE]`:
+```
+[REVIEW]
+Verdict: ACCEPT | ACCEPT_WITH_WARNINGS | REJECT_AND_REROUTE
+Reason: <short reason>
+Violations: <list or "none">
+Next: <specialist to fix or "handoff to user">
+[/REVIEW]
+```
+
+---
+
+## Do Not Do This
+
+- Do not fix issues yourself. Report them and name the responsible subagent.
+- Do not become a second builder. Your job is to check, not to code.
+- Do not perform broad rewrites. Flag specific violations.
+- Do not promote app-specific workarounds into doctrine.
+- Do not review areas outside your checklist unless specifically asked.