Reference: Admin database ownership

For the full ownership map see Reference: Database ownership. This page is the admin lens: which stores an admin reads, which they write, and through which path.

Stores admin needs to read

Store	What admin needs	How
auth-state.json principals[]	Principal fleet, suspension status	auth.principal.list, auth.principal.get
auth-state.json spaces[]	Space fleet, ownership	(target) auth.admin.spaces.list; today: state-file
auth-state.json publicNamespaces[]	Namespace claims, conflict resolution	auth.namespace.list per principal
auth-state.json hostLinks[]	Device fleet	auth.hostLink.list per principal; (target) cross-principal
auth-state.json revokedSessions[]	Currently revoked sessions	state file
<host-home>/runtimes/*.json	Local Host runtime records	filesystem; or host.control runtimes.list
<host-home>/host.status.json	Supervisor status	host.control status
<host-home>/logs/runtimes/*.log	Operational logs	tail

Stores admin writes to (today)

Store	Why	Path
host.json	Configuration changes, secret rotation	edit + Host restart
auth-state.json (suspending)	No suspend op exists	direct edit
auth-state.json (NATS account rotation)	No rotate op exists	direct edit
<host-home>/runtimes/*.json	Manual runtime declaration	host.control runtimes.declare (preferred) or edit

Direct state-file editing requires hivecast stop to avoid concurrent writes. Always backup first.

Stores admin writes to (target via ops)

When the admin op family lands:

Op	Underlying store
auth.admin.principal.suspend	auth-state.json principals[].status
auth.admin.space.suspend	auth-state.json spaces[].status
auth.admin.space.transfer	auth-state.json spaces[].ownerPrincipalId
auth.admin.role.assign	auth-state.json principals[].role (target field)
auth.admin.hostLinks.bulkRevoke	atomic revoke loop with one NATS hub reload
system.devices.admin.bulkRevoke	wraps the above

Stores admin should NOT read directly

• Per-Device <host-home>/credentials/ — these contain plaintext NATS user JWTs and heartbeat tokens. Devices, not the platform admin, manage these.
• Inference credentials — Factotum-only on each Device. Platform admin has no business reading them.
• User content — packages a user installs, conversations they had, etc. The platform does not own this.

Backup-and-restore from admin perspective

# Daily backup script (target: system service)
sudo tar czf /backups/hivecast-$(date +%Y%m%d).tar.gz \
  --exclude=logs --exclude=node_modules \
  /var/lib/hivecast/host-home/

# Encrypt
gpg --encrypt --recipient admin@hivecast.ai \
  /backups/hivecast-$(date +%Y%m%d).tar.gz

# Off-site (target: S3 with retention)

Restore:

hivecast stop
gpg --decrypt /backups/hivecast-<date>.tar.gz.gpg | tar xz -C /
hivecast start

This restores everything: principals, Spaces, Host Links, runtime records, credentials, packages, logs.

Sensitive content

auth-state.json is the most sensitive single file:

• Principal NATS account seeds in credentials[].value for credentialType: 'nats-account'.
• Heartbeat token hashes (low risk; HMAC, not plaintext).
• Pending Google OAuth states with PKCE verifiers (low risk; short TTL).
• Revoked-session jti list (audit interest).

Operational rule: never copy auth-state.json to a less-secure environment. Mask the credentials[] array if sharing for debugging.

Admin-write audit (target)

Every admin write should produce an audit event. Today, manual edits leave no trace beyond the file modification timestamp. Target.

See also

• Reference: Database ownership — full map.
• Security: Secrets — secret-store target.
• Security: Audit trails — write-audit target.

Source: projects/matrix-3/packages/system-auth/src/host-auth.ts for HostAuthStateStore. projects/matrix-3/packages/host-service/src/host-state-store.ts.