feat(THU-556): Settings → Workspace → Permissions page + resource-CRUD enforcement

[raivieiraadriano92]

Summary

Ships PR 8 of the Workspaces v1 plan — the Permissions page under Settings → Workspace, plus end-to-end FE/BE enforcement of those permissions for add/remove × agents / skills / models / mcp_servers (8 keys). Soft-delete (PATCH deleted_at) is correctly classified as a remove. Stacked on top of #974 (THU-555, Members page); base will move to main once #974 merges.

Spec called for an 11-row grid; mid-task the surface was narrowed to the 4 resource CRUD pairs (the spec's other keys stay in the enum, stored-only — see Out of scope below).

What this PR does

• Shared (shared/workspaces.ts) — single source of truth for workspacePermissionKeys, WorkspacePermissionKey/Role types, isWorkspacePermissionKey narrowing, and permissionAllows(userRole, requiredRole) so FE + BE agree on satisfiability.
• Frontend
  • DAL: setWorkspacePermissionRequiredRole (UPSERT — works without the seeded row), useWorkspacePermissionsQuery reactive hook.
  • Permissions page at /w/<id>/settings/workspace/permissions — card+table with 8 rows (Add/Remove × Agents/Skills/Models/MCPs); role selector ("Admin" / "Everyone"). Loads, mutates, persists via PowerSync — no separate save button.
  • RequireWorkspaceAdmin route guard (sibling to RequireWorkspacePermission): admin-only, personal-workspace + E2EE gated. Branch order: personal → e2ee → loading → !admin → render.
  • Sidebar: new "Permissions" entry (Lock icon) between Members and Models, gated on admin + non-personal + non-E2EE.
  • Affordance gating across 4 resource surfaces — every Add/Edit/Remove/Toggle that PATCHes the row now consults useWorkspacePermission:
    • Models page: header +, empty-state Add, row Switch, row Edit (Pen), row Delete (Trash), ModificationIndicator reset.
    • MCP Servers page: header +, empty-state Add, row Switch, row Trash (Popover).
    • Agents page: header Add Custom Agent; AgentRow Switch + Trash threaded via canEditAgents / canRemoveAgents props.
    • Skills: SkillsList Create button; LibraryRow Switch + Edit/Delete menu items; SkillDetail Switch + Edit/Delete menu items; empty-panel "Create your first skill".
  • Chat-composer bypass gating — the chat input has its own write paths into skills / agents / models pickers; gated symmetrically:
    • ChatSkillsBar "Pin a skill" trigger hidden when !add_skills; pinned chips still render but SuggestionChip hides Reorder + Unpin.
    • ChatModelPicker "Add Models" footer suppressed when !add_models.
    • Header agent selector "Add Agent" footer also gated on add_agents (in addition to allowCustomAgents).
• Backend
  • DAL helpers: getUserRoleInWorkspace(tx, workspaceId, userId), getRequiredRoleForPermission(tx, workspaceId, key).
  • createWorkspaceScopedHandler extended with optional addPermissionKey / removePermissionKey / softDeleteColumn. New opIntent helper classifies PUT/PATCH(no deleted_at) as "add" and DELETE/PATCH(deleted_at set) as "remove" — gates each on the corresponding key, rejects with permanent / INSUFFICIENT_PERMISSION otherwise.
  • Registry entries for agents, skills, models, mcp_servers now pass all three options (deleted_at is the soft-delete column for all four).

Notable decisions

• Permissions page itself is hardcoded admin-only (RequireWorkspaceAdmin) rather than gated on the change_permissions key — making it configurable creates a self-escalation foot-gun (a member granted change_permissions=member could promote themselves further). The row stays in the enum for forward-compat.
• 'member' = "Everyone" in the UI — the underlying enum stays 'admin' | 'member', but the role picker shows "Admin" / "Everyone" since every workspace member satisfies a member requirement (admins satisfy it too).
• Soft-delete classified as a remove at the upload-handler layer, not via per-resource hacks. The four resource tables all soft-delete via PATCH deleted_at, so softDeleteColumn: 'deleted_at' on each registry entry routes that PATCH to removePermissionKey instead of addPermissionKey. Regular edits + restores stay on the add key.
• Edit gates on add_* (not a separate edit_* key) — toggling enabled, renaming a model, editing a skill all PATCH the row and gate on the resource's add key. Avoids exploding the permission surface.
• Shared permissionAllows predicate in shared/workspaces.ts — same satisfiability check on FE (useWorkspacePermission) and BE (createWorkspaceScopedHandler). Adding 'admin' always satisfies; 'member' is satisfied by both roles.
• useWorkspacePermission as a DI seam on each page-level component (ChatSkillsBar, ChatModelPicker, Header, AgentsSettingsPage, McpServersPage, ModelsPage) — matches the existing isStandalone?: () => boolean pattern, lets component-level tests assert "denied → affordance hidden" without seeding the DB.
• Pin/reorder/unpin from the chat composer route through add_skills since they PATCH the shared skills row (pinned_order). Future work could move pinning to a per-user store; for now the BE enforcement covers it.

Out of scope (stored-only keys)

The enum has 12 keys; only 8 are enforced today. The rest:

• manage_members — legacy; still backs the Members sidebar gate + route guard for the existing add/remove members flows. Effectively superseded by invite_users / remove_users once those are wired.
• join_workspace — no user-initiated "join" operation exists yet; reserved for a future invite-link / accept-invite flow.
• invite_users, change_roles, remove_users — Members page already gates on manage_members + change_roles directly (membership upload handlers hardcode isWorkspaceAdmin). These keys are stored but not consulted.
• change_general_settings — workspaces upload handler hardcodes isWorkspaceAdmin for renames/slug/icon. Stored but not consulted.
• change_permissions — Permissions page itself is hardcoded admin-only via RequireWorkspaceAdmin (see Notable decisions).
• delete_workspace — BE rejects all workspace DELETEs (WORKSPACE_DELETE_DISABLED). Stored but inert.

Wiring enforcement for any of these is a one-line registry change (workspace-scoped tables) or a getRequiredRoleForPermission + permissionAllows call (bespoke handlers). See the project memory note in this repo for the migration pattern.

Caveats

• Permissions for personal workspace are hidden entirely — Decision 25. Personal workspaces have no permission rows, no Permissions sidebar entry, and direct URL nav redirects.
• E2EE-enabled servers redirect away from the Permissions page (same as Members) — configuring member-management permissions is meaningless when nothing can be shared.
• Defensive UPSERT in setWorkspacePermissionRequiredRole — works on workspaces that pre-date THU-552's seed-defaults hook. If a row is somehow missing, the first write creates it.

Test plan

• Permissions page: admin in a shared workspace sees 8 rows defaulted to Admin; flipping add_agents/add_skills/add_models/add_mcp_servers to Everyone immediately reflects on the corresponding resource page; member can hit the URL → redirected.
• Sidebar: Permissions entry visible to admin only on shared workspaces; hidden on personal and on E2EE-enabled servers.
• Agents page: as member without add_agents, "Add Custom Agent" hidden, row Switch disabled, Trash hidden. Setting add_agents=member makes them appear; row PATCH lands on BE. Header agent-selector footer also follows.
• Skills page: same matrix — Create hidden, row Switch disabled, Edit/Delete menu items hidden, empty-panel "Create your first skill" hidden.
• Models page: header +, empty-state Add, row Switch, Edit (Pen), Delete (Trash), ModificationIndicator reset all gated.
• MCP servers page: same matrix — header +, empty-state Add, row Switch + Trash gated.
• Chat composer bypasses: + Pin a skill hidden when !add_skills; pinned chips still render but Reorder/Unpin are absent from the chip dropdown. Add Models footer hidden in the model picker. Add Agent footer hidden in the header's agent selector.
• BE soft-delete for each resource: PATCH {deleted_at: <iso>} from a member without remove permission is rejected with INSUFFICIENT_PERMISSION; granting the remove key allows it.
• BE edit PATCH (no deleted_at) for each resource: rejected on !add_* even if the remove key is granted.
• bun check (FE) + bun test (FE + BE) green.

Spec: https://github.com/thunderbird/thunderbolt-spec/pull/12
Addendum: Decision 10, Decision 11, Decision 25.

What's in the PR

17 commits, ordered for review:

Commit	Subject
1338e4a5	setWorkspacePermissionRequiredRole DAL
09c600fd	RequireWorkspaceAdmin route guard
6bd9b4dc	Consolidate workspace permission keys into shared/workspaces.ts
f23b18d4	Permissions page (11 keys, labels only)
c845030a	Permissions sidebar entry
f54e70b7	Mount Permissions route
796ebf66	Refine Permissions page copy and layout
0311c4fb	Scope Permissions to agents/skills/models/mcps
eccd544c	Use Lock icon for Permissions sidebar entry
aa9fde05	permissionAllows + BE permission lookup helpers
9f1f6afa	Permission-key gating in workspace-scoped handler
29f620b2	Enforce add_agents / remove_agents permissions
a9d368c2	Treat soft-delete PATCH as remove for permission gating
ab2c8a2a	Enforce add_skills / remove_skills permissions
bfb504cb	Enforce add_models / remove_models permissions
26119f09	Enforce add_mcp_servers / remove_mcp_servers permissions
967f8e96	Gate edit + chat bypasses, add permission gating tests

---

Note

High Risk
Changes authorization on membership/pending-invite uploads and resource writes, and broadens pending-invite sync visibility to all members—mistakes could allow privilege escalation or block legitimate admins.

Overview
Workspace permissions are centralized in shared/workspaces.ts (keys, roles, permissionAllows) and wired through FE useWorkspacePermission / BE callerSatisfiesPermission, defaulting missing policy rows to admin-only.

Backend upload auth moves membership and pending-invite writes from “workspace admin” to invite_users / change_roles / remove_users, with guards against admin escalation via invites or membership PUT upserts, last-admin protection on PUT, safer promote-on-insert (no role downgrade, delete pending by workspace+email), email validation, and server-truth invited_by_user_id. Agents, skills, models, and MCP servers use optional add_* / remove_* keys; PATCH setting deleted_at counts as remove.

Sync: workspace_pending_memberships syncs to all members (not an admin-only bucket) so permitted non-admins can see invites; writes stay handler-enforced.

Frontend adds the Permissions page (admin-only route), setWorkspacePermissionRequiredRole, and hides add/edit/remove affordances on settings pages and chat composer paths when the user lacks the matching key. Smaller fixes include Members route without manage_members guard, AppErrorBoundary, mode-picker stale validation, logout double-click guard, and clearAllKeys(serverId) after registry clear.

^{Reviewed by Cursor Bugbot for commit 24cc392. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Semgrep Security Scan

No security issues found.

[github-actions]

PR Metrics

Metric	Value
Lines changed (prod code)	+898 / -202
JS bundle size (gzipped)	🟡 733.1 KB → 746.9 KB (+13.7 KB, +1.9%)
Test coverage	🟡 77.63% → 76.85% (-0.8%)
Performance (preview)	Preview not ready — Render deploy may have timed out
Accessibility	—
Best Practices	—
SEO	—

Updated Fri, 12 Jun 2026 10:50:45 GMT · run #1874

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Reviewed by Cursor Bugbot for commit 24cc392. Configure here.}

[cursor]

Admin PUT wrongly needs change_roles

Medium Severity

For workspace_memberships PUTs that omit workspace_id and only target an existing row by op.id, validation treats any role: 'admin' payload as needing change_roles, even when the member is already an admin and the role does not change. The insert-or-update path correctly uses wouldMintNewAdmin only for new rows; this branch still uses targetsAdminRole alone, so callers with invite_users but not change_roles get INSUFFICIENT_PERMISSION on harmless re-upserts.

 

^{Reviewed by Cursor Bugbot for commit 24cc392. Configure here.}

[cursor]

FE duplicates permissionAllows logic

Low Severity

This PR adds shared permissionAllows in shared/workspaces.ts so frontend and backend use the same satisfiability rule, but useWorkspacePermission reimplements that predicate inline instead of calling permissionAllows. Future changes to role rules can update the shared helper while the hook stays wrong, hiding denied actions or showing ones the backend rejects.

 

^{Reviewed by Cursor Bugbot for commit 24cc392. Configure here.}