govoplan-core/docs/RBAC_MANIFEST.md

Multi Seal Mail - Current RBAC and Resource-Access Model

Updated: 2026-06-16 Current migration head: f5a6b7c8d9e0

Authorization Equation

An operation is permitted only when every applicable layer allows it:

effective role/API-key capability
AND resource ownership/share access
AND workflow state
AND active governance/policy constraints

RBAC answers what an actor may do. ACLs answer which resource the actor may do it to. Workflow state and policy decide whether the operation is currently valid.

Identity and Scope

Account                         global login identity
+- User membership               tenant-local identity
   +- direct tenant roles
   +- active group memberships
   |  +- inherited tenant roles
   +- tenant-local API keys

Account
+- direct system-role assignments

A browser session has one active tenant membership. System privileges do not silently grant tenant data access. API keys remain tenant-local and receive the intersection of their configured scopes and their owner's live tenant scopes on every request.

Wildcards

tenant:*   every canonical tenant permission
system:*   every canonical system permission
*          legacy alias interpreted as tenant:* only

Tenant wildcards never grant system permissions.

Canonical Tenant Permissions - 53

Campaigns

campaign:read
campaign:create
campaign:update
campaign:copy
campaign:archive
campaign:delete
campaign:share
campaign:validate
campaign:build
campaign:review
campaign:send_test
campaign:queue
campaign:control
campaign:send
campaign:retry
campaign:reconcile

Recipients

recipients:read
recipients:write
recipients:import
recipients:export

Files

files:read
files:download
files:upload
files:organize
files:share
files:delete
files:admin

Reports and Audit

reports:read
reports:export
reports:send
audit:read

Mail Servers

mail_servers:read
mail_servers:use
mail_servers:test
mail_servers:write
mail_servers:manage_credentials

Tenant Administration

admin:users:read
admin:users:create
admin:users:update
admin:users:suspend

admin:groups:read
admin:groups:write
admin:groups:manage_members

admin:roles:read
admin:roles:write
admin:roles:assign

admin:api_keys:read
admin:api_keys:create
admin:api_keys:revoke

admin:settings:read
admin:settings:write
admin:policies:read
admin:policies:write

Canonical System Permissions - 18

system:tenants:read
system:tenants:create
system:tenants:update
system:tenants:suspend

system:accounts:read
system:accounts:create
system:accounts:update
system:accounts:suspend

system:roles:read
system:roles:write
system:roles:assign

system:access:read
system:access:assign

system:audit:read
system:settings:read
system:settings:write
system:governance:read
system:governance:write

system:access:* remains as a compatibility/read and assignment boundary for cross-tenant/system access handling. It is not a separate primary UI area.

Default Tenant Roles

• Owner: tenant:*. At least one active operational owner must remain.
• Tenant administrator: settings, policies, users, groups, roles and API keys plus read access to campaigns/files/reports/audit. Real delivery remains separately delegable.
• Administrator (legacy): all tenant permissions for upgraded installations.
• Access administrator: membership and assignment management within delegation limits.
• Campaign manager: prepare, validate and build campaigns; no review approval or real delivery by default.
• Reviewer: inspect and approve prepared campaign messages.
• Sender: mock-test, queue, control, send, retry and reconcile prepared campaigns; can use/test approved mail profiles.
• File manager: managed file operations without campaign delivery rights.
• Viewer: read campaigns, recipients, files and reports.
• Auditor: read campaigns, recipient evidence, reports and audit records; export detailed evidence.

Default System Roles

• System owner: system:*, protected. At least one active account must retain it.
• System administrator: all specific system permissions, editable and not protected.
• System auditor: read-only system registry/settings/governance/audit role, editable.

Delegation Ceiling

For role definition, assignment and API-key creation:

requested scopes subset of actor delegateable scopes

Rules:

1. Tenant roles may contain tenant scopes only.
2. System roles may contain system scopes only.
3. Definition rights and assignment rights are separate.
4. Group definition and group membership management are separate.
5. API-key scopes are intersected with the owner's current effective scopes on every request.
6. Suspended accounts, users, tenants or groups stop contributing access immediately.
7. Administrative updates are field-sensitive; a user with only status authority cannot change role assignments.

Campaign Ownership and ACLs

A campaign has exactly one owner:

owner user OR owner group

Additional active shares may target users or groups with read or write.

Resolution:

• owner user: read and write;
• member of owner group: read and write;
• explicit read share: read;
• explicit write share: read and write;
• tenant:*: tenant-wide ACL bypass;
• ordinary campaign permission without ownership/share: no object access.

ACLs do not add capabilities. A write share still needs the specific permission for update, validation, review, send, report, retry or reconciliation.

Sensitive Recipient Boundary

Recipient-complete campaign JSON, message data and job detail require recipients:read. Recipient edits require recipients:write; exports require recipients:export; import is reserved for the dedicated recipient import/list workflow.

Files

Permission	Operations
files:read	list, search, inspect, resolve metadata
files:download	download file bytes and generated ZIP archives
files:upload	upload files and ZIP contents
files:organize	create folders, rename, move, copy and bulk rename
files:share	create/revoke file shares
files:delete	delete/hide files and folders subject to retention
files:admin	tenant-wide administration of user/group file spaces

Mail Servers

Permission	Boundary
mail_servers:read	profile metadata and effective policy visibility
mail_servers:use	select an approved profile without reading secrets
mail_servers:test	run server-side connection tests
mail_servers:write	define/edit profiles in allowed scopes
mail_servers:manage_credentials	create/replace SMTP/IMAP secrets or campaign-level credentials where policy allows

Reusable encrypted profiles now exist. Effective usability is also constrained by hierarchical mail-profile policy, ownership, allowed/forced profile sets, credential inheritance mode, the lower-level override switch for that mode, and allow/deny patterns.

Sessions, API Keys and CSRF

• Browser login creates an HttpOnly session cookie and a separate readable CSRF cookie.
• Unsafe cookie-authenticated requests require matching CSRF cookie/header and stored CSRF hash.
• API keys remain supported for CLI/automation and do not use browser CSRF.
• Login responses still expose a compatibility session token in the response body; the WebUI does not persist it.

Legacy Compatibility

Runtime aliases remain only for names that are no longer canonical, including:

campaign:write
attachments:read
attachments:write
admin:users
admin:users:write
admin:api_keys:write
admin:settings
system:tenants:write
system:access:write

Canonical scopes are not widened by runtime alias expansion after migration.

Deferred Permission Families

Add these only with their corresponding implemented features:

templates:*
address_books:*
recipient_lists:*
connectors:*
dsar:*
system:monitoring:read
system:backups:run
system:backups:restore
system:updates:apply
system:updates:rollback

A separate retention:* family is not currently canonical because retention is managed through system settings and tenant policy scopes. Add it only if retention operation duties need separation from general policy/settings administration.