Roles & access

Roles

Role	Description
`analyst`	read-only on own tenant
`admin`	administrator of own tenant — agents, rules, billing, identity
`owner`	full control of own tenant + role management
`auditor`	external accountant; bundle export download via Auditor Workbench (TOTP-prod)
`msp_operator`	cross-tenant operator — exclusively `/api/v1/msp/overview`
(`is_superadmin`)	platform superadmin; all MSP endpoints + tenant-suspend

Endpoint gates

Cookie auth + tenant scope is the baseline for every user.* route. On top of that:

Endpoint	Extra gate
`POST /api/v1/trust-score/weights`	role=admin\|owner + TOTP-prod
`POST /api/v1/auditor/bundle`	role=admin\|owner\|auditor + TOTP-prod
`GET /api/v1/auditor/bundles/:t/download`	atomic one-shot, 24h expiry
`GET /api/v1/msp/overview`	role=msp_operator OR is_superadmin
`POST /api/v1/agents/:id/console/start`	role=admin\|owner + TOTP-prod + reason ≥20 chars

All agentAuth.* routes (ingest, register, whoami, heartbeat) go through the SHA-256 bearer-token check; no role check needed.

TOTP purpose buckets

Every TOTP-gated action has its own purpose so cross-feature replay is impossible:

Purpose	Used by
`console_session`	console start
`trust_score_weights`	weights override POST
`auditor_bundle`	bundle generation POST
`force_update`	force-update push to agents
`unlock_evidence`	AI evidence pack content unlock

A 6-digit code consumed for console_session stays invalid for that same purpose for 30 seconds, but IS usable for auditor_bundle within that same 30-second window — different row in consumed_totp_codes.

RLS

Every tenant table has ENABLE ROW LEVEL SECURITY with a tenant_isolation policy. Important: this is defense in depth. set_config('app.current_tenant', …, true) does not survive pgxpool’s connection recycling, so every production query MUST contain an explicit WHERE tenant_id = $1.

Exception: hub-side workers (TrustScoreWorker, IdentityHygieneWorker, SupplyChainWorker, CorrelationWorker, AuthGeoWorker) intentionally run cross-tenant — they emit/aggregate per tenant via the inner-loop scope.

Audit log

Every role change, weights update, bundle creation/download, link creation, and delete operation goes through audit_log with event_type = <feature>.<action>. Filterable in the Audit page (/audit).