govoplan-core/docs/DATA_SUBJECT_REQUESTS.md

Data-Subject Request Contract

This document defines the provider-neutral workflow for access and erasure requests. It is an operational control and evidence mechanism. It does not replace legal review, identity verification, retention policy, or the institution's statutory response process.

Ownership

Core owns the request aggregate, lifecycle API, optimistic concurrency, provider discovery, export manifest, execution orchestration, and audit event names. Modules that store subject-related data own their search, explanation, retention, and mutation behavior through a privacy.dsar.<module> capability. Core never scans module tables or guesses how a foreign resource may be erased.

Access owns the first provider. It finds tenant memberships plus safe account, identity, assignment, API-key, and session metadata. It does not export secret hashes, session tokens, IP addresses, or browser fingerprints. Tenant-local membership data can be anonymized and authentication material can be revoked. Global accounts and identities require manual system-level review because they may serve more than one tenant.

Lifecycle

1. A privacy officer records a verified selector, purpose, legal basis, due date, and internal reference.
2. Search invokes every available tenant capability independently. A provider failure is isolated and recorded; it cannot turn an incomplete search into a successful one.
3. The JSON export contains the request, records, provider runs, coverage, retention reasons, execution evidence, and a SHA-256 manifest digest.
4. An erasure request produces stable provider-owned actions. Immutable evidence generates an explicit non-executable retain decision.
5. Execution accepts only selected executable actions from the current plan. It requires If-Match, the current resource revision, the dedicated erase permission, and the exact ERASE <request-id> confirmation phrase.
6. Provider execution is idempotent. Completed or unchanged effects remain durable in the request's execution evidence.

The API is rooted at /api/v1/admin/privacy/data-subject-requests. Access exposes the independent permissions access:privacy:read, access:privacy:manage, access:privacy:export, and access:privacy:erase; the built-in privacy officer role contains all four.

Provider Rules

A provider must:

• enforce tenant ownership for every record and action;
• return stable, unique resource and action identities;
• avoid credentials, hashes, tokens, unnecessary telemetry, and unrelated third-party data;
• distinguish mutable personal data from immutable institutional evidence;
• state a retention reason for immutable evidence;
• propose manual review instead of an automatic action when authority is ambiguous or a resource spans tenants;
• return exactly one execution result per requested action;
• make execution idempotent and avoid committing the caller's transaction;
• keep all actual mutations inside the owning module.

Each active module without a DSAR provider is listed in coverage. This is a deliberate fail-visible state, not proof that the module stores personal data. An institution may call an export complete only after it has reviewed both the provider runs and that coverage list.

Retention And Evidence

Erasure and retention are separate decisions. Stable object IDs, authorization history, function incumbency, formal decisions, delivery evidence, and audit records may remain necessary for accountability. Providers expose those items with a concrete reason and Core prevents them from being selected as executable actions. Policy may further restrict an action, but it must never silently loosen a provider's retention decision.

All lifecycle mutations and exports produce tenant audit events. The request stores an evidence digest after every revision. This digest detects accidental or unauthorized mutation of the aggregate; it is not a digital signature or a substitute for signed recovery evidence.

Current Limits

• Access is the first native provider. Other enabled modules appear in the coverage list until they add a provider or an explicit no-subject-data declaration is standardized.
• Verification of the requester's identity and statutory deadline escalation remain institutional workflows outside this API.
• Global account or identity erasure is deliberately manual.
• Exports are JSON. A human-readable signed response package remains a later Reporting/Templates integration.