feat(permissions): add GET /permissions/can check endpoint

[zaira-bibi]

Part of: #487 — Analytics are not visible anywhere in the product UI

Backend prerequisite. The frontend that consumes this (the analytics dashboard, stacked PR #539) closes #487. Part of the analytics epic #434.

What

Add a server-side single-permission check endpoint so a client (e.g. the web UI) can ask whether the authenticated user holds a specific permission and gate UI precisely — there is no admin bypass, so is_admin alone is the wrong signal.

Changes

• feat(permissions): GET /api/v1/permissions/can?permission=<name>&scope=<kind>&scope_object_id=<id?> → {"allowed": bool}, auth-only, backed directly by the engine's can(); unknown permission/scope names map to 422 via the exception registry
• refactor(permissions): drop the initial approach (a permissions list on /user/me + a get_user_permissions helper) in favour of the check endpoint, per review feedback — keeps the authorization decision on the server (one source of truth, incl. the scope cascade), extends to object-scoped checks, and discloses only the answer asked for

How to Test

1. Backend suites — all green:
   uv run pytest tests/api/v1/test_permission_check.py tests/api/v1/test_user.py tests/permissions/ -v
2. Gates: make mypy and make lint.backend → clean.
3. Manual (app running): grant a user a role containing analytics.read at the global scope
   (make cli -- roles assign-role <user> <role>), authenticate, then
   GET /api/v1/permissions/can?permission=analytics.read → {"allowed": true};
   a user without the grant → {"allowed": false}.
4. An unknown permission (?permission=does.not.exist) or scope (&scope=nope) → 422; unauthenticated → 403.

Notes

• Supersedes this PR's earlier /user/me permissions-list design (reworked per TL feedback). No migration; no new dependencies.
• The check endpoint is a UI-gating convenience, not a security boundary — every endpoint still enforces its own permission and returns 403.
• The frontend consumer (analytics dashboard) is the stacked PR feat(frontend): add analytics dashboard at /dashboard/analytics #539; it will call this endpoint to gate the nav entry.

This PR description was written with the assistance of an LLM (Claude).

[zaira-bibi]

@claude-review

[claude]

Claude finished @zaira-bibi's task in 1m 25s —— View job

---

Claude Code Review

• Gather context (read changed files & diff)
• Review permissions core changes
• Review API + schema changes
• Review frontend + docs changes
• Validate test coverage
• Post review feedback

---

Reviewed the full diff against origin/main. This is a clean, well-scoped, TDD-first change. get_user_permissions mirrors can() faithfully (same _active_assignment_at_scope selection, so the objectless-ancestor cascade is honoured identically), the permissions field is additive/defaulted so non-/user/me responses stay non-privileged, and the docstrings/guide were updated alongside the code. Test coverage is thorough: granted names, empty, dedup across two roles, and the cascade direction — plus the two API-level tests. Nothing blocking.

Correctness ✅

• The .distinct() on RolePermission.permission correctly dedups a permission granted via multiple roles — covered by test_deduplicates_permission_granted_via_two_roles.
• Reusing _active_assignment_at_scope (rather than re-deriving the scope chain) keeps get_user_permissions and can() in lockstep — if the cascade logic changes, both move together. Good DRY.
• Pydantic mutable default permissions: list[str] = [] is safe (Pydantic deep-copies field defaults per instance), and model_copy(update=...) sets the computed list without re-validating the ORM object. Correct.

Suggestions (non-blocking)

Low — non-deterministic result order. select(...).distinct() has no ORDER BY, so the returned list order is backend-dependent. It's harmless for the frontend nav-gating use case (membership test), and the unit tests guard against it with sorted(...), but a stable order makes responses reproducible and easier to snapshot/assert against later. Optional:

.distinct()
.order_by(col(RolePermission.permission))

Low — two round-trips on /user/me. The handler now issues two queries (has_role for is_admin, then get_user_permissions). Fine at this scale and clearer than a fused query — noting it only for awareness; no change requested.

Test coverage note (optional)

The cascade test covers the parent→child direction (a GLOBAL grant visible at WHITELIST). If you want to lock in the non-cascade direction too, a case asserting that a grant made at a descendant scope does not surface when querying GLOBAL would round out the guarantee — but can()'s existing suite likely already pins this, so it's genuinely optional.

Overall: LGTM. 👍 Correct, tested, documented, and non-breaking.
• zaira/feat/analytics-dashboard-s3

[regisb]

yup this is good!