govoplan-core/docs/ACCESS_RBAC_MODEL.md

GovOPlaN RBAC And Resource-Access Model

Updated: 2026-07-09

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

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

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 a read/assignment boundary for cross-tenant and 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, API keys, and read access to campaigns/files/reports/audit. Real delivery remains separately delegable.
• Administrator: 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.

Files

The current file access model distinguishes tenant-level file capabilities from space/folder/file ownership:

Scope	Meaning
files:read	browse/read visible file spaces and metadata
files:download	download file content when ACL permits
files:upload	create files in writable spaces
files:organize	create folders, move files, and update metadata where ACL permits
files:share	share files/spaces according to owner and policy rules
files:delete	delete or retire files where ACL permits
files:admin	tenant-wide administration of user/group file spaces

External file connections and spaces are additionally constrained by connector policy and owner/group assignment in the files module.

Mail Servers

Scope	Meaning
mail_servers:read	profile metadata and effective policy visibility
mail_servers:use	use an allowed profile for a campaign or message flow
mail_servers:test	run connectivity tests without revealing secrets
mail_servers:write	create/update profile metadata where policy allows
mail_servers:manage_credentials	create/replace SMTP/IMAP secrets or lower-level credentials where policy allows

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

Compatibility Aliases

Compatibility aliases may exist in backend code for upgraded installations, but new UI and docs should use canonical scopes.

Current alias direction:

*                      -> tenant:*
system:tenants:write   -> create/update/suspend tenant scopes
system:access:write    -> system access assignment/write scopes

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.