Security: Roles

Status: target state, almost entirely unimplemented. The only role-like distinction today is localClient: true (loopback identity) vs. authenticated remote principal.

Today's model

auth.identity.resolve returns:

{
  authenticated: boolean,
  localClient: boolean,
  principalId: string | null,
  ...
}

localClient: true is set when the connection is over loopback. It bypasses ownership checks and acts as a de-facto admin role for everything an actor checks. There is no other "role" in the auth model.

The schema has no principal.role field. There is no IRoleAssignment record type. There is no auth.role.* op family.

Target role set

A minimal target role set:

Role	Scope	Examples
user	One principal, one or more Spaces.	The default.
space-admin	Within a Space, can manage members and Devices.	Org Space leads (when orgs land).
platform-admin	Cross-principal admin operations.	HiveCast operator.
security-auditor	Read-only across all principals.	Compliance reviewer.
service	Programmatic identity, no UI.	Bots, integrations.

Each role would map to a permission set (see Security: Permissions).

Why not RBAC

Per Security: Authorization, the architectural target is capabilities, not RBAC. A minimal RBAC layer for launch is still useful — platform-admin and security-auditor are RBAC-shaped. The capabilities layer would be the durable model that subsumes RBAC.

Workaround for platform-admin today

Use the local-client identity. This means platform admin work happens on the platform Host itself, via SSH + matrix invoke. A remote browser session for an admin user does not have privileged access today.

Workaround for security-auditor today

Read access to <host-home>/state/auth-state.json and <host-home>/logs/runtimes/. Operator-level filesystem access. There is no auditor role that grants read-only API access.

Implementation sketch

A minimal RBAC overlay needing roughly:

1. Add role: 'user' | 'platform-admin' | 'security-auditor' | 'service' to IHostPrincipalRecord.
2. Add auth.role.set op (loopback-only).
3. In every system.auth op, add a requireRole helper that gates on the calling principal's role.
4. In system.devices ops, allow cross-principal listing for platform-admin and security-auditor.
5. In system.runtimes ops, allow cross-Host operations for platform-admin.

About 200-400 lines of code. Bounded scope. Useful immediately.

Role transitions

Promoting a principal to platform-admin should be auditable. The grant op should:

• Log the granting principal, the receiving principal, the role, the timestamp.
• Require multi-step confirmation (e.g., second admin co-signs).
• Be revocable.

These are target.

Service roles

A service role suits non-human principals — bots, automation accounts. It implies:

• Login flow is API-key or service-credential, not OIDC.
• No browser session.
• Long-lived NATS user JWT.
• Scoped to specific actors/ops.

The schema (ownerType: 'service' on Spaces) anticipates this; the role-grant flow does not exist.

See also

• Security: Authorization — broader context.
• Security: Permissions — per-op authorization.
• Users — principal model.

Source: projects/matrix-3/packages/system-auth/src/index.ts:1311-1320 for the localClient short-circuit. No role schema today.