govoplan-core/docs/GOVERNANCE_MODEL.md

GovOPlaN Governance Model

Updated: 2026-07-09

Governance Rule

System policy is authoritative for tenants and all lower levels. Each lower level may only narrow what it inherits:

system
-> tenant
-> user or group owner
-> campaign

Lower levels do not widen privileges, allowed profiles, retention durations, or credential rights granted by a higher level.

Administration Structure

GovOPlaN separates system administration from scoped configuration:

ADMINISTRATION
- Modules
- Packages
- Maintenance
- Changes

GLOBAL
- Tenants
- Roles
- Groups and users
- File connectors
- Mail servers
- API keys
- Retention

TENANT
- Roles
- Groups and users
- File connectors
- Mail servers
- API keys
- Retention

GROUP
- File connectors
- Mail servers
- API keys
- Retention

USER
- File connectors
- Mail servers
- API keys
- Retention

System access scopes remain in the backend for assignment/read boundaries, but the UI should present the configuration hierarchy rather than a separate "system access" concept.

Tenant Governance

System settings define tenant defaults and whether tenants may narrow selected options. Tenant overrides can only restrict:

• custom groups;
• custom roles;
• tenant API keys.

The backend enforces that tenant governance cannot widen system-denied privileges.

Mail-Profile Governance

Mail server profiles may exist at these scopes:

system
tenant
user
group
campaign

Effective campaign profile availability follows campaign ownership. A campaign owned by a user resolves through system, tenant, that user, and campaign policy. A group-owned campaign resolves through system, tenant, that group, and campaign policy.

Policy semantics:

• higher levels define the maximum available profile set;
• lower levels can further restrict the set;
• forced profiles mean the lower level must choose from the forced set;
• a forced set with one profile effectively enforces that profile;
• campaign-level profile creation is allowed only if the effective policy permits it;
• SMTP/IMAP credentials use one inheritance decision per protocol: lower levels must inherit profile credentials, may inherit profile credentials, or must provide local credentials;
• the lower-level override switch for smtp_credentials.inherit and imap_credentials.inherit controls whether descendants may change that inheritance decision;
• deny patterns always win over allow patterns;
• empty or * allowlist means allow all except denied;
• non-empty allowlist means at least one allow rule must match and no deny rule may match.

Pattern targets:

SMTP hostname
IMAP hostname
envelope sender
From header
recipient domains

Ownership transfer is intentionally deferred as a two-step workflow: original owner initiates, new owner accepts and reselects/repairs the mail profile if their effective policy requires it.

File-Connector Governance

File connector profiles and credentials are separated. Profiles describe external endpoints; credentials bind authentication material and policy to a scope. Concrete linked folders appear as file spaces in the files module.

Governance follows the same inheritance shape as mail:

• system and tenant policy can permit, require, or forbid lower-level connections/credentials;
• user or group ownership controls which spaces appear to principals;
• spaces inherit endpoint and credential policy from their connector profile;
• connector health and credential tests must not reveal plaintext secrets.

Retention Governance

Retention policy is hierarchical:

system -> tenant -> user/group -> campaign

Managed fields:

• raw campaign JSON retention days;
• generated EML retention days;
• stored report detail retention days;
• mock mailbox retention days;
• audit detail retention days.

Rules:

• system may set concrete defaults or unlimited retention;
• system exposes allow-limiting toggles per field;
• tenants, users/groups, and campaigns may only shorten inherited retention where the parent allows limiting;
• blank lower-level values inherit;
• mock mailbox retention is currently system-level because mock mailbox records do not yet carry tenant/campaign ownership metadata;
• dry-run/apply retention actions report affected classes before destructive cleanup.

Role Definitions And Assignments

System Roles

System roles define instance-wide permissions. system:* is stored as one wildcard and displayed as granting the full system catalogue. System owner is protected.

Tenant Roles

Tenant roles can be system-governed templates or tenant-local definitions, subject to system tenant-governance settings and actor delegation ceilings. Wildcard counts are expanded against the canonical tenant catalogue.

Audit Access

Audit access remains scope-separated:

system audit -> system:audit:read
tenant audit -> active tenant + audit:read

Audit pages use server pagination, filtering, and bounded grids.

Tenant Switching

Tenant switching preserves the current URL when possible and falls back when a route/resource is not accessible in the new tenant context.

The tenant selector is hidden for ordinary single-tenant accounts and visible for multi-tenant or system tenant-management contexts.

Administration DataGrid Contract

Admin lists use bounded container grids:

• one flexible fill column;
• fixed total table width;
• compact action/status/count columns;
• resizable text/date columns;
• no intrinsic content growth;
• sticky headers where needed;
• server pagination for audit.

Deferred Work

• DataGrid sizing and resize behavior remains explicitly deferred. The current bounded-grid contract above is binding, but further layout changes should be handled as a dedicated, isolated UI debt item because the component is shared and brittle.
• real SMTP/IMAP test-bed verification and operator runbook;
• recipient import with column mapping;
• session/device revocation UI;
• backup/restore, monitoring, and update procedures;
• DSAR workflows and evidence bundle verifier;
• campaign ownership transfer workflow;
• policy impact analysis before delete/disable/unshare/change;
• LDAP/OIDC/SAML provisioning;
• destructive tenant erasure orchestration.