Security and Identity

Matrix is a substrate where any feed, service, or component is the same primitive — a typed actor on a federated bus. A substrate that is open by construction needs a security model that lets it stay open without becoming a free-fire range. This documentation package covers that model end to end.

The model is built on three pillars and one boundary doctrine:

• Policy presets — dev, standard, strict, lockdown — the operating posture of a Host. Hosted production loads standard, strict, or lockdown and must not boot with a null policy engine or the dev preset.
• Capability tokens — credentials that say "the bearer is authorized to do X in scope Y," distinct from identity tokens. Today's implementation is partial (status-gated principal capabilities, Host Link scopes[]); attenuable per-op capability tokens are target state. The C# bridges (com-matrix-bridge, win32-matrix-bridge) already mint, attenuate, and revoke capability tokens — that code is the reference implementation for the planned TypeScript expansion.
• Audit ledger — every cross-trust-boundary action records who did what, when, with which capability, against which target, and the outcome. The bridges already write structured audit events; the substrate-side ledger is being built out.
• Trust-surface and origin doctrine (thesis Part 4.5) — code HiveCast did not author does not run inside the HiveCast control-plane origin. Untrusted-or-user-or-package-generated JavaScript runs in sandboxed iframes (preferably without allow-same-origin) or on a separate registrable domain. Matrix subjects are not browser security boundaries; this rule is what keeps that distinction safe.

Motivation

Security exists in this substrate because typed actors on a federated bus are exactly the surface where ambient authority is dangerous — anything that can be addressed can be invoked, and anything that can be invoked needs an answer to "by whom, with what permission, and what got recorded." This package gives you the three concrete answers in one place: policy presets that classify the operating posture (dev, standard, strict, lockdown), capability tokens that gate every cross-actor invocation, and an audit ledger that records what actually happened. Trust surfaces — what code runs in which origin — are documented separately because they constrain four feature classes: runtime tunnels, generated artifacts, package UIs, and third-party pages. Read this if you are shipping anything to hosted production, integrating an actor that needs auth, or auditing the substrate before adoption.

Five-minute orientation

Decide which posture you need before you read further.

You are	Read this section first
Operating a hosted HiveCast Host or VPS-hosted Host	Overview / Security model plus Authorization / Capability tokens
Reviewing for a security audit	Overview / Threat model, then the boundary rules in CLAUDE.md (Rules 4, 5, 6)
Building a Matrix package that needs credentials	Secrets / Factotum and Secrets / Credential references
Pairing or operating Devices	Authentication / Device flow

Where this fits in the whole

Security is substrate, not vertical. Every vertical (chat, director, the agent platform, the inference market, future third-party Matrix pages) consumes the same boundary rules, the same policy engine, the same Factotum credential discipline, the same audit hooks. When a vertical needs a new capability surface (per-op gates, per-mount caps, attenuated Host-Link tokens), the right answer is to extend the substrate's security model, not to invent a parallel one.

In thesis terms:

• Policy presets are the substrate's "operating posture" mode system. They express what is structurally allowed.
• Capability tokens are the substrate's authorization currency. They express what a specific principal/Device may do, attenuably and revocably.
• The audit ledger is the substrate's accountability primitive. It is what makes "we sold access without selling sovereignty" a verifiable claim, not just a slogan.
• The origin boundary is what keeps federation honest. Federation means typed service contracts between Spaces, not arbitrary UI in a peer's trusted browser origin.

The non-negotiable invariants

These show up in every section, so it is worth stating them up front:

1. Policy posture: hosted production is standard, strict, or lockdown only. A null policy engine or dev preset must not boot in hosted production. The substrate's launch hygiene gate makes this a startup assertion (target state — v0 acceptance).
2. Identity from transport metadata, NEVER from payload. (CLAUDE.md Rule 5.) Bearer tokens, NATS auth claims, and HTTP cookies are authoritative. payload.principalId is untrusted decoration.
3. Credentials go through Factotum ONLY. (CLAUDE.md Rule 4.) system.factotum is the one actor on a Device that reads or writes provider credential files. Other actors use the credential.lease / credential.materialize discipline.
4. Singleton authority mounts have one live owner per authority root. system.runtimes, system.registry, system.devices, system.auth, host.control. Two writers = silent claim collision.
5. HiveCast credentials live cloud-side. Provider credentials live Device-side. The pairing grant is the only legal bridge. (Per USER-FLOWS-AND-AUTH-BOUNDARIES.md.)
6. Code HiveCast did not author does not run inside the HiveCast control-plane origin. Sandboxed iframes or a separate registrable domain. Federation is typed contracts, not foreign UI.

Sections

• Overview — security model, identity model, capability model, credentials model, threat model.
• Authentication — HiveCast account login, OAuth providers (Google, GitHub, Anthropic, Codex), the device-flow used by Hosts, staging and local-test lanes.
• Authorization — capability tokens, topic claims, security realms, actor permissions, namespace ownership.
• Secrets — credential references vs raw tokens, the Factotum service, rotation, and the "no raw OAuth tokens on local Host" rule.
• Auditing — what is logged today, where, and what is target state.
• Reference — wire shapes for tokens, claims, grants, and error codes.

Authoritative sources

• PolicyPresets.ts — the four presets, the SYSTEM_OPS allowlist, and the createPolicyEngine factory.
• BridgeSecurityRealm.cs — the C# capability realm: mint, attenuate, revoke, audit. Reference implementation for the planned TypeScript expansion.
• USER-FLOWS-AND-AUTH-BOUNDARIES.md — where each flow MUST run.
• MATRIX-AUTHORITY-MODEL.md — singleton authority rule, spacePath/spaceId/authorityRoot distinction.
• THESIS.md Part 4.5 — trust surfaces and origin boundaries.
• The code: projects/matrix-3/packages/system-auth/src/host-auth.ts, system-factotum/, system-security/src/.