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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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

- 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.