Authorization

Authorization is "given an authenticated identity, what can it do?". This section is honest about what is implemented today vs target state. The short summary: today the gates are status-based (active vs suspended) plus singleton authority plus NATS account isolation. Capability tokens, topic claims, and security realms have placeholders in code but are not fully wired yet.

Pages in this section

• Capability tokens — what a capability token would look like, what code paths reference them today.
• Topic claims — NATS subject permissions; how scoping works today, what target state would add.
• Security realms — the legacy system-security package's realm model, and how it relates to the cloud system.auth.
• Actor permissions — what an actor declares via static accepts, static emits, and how callers see those declarations.
• Namespace ownership — auth.namespace.claim and the rules around space.*, domain.*, and system.*.

Today's actual authorization gates

Three gates do most of the work today:

1. Principal status — HostPrincipalStore.hasCapability() returns true iff principal.status === 'active'. Suspended principals fail every gate.
2. Host Link status — verifyHeartbeatToken() rejects revoked links. Bus tokens issued under revoked links are scoped to short TTLs and cease to renew.
3. NATS account isolation — subject permissions enforced by NATS itself via operator/JWT mode (per projects/matrix-3/packages/docs/content/security/nats-account-isolation.md).

Beyond these three, there is no per-op capability check today. Adding one is target state.

See also

• Overview / Capability model — what capabilities mean conceptually.
• Identity model — what gets gated.