Operations: Service, CLI, Cache, Audit

Assignment service

AssignmentService(admin, catalog, before_change=[...], after_change=[...]) validates roles against the catalog (UnknownRoleError; a role may only be assigned in a scope of the kind its permissions belong to) and runs your hooks. before_change may raise to veto: nothing is written. That is where application rules live, for example “the last owner cannot leave” (see the docstring of AssignmentService for the full hook). after_change receives the written assignment; every after hook runs even if an earlier one raises (the first error is re-raised afterwards).

Warning

Changes of one scope are serialised within a process (hooks and write run under a per-scope lock), so concurrent requests cannot both pass the same check. Several processes still race (two owners revoking each other on different servers may leave a scope with no owner): enforce hard invariants in your store (a constraint or a transaction in your own adapter) as well.

CLI

$ export AUTHZ_SQLALCHEMY_DATABASE_URI=postgresql+asyncpg://...   # or AUTHZ_DYNAMODB_TABLE
$ authcli authz assign --store sqlalchemy --principal SUB --scope studio:UUID --role EDI
$ authcli authz list   --store sqlalchemy --scope studio:UUID
$ authcli authz revoke --store sqlalchemy --principal SUB --scope studio:UUID --expected-revision 0

--catalog FILE validates roles. The CLI is the only place that reads these variables.

Cache (opt-in)

CachingAssignmentStore(store, ttl_seconds=...) caches get_assignment in-process (negative results for a quarter of the TTL). It is never enabled by default. Writes through the same instance invalidate at once; writes from other processes become visible only after the TTL, so a revoked principal can keep access that long. TTLs above 60 s need i_understand_stale_authorization=True.

Audit and metrics

AuthzHooks(on_decision=...) receives one DecisionEvent per decision (ids and permission names only; never e-mails or tokens). audit_hook(AuditLogger()) logs it (denied WARNING, not visible INFO, allowed DEBUG, sensitive permissions INFO); metrics_hook(MetricsCollector()) counts per outcome and permission (get_authz_metrics()); combine_hooks chains several. A hook that raises is logged and ignored: auditing never turns an allowed request into a 500.