diff --git a/Repo-docs-RBAC-MANIFEST.-.md b/Repo-docs-RBAC-MANIFEST.-.md new file mode 100644 index 0000000..037ca6d --- /dev/null +++ b/Repo-docs-RBAC-MANIFEST.-.md @@ -0,0 +1,298 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/RBAC_MANIFEST.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# 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.