148 lines
6.1 KiB
Markdown
148 lines
6.1 KiB
Markdown
# Policy Decision And Provenance Contract
|
|
|
|
`govoplan-policy` owns policy and retention route contributions. Core keeps the
|
|
small shared DTOs that let policy decisions look the same across modules.
|
|
|
|
Privacy retention implementation lives in this module at
|
|
`govoplan_policy.backend.retention`. It is also exposed as the
|
|
`policy.privacyRetention` capability so older core compatibility imports can
|
|
dispatch to the active policy module without owning policy logic in core. Core
|
|
does not import this implementation as a hidden fallback when policy is
|
|
disabled.
|
|
|
|
Reusable hierarchical policy validation lives in
|
|
`govoplan_policy.backend.hierarchy`. Policy families should use that helper for
|
|
parent locks, lower-level override ceilings, "more restrictive only" checks,
|
|
and read-only simulations before destructive or limiting changes are saved.
|
|
Domain modules keep their own policy fields and restriction rules, but the
|
|
decision shape and simulation payload stay consistent.
|
|
When retention needs audit-log storage behavior, it requests the
|
|
`audit.retention` capability; it does not import audit module tables or
|
|
providers directly.
|
|
|
|
## Scheduling Participant Privacy
|
|
|
|
Policy exposes `policy.schedulingParticipantPrivacy` as an optional restriction
|
|
hook. Scheduling supplies the request-level visibility choice and remains
|
|
responsible for its secure fallback when Policy is absent. The provider never
|
|
broadens that choice.
|
|
|
|
System and tenant settings may contain:
|
|
|
|
```json
|
|
{
|
|
"scheduling_participant_privacy_policy": {
|
|
"maximum_visibility": "aggregates_only"
|
|
}
|
|
}
|
|
```
|
|
|
|
`maximum_visibility` is either `aggregates_only` or `names_and_statuses`.
|
|
Omitted settings impose no additional restriction. Effective visibility is the
|
|
most restrictive of the Scheduling request, the system ceiling, and the tenant
|
|
ceiling. Explicit malformed policy fails closed to `aggregates_only` and is
|
|
reported in decision details without echoing the invalid stored value. Policy
|
|
sources include only explicitly configured or invalid system and tenant steps.
|
|
|
|
The current slice is resolver-only. A managed write API and administration UI
|
|
must add validation, audit, parent-ceiling enforcement, and configuration
|
|
safety registration before operators can edit this setting through GovOPlaN.
|
|
|
|
## Backend DTOs
|
|
|
|
Use `govoplan_core.core.policy.PolicyDecision` for explainable policy results:
|
|
|
|
- `allowed`: effective decision for the checked action.
|
|
- `reason`: compact operator-readable explanation.
|
|
- `source_path`: ordered policy sources that produced the decision.
|
|
- `requirements`: machine-readable blockers or prerequisites.
|
|
- `details`: domain-specific structured context, redacted when needed.
|
|
|
|
Use `PolicySourceStep` or `policy_source_step()` for each provenance step:
|
|
|
|
- `scope_type`: `system`, `tenant`, `user`, `group`, or `campaign`.
|
|
- `scope_id`: stable ID for non-system scopes.
|
|
- `path`: stable string path generated by `policy_source_path()`.
|
|
- `label`: concrete source label such as `System`, `Tenant`, `Owner user`,
|
|
`Group`, or `Campaign`.
|
|
- `applied_fields`: field names affected by that step.
|
|
- `policy`: local policy fragment that explains the applied fields.
|
|
|
|
Do not build or split provenance paths manually. Use
|
|
`policy_source_path()` and `parse_policy_source_path()` so IDs are URL-encoded
|
|
consistently.
|
|
|
|
## Retention Explain Endpoint
|
|
|
|
Retention policy exposes the shared shape through:
|
|
|
|
```text
|
|
GET /api/v1/admin/privacy-retention/policies/{scope_type}/explain
|
|
```
|
|
|
|
The response contains `decision`, `effective_policy`, `parent_policy`,
|
|
`effective_policy_sources`, `parent_policy_sources`, and `blocked_fields`.
|
|
|
|
Retention policy also exposes a write-preflight endpoint:
|
|
|
|
```text
|
|
POST /api/v1/admin/privacy-retention/policies/{scope}/simulate
|
|
```
|
|
|
|
The request body is the same as the write endpoint. The response contains a
|
|
`simulation` object with `allowed`, `changed_fields`, `issues`,
|
|
`before_policy`, `requested_policy`, and a shared `PolicyDecision` payload.
|
|
The endpoint never writes policy state and is intended for UI validation before
|
|
operators attempt destructive or limiting changes.
|
|
Clients can use `blocked_fields` to disable controls before a save attempt.
|
|
|
|
## UI Expectations
|
|
|
|
Policy UIs should render provenance close to the effective column or field it
|
|
explains. The display path should use concrete source labels and local values,
|
|
for example:
|
|
|
|
```text
|
|
System: Allow
|
|
> Tenant: Deny without override
|
|
```
|
|
|
|
If all lower levels still inherit, continue the path until the effective local
|
|
decision:
|
|
|
|
```text
|
|
System: Allow
|
|
> Tenant: Inherit
|
|
> Group: Inherit
|
|
> Campaign: Deny
|
|
```
|
|
|
|
When a parent disallows lower-level limits or changes, the UI should disable
|
|
the affected controls and avoid sending those fields in the save payload.
|
|
|
|
System retention execution is a separate high-consequence operation. The UI
|
|
must distinguish dry-run evidence from an applied run, render bounded counts as
|
|
typed rows rather than raw JSON, explain missing write authority, and require a
|
|
destructive confirmation that names deletion/redaction and recovery
|
|
expectations. The backend remains authoritative and records the mode plus
|
|
bounded outcome counts in audit evidence.
|
|
|
|
The shared core WebUI helper `PolicySourcePath` renders the source path shape
|
|
for module UIs. Modules may use their own field layout, but the data contract
|
|
should remain this shape.
|
|
# Function assignment delegation and escalation
|
|
|
|
The `policy.functionAssignmentGovernance` decision includes the effective
|
|
`delegation_allowed`, `maximum_delegation_depth`, and
|
|
`maximum_delegated_validity_days` values plus zero or more per-step escalation
|
|
rules. Each rule binds `holder`, `authority`, or `recipient` review to one exact
|
|
target function and a bounded timeout. Consumers must treat the decision as a
|
|
current limit, not a captured grant: IDM rechecks it across the complete source
|
|
chain at every consequential transition.
|
|
|
|
An elapsed timeout does not change the approval result. IDM records an explicit
|
|
escalated state and the target function; Policy authorizes only a current holder
|
|
of that target for the escalated decision. Missing, malformed, vacant, expired,
|
|
cyclic, over-depth, or tightened routes fail closed with their reason preserved
|
|
in the decision and transition evidence.
|