feat(authz): role-based access control, teams and org/auth surfaces

[melihsunbul]

What

Role-based access control (RBAC): roles and permissions, team management, organisations/principals, and the supporting authentication surfaces. This adds the authorisation primitives that every later feature PR guards against.

Concepts

• Principal — any actor a permission can be granted to (a team member, a portal user, or a team). It is the single subject type the authorisation layer reasons about.
• Role — a named bundle of granular permissions (for example "view tickets", "manage routing rules").
• Role assignment — binds a role to a principal, optionally scoped (workspace-wide or to a resource). Authorisation governs what a principal may do; it does not change who they are (role/identity stays gated behind invite or verified-domain provisioning).
• Team — a group that can own work (inboxes, tickets) and receive assignments; supports membership and archive/unarchive.
• Organisation — groups contacts/customers for B2B context and reporting.

How it works

• Domains — authz/ (permission catalogue and enforcement), roles/ (role and assignment services), teams/, organizations/, principals/, and server/policy/ (resolves the acting principal from the session).
• API — /api/v1/roles, /role-assignments, /permissions, /principals, /teams, /organizations (CRUD plus membership), with admin-authz-routes coverage.
• Server functions — authz, teams, principals, organizations, bootstrap, sso, recovery-codes, force-signout, auth-helpers, onboarding, status-sync.
• Authentication — server/auth/ email sign-in and contact linking (link-contact, widget-link-contact).
• UI — admin pages /admin/settings/roles, /admin/settings/teams (and a team detail page), /admin/settings/people, /admin/users; the components/admin/settings/team/ controls; and shared admin controls (components/admin/shared/: principal/resource/organisation/contact/inbox/status pickers, scope selector, route error boundary) used across the admin surface.
• Client — use-authz-queries, team query factories, shared team schemas.

How to use

• Define roles: Settings → Roles (/admin/settings/roles) — create a role and tick the permissions it grants.
• Assign roles: assign a role to a person or team from the people/team views; assignments are admin-only and audit-logged (see PR 03).
• Manage teams: Settings → Teams (/admin/settings/teams) — create teams, add members, archive when no longer needed.
• Group contacts: organisations are created/edited from the Customers area (PR 04) and referenced here for scoping.
• API: drive the same operations programmatically via /api/v1/roles, /role-assignments, /teams, /organizations.

Safety

• Permission guards are additive; existing admin/member capabilities are preserved. Role assignment stays gated behind admin-only flows and is audit-logged.
• The shared admin controls are introduced here because several later PRs consume them; they carry no feature behaviour of their own.

Verification

• bun run typecheck, bun run lint; unit tests for authz, teams, principals, recovery-codes, policy-actor resolution and the admin authz routes (included).

Depends on 01-data-model-foundation.

---

📚 This is a stacked series — please review & merge in order

These 10 PRs are split by concern and ordered by dependency. Each is opened against main, so until the PRs before it have merged, a PR's diff is cumulative (it also contains the earlier batches). As the earlier PRs merge and we rebase the next branch onto main, each diff reduces to just its own batch. Merging all 10 in order reproduces our integrated branch exactly (verified: the cumulative tip of the series is byte-identical to it).

Order (by branch):

1. 01-data-model-foundation — data model, TypeIDs, migrations
2. 02-rbac-authz-teams — RBAC, teams, organisation & auth surfaces
3. 03-events-audit-webhooks — event dispatch, audit log, webhooks, notifications
4. 04-ticketing-crm-core — ticketing / CRM core
5. 05-sla-inboxes-routing — SLA policies, inboxes, business hours, routing
6. 06-github-sync-and-ticket-email — GitHub ticket sync, ticket email, integration platform
7. 07-widget-profiles — scoped widget profiles + ticket submission
8. 08-api-openapi-mcp — OpenAPI surface, MCP tools, conversation actions, API keys
9. 09-content-visibility — changelog/help-centre visibility, segments, portal tabs
10. 10-test-coverage — broad unit/integration test suite + supporting infra

Part of the roadmap: #283

[CLAassistant]

All committers have signed the CLA.