Security Model

Matrix's security stack is layered on the addressing model. Authority roots scope ownership; NATS ACL gates the wire; capability tokens gate specific ops; Factotum is the only place credentials cross processes.

Page	What it covers
Capability tokens	The ICapabilityToken shape; how an actor proves it can do an op.
Topic claims	The runtime's TopicClaimRegistry — which actor may publish/subscribe a subject.
Principal identity	CLAUDE.md Rule 5: identity from transport metadata, never from payload.
Device grants	Host link records — how a Device proves it belongs to a principal/Space.
Credentials references	The Factotum-only-reads-credentials rule and credential-by-reference shape.

Five rules that shape this section

Source: CLAUDE.md Rules 4, 5, 7 and MATRIX-AUTHORITY-MODEL.md cross-tenant invariant.

1. Identity from transport metadata, never from payload. Authenticated identity comes from the connection. Payload principalId is untrusted.
2. Credentials go through Factotum ONLY. system.factotum is the one actor that reads/writes credential files. No other actor handles credential bytes.
3. Auth boundaries are split. Google/GitHub OIDC and domain verification go through HiveCast (registered redirect URIs). Anthropic/Codex OAuth and inference API calls stay local (localhost redirect, credentials never leave the machine).
4. Same-origin WebSocket only. Browsers connect to NATS via /nats-ws on the same origin; never an absolute WebSocket URL.
5. Cross-tenant invariant. No identity may read another principal's data, except through an explicit cross-tenant authority grant (today: none in product).

Trust boundaries

┌─────────────────────────────────────────────────────────────┐
│  Browser tab (untrusted user input)                         │
│  ↓ same-origin /nats-ws (TLS at edge)                       │
│  ↓                                                           │
├─────────────────────────────────────────────────────────────┤
│  NATS broker (authenticates connection; ACL per subject)    │
│  ↓ wire identity in transport metadata                       │
│  ↓                                                           │
├─────────────────────────────────────────────────────────────┤
│  Actor (mounts under authority root; ops run under          │
│  capability tokens; can call other actors only on permitted │
│  subjects)                                                   │
│  ↓ credential ref ('anthropic.access_token')                │
│  ↓                                                           │
├─────────────────────────────────────────────────────────────┤
│  system.factotum (only actor that reads credential bytes)   │
│  ↓ fetched bytes used for one outbound API call             │
│  ↓                                                           │
└─────────────────────────────────────────────────────────────┘
   external API (Anthropic, Codex, OpenAI, ...)

See also

• Authority roots — what authority a principal owns.
• Topic claims — wire-level publish/subscribe gate.
• CLAUDE.md — Rules 4, 5, 6, 7.