Security realms

system.security is a package-local identity actor. It is distinct from the cloud system.auth actor. This page is the boundary description and the rule for picking which one to call.

Two system.* auth actors

Actor	Package	Role
system.auth	@open-matrix/system-auth	Cloud authority for principals, sessions, namespaces, Host Links. The HiveCast OIDC RP.
system.security	@open-matrix/system-security	Package-local identity surface. Resolves a bus token to a principal record for the actors mounted alongside it.

Their op surfaces overlap in vocabulary but live at different addresses:

system.auth.auth.session.validate     <- cloud
system.security.auth.whoami           <- package-local

Both validate session/bus tokens. The difference is where the verification lives and what state is consulted.

system.security op surface

Source: projects/matrix-3/packages/system-security/src/AuthActor.ts.

static accepts = {
  'auth.whoami':         { description: 'Return identity for the current session — requires busToken' },
  'auth.refresh':        { description: 'Refresh a bus token before expiry' },
  'auth.principal':      { description: 'Look up a principal by ID' },
  'auth.list-principals':{ description: 'List all known principals' },
};

The actor exposes a directory and a session service. Children spawned by SecurityRoot (projects/matrix-3/packages/system-security/src/SecurityRoot.ts:1-60):

• credential-bridge (CredentialBridgeActor) — bridges credential ops between this realm and Factotum.
• auth (AuthActor) — session validation.
• directory (DirectoryActor) — principal lookup.

This is a "realm" in the sense that it's a self-contained identity-surface: an actor mounted under one root can use it without talking to the cloud. Useful for:

• Local-only Hosts that have no cloud link but still want a uniform identity API.
• Testing actors against a synthetic principal directory.
• Federated Spaces that mirror a subset of cloud principal data locally.

When to call which

You want	Call
Validate a session cookie from an HTTP request	system.auth.auth.session.validate
Validate a bus token in a backend actor	system.security.auth.whoami
Resolve identity from arbitrary HTTP headers	system.auth.auth.identity.resolve
Check if principalId is known to this realm	system.security.auth.principal
Check if principalId is known cloud-side	system.auth.auth.principal.get
Mint a fresh cookie session	system.auth.auth.session.create
Mint a fresh short-lived bus token	system.auth.auth.session.create (with purpose: 'bus') or system.security.auth.refresh

The cloud system.auth is the authority; system.security is a local projection / convenience. When in doubt, call system.auth.

Realm = bus root

In product copy, "realm" overlaps with authorityRoot. Each authority root has its own system.security instance (singleton-per-root rule). A federated multi-Space deployment can have one system.security per Space.

The cloud system.auth is also one-per-authority-root. The cloud's state file lists all principals across the cloud's authority root, and each Space inherits from that root.

Why two

You might ask: "if system.auth is authoritative, why have system.security at all?"

1. Decoupling. Backend actors that need identity should not round-trip to the cloud on every call. system.security is the local cache + bus-side adapter.
2. Local-only Hosts. A Host with no cloud link still needs an identity surface. system.security provides it.
3. Package boundary. system.security is a normal Matrix package. Other packages can mount it. system.auth is bigger, has a state file, and runs cloud-side (or in the platform-role Host).

Relationship to capability tokens

If/when capability tokens land, they would be issued by system.auth and verified by system.security (or an analogous local layer). The capability layer would sit between identity verification and op dispatch, possibly as a middleware on MatrixActor.dispatch.

See also

• HiveCast account login — system.auth's login flow.
• Topic claims — NATS-level authorization.
• Actor permissions — what actors gate at the framework level.

Source: projects/matrix-3/packages/system-security/src/SecurityRoot.ts, system-security/src/AuthActor.ts, system-security/src/SessionService.ts, system-security/src/DirectoryActor.ts, system-security/src/CredentialBridgeActor.ts.