Role-based access control

What ships today

Mycelium ships folder-glob role-based access control inside every tenant. Each JWT carries a roles claim. Every vault-touching route resolves the role-set against the target path before reading or writing. Denials produce structured audit-log entries with the role-set, the target path, and the actor identity.

This is the first deliverable on the SOC 2 CC6.1 control path. Audit window is targeted 2027. We are not SOC 2 certified yet. The mapping below is what an auditor would read at quarter-end against the AICPA Trust Services Criteria.

1. Default role library (auto-seeded on tenant creation)

Every tenant created on the Mycelium runtime hydrates with this role library. The operator can upsert, edit, or delete roles via the admin API after creation. Glob semantics follow the gitignore convention: ** matches zero or more path segments, * matches any number of characters within a single segment.

2. Admin API surface

All admin endpoints require the admin tenant token. Role library upsert rejects with HTTP 400 if the proposed library would exceed the per-tenant byte cap (10 KB serialized JSON, covers about fifty realistic roles), or if the proposed inheritance list introduces a cycle. Cycle detection runs at save time, so the operator sees a clean 400 instead of a 500 on first read.

• GET /admin/roles/{tenant_id}: list role library
• POST /admin/roles/{tenant_id}: create or replace one role
• DELETE /admin/roles/{tenant_id}/{role_name}: remove one role (HTTP 409 on protected role)
• GET /admin/audit/denials/{tenant_id}: tail of recent denial audit lines
• POST /admin/jwt/{tenant_id}: mint a role-scoped JWT via HTTP

Delete rejects on protected roles. tenant_admin is the fallback for legacy JWTs without a roles claim AND the default-source-role for webhook sources without a natural-owner role. Deleting it would leave the tenant with no role that matches the legacy fallback or the webhook fallback, bricking the install. Operators who want a different fallback identity upsert a replacement role with the same **-globs under a different name first.

3. Webhook denial behavior

Each webhook source maps to a default role for ingestion. If the role’s write-globs no longer cover the source’s folder (because the operator deleted or scoped down the role), the receiver still returns HTTP 200 (webhook contract) but emits one webhook.<source>.denied audit line with status: "denied", the roles set, and the target path. The event payload is written to vaults/<tenant_id>/.dead-letter/<source>/<event_id>.json with a stable event id so redeliveries deduplicate.

Operators replay after fixing the role library via POST /admin/webhooks/replay/{tenant_id}/{event_id}. If the replay still trips RBAC, the dead-letter file is left in place. Only an all-OK replay unlinks it.

4. Backward compatibility

JWTs minted before Phase 4 do not carry a roles claim. The auth layer detects an absent roles key and falls back to ["tenant_admin"], so existing tokens keep working as full-access until the operator re-mints with explicit roles. Tenants persisted before Phase 4 hydrate with roles=[]; the cold-start auth fallback covers them too.

A token that DOES carry a roles claim with an empty list is a deliberate deny-all token, not a legacy fallback. The auth layer returns [] and every RBAC gate denies. This is the explicit revocation affordance for first-party callers. Malformed claim shapes (non-list values) are treated as legacy and fall back to tenant_admin, since a malformed claim is more often a deserialization issue from a buggy proxy than a deliberate revocation, and failing closed there would brick legitimate callers.

5. Operational caveats (the part most pages hide)

What is NOT done is the trust signal. Three caveats operators evaluating Mycelium should know about Phase 4:

• Single-worker assumption. The tenant registry cache lives in-process. Running uvicorn with --workers > 1 and mutating roles via the admin API leaves other workers serving stale role data until they reload. For single-worker deployments (the Phase 4 default), this is invisible. Multi-worker deployments need a Redis-backed tenant cache OR a fan-out invalidation hook. Phase 5 scope.
• Per-tenant per-source default-role override is not yet exposed. The mapping from webhook source to default ingestion role is hardcoded in src/rbac.py::_SOURCE_DEFAULT_ROLE. Operators who want to demote or upgrade a source’s default role per-tenant edit the role’s globs to scope coverage, not the source-mapping itself. Per-tenant override of the source-mapping is a Phase 5 admin endpoint.
• Audit-log denials view truncates. GET /admin/audit/denials/{tenant_id} reads the last roughly ten thousand lines of audit-log.jsonl and filters to denials for that tenant. Tenants with very high denial volume see only the most recent slice. Phase 5 adds cursor-based pagination.

6. SOC 2 CC6.1 mapping

CC6.1 of the AICPA Trust Services Criteria requires logical access security software, infrastructure, and architectures over protected information assets. Phase 4 deliverables map as follows. We are not SOC 2 certified yet. Audit window is targeted 2027.

The audit log at audit-log.jsonl plus the role library at tenants[*].roles is the evidence chain a CC6.1 auditor reads at quarter-end.

7. Deferred to Phase 5+

• Per-entry frontmatter visibility: enforcement (folder-glob ACLs first).
• Per-tenant per-source default-role overrides (operators tighten beyond the seeded library).
• Frontend admin UI for role management (JSON endpoints + curl + the CLI cover Phase 4).
• Multi-worker tenant cache (Redis-backed or fan-out invalidation).
• Cursor-based pagination on the denials view.