docs/reference/capabilities.md

Inspector — Capabilities (data-driven authorization)

Authorization is a data-driven capability matrix, not hardcoded role tiers. An owner toggles any capability on/off per tier (anonymous / contributor / maintainer) from the Admin → Permissions tab; the change is durable, audited, and takes effect on the affected user's next request. The resolver services/auth/capabilities.py::can() is the single source of authz — every route, state handler, predicate, and edit-lock branch calls it. Roles still exist (contributor < maintainer < owner) but only as the default each capability ships with; an owner overrides per cell.

This doc is the what-is + the convention for adding a gate so it surfaces in the UI. For the predicate/edit-lock/redaction detail see auth-permissions.md; for the Permissions-tab UI see admin-dashboard.md.

---

Adding a capability — the convention

To add a new permission gate so it automatically surfaces in the Permissions tab, do exactly two things (three if it has a UI affordance):

1. Register it — add one Capability(...) (via the _c(...) helper) to CAPABILITIES in qua_shared/schemas/config/capabilities.py:

   • id — dot-namespaced, stable (e.g. reciter.publish, claim.force_release).
   • group — an existing G_* label (or a new one; groups render in first-appearance order).
   • label + description — human text, shown verbatim in the UI. Write them for an owner skimming the matrix.
   • anon — pass a bool only for identity-free read caps (→ anon_eligible); omit for action caps (anonymous renders N/A).
   • contributor / maintainer — the current default for each tier, so the empty-override baseline reproduces today's behavior (parity test enforces this).

2. Gate the code path through the resolver — never a hardcoded role check:

   Where	Use
   Route (decorator)	@require_capability("your.cap") (injects user; anon allowed iff anon_eligible)
   Route (inline)	actions.py::_require_cap("your.cap") or _admin_helpers.require_capability_or_403(user, "your.cap")
   State transition	_require_capability(actor, "your.cap") inside the _h_* handler and add the event → cap row to state.py::_EVENT_CAPABILITY
   Service / predicate / edit-lock	capabilities.can(actor_or_user, "your.cap")

3. (FE — only if there's a UI affordance to show/hide) gate it on lib/stores/capabilities.ts: can('your.cap') (reactive store) or hasCapability(user, 'your.cap') (pure). The Permissions tab itself needs no change — its matrix is fully data-driven (see below).

That's the whole recipe. No endpoint, no Permissions-tab, no migration change — the capability appears in the matrix (label + description + per-tier toggles) on the next GET /api/admin/permissions, and the owner can toggle it immediately. /api/me picks it up in the caller's resolved capabilities[].

Don'ts

• Don't hardcode permissions.is_maintainer() / is_owner() / @require_role(...) at a new gate. Those bypass the registry → the gate won't surface in the Permissions tab and won't be owner-toggleable. The guard test (below) fails the build if @require_role reappears in routes/.
• Ownership checks (is_claim_holder, is_claim_holder_or_maintainer) are not capabilities — they ask "is this your row," and stay as-is. A capability governs the tier dimension layered on top.
• An unknown capability id passed to can() / @require_capability raises ValueError at call/import time — so a typo can't silently create an ungated path.

---

How a capability surfaces in the UI (automatic)

CAPABILITIES (registry)
  → services/admin/permissions.py::build_matrix()   # iterates CAPABILITIES by GROUP_ORDER
  → GET /api/admin/permissions                       # grouped matrix (default ⊕ overrides)
  → PermissionsCompartment.svelte                    # renders every group/cap/tier in the response

The FE hardcodes nothing about which capabilities exist — it renders whatever the matrix returns. So a registered capability is rendered with no FE edit. /api/me exposes the caller's resolved capabilities[] for capability-aware affordance gating elsewhere.

---

Resolver + storage (the substrate)

Piece	Truth
Registry (data)	qua_shared/schemas/config/capabilities.py — Capability{id, group, label, description, anon_eligible, owner_only_fixed, default_grants} + CAPABILITIES, CAPABILITIES_BY_ID, GROUP_ORDER, TIERS. Backend-only; NOT codegen'd to the FE (the matrix response models in admin_permissions.py are).
Resolver	services/auth/capabilities.py — tier_of(user_or_actor) (None→anonymous), resolve_grants() -> {(cap,tier): bool} (baseline ⊕ overrides, cached on db_seq), can(user_or_actor, cap), capabilities_for(user).
Override store	permission_overrides(capability_id, tier, allowed, set_by, set_at) — migration 0008, services/db/repo_permissions.py. Deviations only: absent row → default; reset = DELETE.
Cache	services/storage/cache.py::{get,set,invalidate}_capability_matrix_cache — single (db_seq, matrix) tuple. Any committed override write bumps db_seq → transparent invalidation, no restart. (The autouse test fixture invalidates it too.)
Endpoints	GET /api/admin/permissions + POST /api/admin/permissions/<cap>/<tier> ({allowed} or {reset:true}), both @require_capability("manage_permissions"); POST @require_same_origin, audited access.permission_changed (a HIDDEN_EVENTS event). Service services/admin/permissions.py.

Invariants (hold regardless of the override table)

• Owner is a superuser — can(owner, anything) is True.
• manage_permissions is owner_only_fixed — never grantable to a lower tier even if a row is forced in. Gates the Permissions tab + endpoints; the recovery anchor, so owners can't lock themselves out.
• Anonymous only where anon_eligible — action caps are always False for anonymous; only the public-read caps (view.catalog, view.public_activity) and the public Timestamps-tab report cap (timestamps.report, default-on for everyone) are anonymous-toggleable. timestamps.see_reporter_identity (owner-default) gates revealing the reporter's login on a report + its notification — the owner-facing sibling of segments.see_flagger_identity. timestamps.resolve_report (owner-default) gates the resolve action; timestamps.view_stale_reports (owner-default) gates filtering to reports a re-stamp invalidated; timestamps.view_nonpublic_reports (maintainer-default) gates seeing tajweed + phoneme report flags (timing flags + verse-level comment reports stay public to everyone; a reporter always sees their own).
• Structural integrity is NOT a capability — the last-active-owner guard + owner-on-owner revoke asymmetry (services/admin/users.py, services/auth/access.py) stay enforced even with roles.* toggled on.

Guards (keep the convention honest)

• tests/services/test_capabilities.py — baseline parity (empty overrides == legacy), owner-superuser, manage_permissions immutability, anon-eligibility, override apply/clear, _EVENT_CAPABILITY completeness.
• tests/test_capability_convention.py — (a) build_matrix() returns every registry capability (registry→UI completeness — a new cap can't fail to surface); (b) no @require_role( decorator in inspector/routes/ (forces @require_capability).
• tests/routes/test_route_permissions.py — endpoint owner-only, toggle reflected live, manage_permissions/anon-ineligible rejected, audit emitted.