# 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: ```text 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 ```text 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 ```text 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 ```text 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 ```text recipients:read recipients:write recipients:import recipients:export ``` ### Files ```text files:read files:download files:upload files:organize files:share files:delete files:admin ``` ### Reports and Audit ```text reports:read reports:export reports:send audit:read ``` ### Mail Servers ```text mail_servers:read mail_servers:use mail_servers:test mail_servers:write mail_servers:manage_credentials ``` ### Tenant Administration ```text 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 ```text 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: ```text 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: ```text 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: ```text 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: ```text 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.