Security and Identity

Appearance

Overview ​

The Overview gives you the conceptual map. The five pages here lay out:

  • Security model — the boundaries (cloud HiveCast vs local Host vs Device-scoped credential), the singleton authority rule, and the architectural anti-patterns.
  • Identity model — principal identity, Space identity, and the chain from external IdP (issuer, subject) to principalId to authorityRoot.
  • Capability model — what capabilities exist today (mostly status-gated) and what is target state.
  • Credentials model — the four credential layers (HiveCast principal credentials, Device-scoped NATS, heartbeat bearer, local provider OAuth) and where each layer lives.
  • Threat model — the threats this design defends against and the threats that are out of scope.

Core invariants ​

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

  1. 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.

  2. 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.

  3. 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.

  4. HiveCast credentials live cloud-side. Provider credentials live Device-side. The pairing grant is the only legal bridge. (Per WORKSTREAMS/matrix-web/USER-FLOWS-AND-AUTH-BOUNDARIES.md.)

These rules together produce a security architecture where each layer's blast radius is contained. The rest of this domain documents how each piece is enforced today.