Authority roots

An authority root is the internal namespace used by NATS, by security policy, and by the runtime when registering claims. It is the canonical "who owns this slice of the bus?" identifier.

Source: WORKSTREAMS/core-and-packaging/MATRIX-AUTHORITY-MODEL.md § "Public Space identity stack". This page summarizes the four-level identity stack settled by Gate 2.2 on 2026-05-04.

The four-level identity stack

A public Space is described by four distinct values. They look similar at a glance and are easy to conflate, but each has a different role:

Concept	Field	Example	Where it appears
User-facing public path	spacePath	alt.stories.ghost-stories.funny	URLs as /<spacePath>/<appName>/; user-typed
Typed namespace claim	publicNamespace	space.alt.stories.ghost-stories.funny	internal claim key, NEVER in URLs
Durable Space identity	spaceId	spc-7f3a9b2c	product-stable Space id (lowercase, hyphen-safe)
Internal authority root	authorityRoot	space.spc-7f3a9b2c	bus / security / runtime root

The verbatim copy from MATRIX-AUTHORITY-MODEL.md:

"For new Spaces, derived from spaceId, never from public path text. Legacy SPACE-<UPPERCASE-PATH> records remain readable; new roots are minted from durable spaceId and never derived from public path text."

Why each layer exists

spacePath is the only one users type. It can change (rename a Space) and can be aliased. Examples are friendly: acme.support, nimbletec.engineering.

publicNamespace is the typed claim key. By convention it is space.<spacePath> for public Spaces. Internal — never in URLs.

spaceId is the durable Space id. It does NOT change. If spacePath moves, spaceId stays put. Stored alongside Space records in system.auth. Format: spc-<8 lowercase hex chars>.

authorityRoot is the bus prefix. New Spaces use space.<spaceId> so the bus root never has to migrate when the friendly path changes. Legacy roots derived from path text (SPACE-<UPPERCASE-PATH>) remain readable for older deployments.

Examples

A new corporate Space:

spacePath:        nimbletec.engineering
publicNamespace:  space.nimbletec.engineering
spaceId:          spc-9c3a417e
authorityRoot:    space.spc-9c3a417e

A user-rooted personal namespace (different shape, not a Space):

account email:    richard-santomauro@nimbletec.com
authorityRoot:    COM.NIMBLETEC.RICHARD-SANTOMAURO

The user-rooted shape is the legacy (and current product) form: reverse domain, uppercase, append username. See Host wire roots.

What "authority" means here

Per MATRIX-AUTHORITY-MODEL.md, the authority root governs:

1. NATS subject prefix — every actor under this root publishes/subscribes on {authorityRoot}.>. NATS ACL is configured per root.
2. Singleton ownership — singleton mounts (system.runtimes, system.registry, system.devices, system.auth, host.control) have exactly one live owner per authority root.
3. Heartbeat scoping — devices.heartbeat, registry.heartbeat, and runtime-record TTL are all scoped to the authority root.
4. Cross-tenant invariant — "No identity may read another principal's data, except through an explicit cross-tenant authority grant (today: none in product)."

Resolution

For user-rooted addresses (matrix://user@domain/path):

richard-santomauro@gmail.com  → COM.GMAIL.RICHARD-SANTOMAURO
amazon.com                    → COM.AMAZON
jane@acme.com                 → COM.ACME.JANE

Rule: reverse the domain (dot-delimited), uppercase, append the username (uppercase, hyphens preserved).

For Space-rooted addresses, the address itself is <spacePath> and the runtime resolves to the durable spaceId and authorityRoot via auth.namespace.resolve.

Caution: gmail.com → COM.GMAIL, NOT COM.GOOGLE. Domain-as-typed, no email-provider canonicalization. This is a hard rule — Hosts discover each other through this prefix, and any divergence breaks routing.

routeKey is a v1 alias for spacePath

From MATRIX-AUTHORITY-MODEL.md:

"routeKey is a v1 compatibility alias for spacePath. New code, specs, and UI copy must say "Space path"; existing stored routeKey fields remain as compatibility aliases during the v1 transition."

The CLI flag --route-key is preserved as a v1 alias on hivecast login and related commands. New code should use spacePath everywhere.

Validation grammar

From MATRIX-DISCOVERY-METADATA-SPEC.md §1:

appName    /^[a-z0-9][a-z0-9-]*$/
spacePath  /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/
routeKey   v1 compatibility alias for spacePath (same shape allowed)

The authorityRoot for a new Space MUST be derived from spaceId, not from spacePath text. This is rule 7 in the authority-model rules:

"Authority root provenance for new Spaces. New Space authorityRoot values MUST be derived from durable spaceId, never from mutable public path text."

Where authority roots come from

Origin	Authority root format	Notes
User-rooted account	COM.GMAIL.<USERNAME> etc.	Derived from email at signup
Organization root	<TLD>.<DOMAIN>	Derived from verified domain
New public Space	space.<spaceId>	Minted at Space creation; immutable
Legacy Space	SPACE-<UPPERCASE-PATH>	Pre-2026-05-04 records; read-only support
HiveCast platform	AI.HIVECAST.HOST	Reserved for the platform

See also

• Host wire roots — environment-level wire prefix.
• Runtime wire roots — per-runtime sub-scopes.
• Principal identity — how identity binds to authority root.
• Singleton claims — what "singleton per authority root" means.
• MATRIX-AUTHORITY-MODEL.md — full authority/projection table.