# Privacy Policy & Consent Versioning

This document defines the contract for privacy policy publication, consent text
lifecycle management, and the consent ledger events emitted by the Lilith Auth
service. The controls described here satisfy regulatory requirements for
GDPR/CCPA consent capture, auditability, and traceability while supporting
localized content delivery.

## Privacy Policy Versioning

Privacy policies are versioned artifacts identified by a stable `policy_id`
(defaults to `privacy_policy`). Each version captures the rendered content,
jurisdictional scoping, and compliance metadata required for distribution and
audit.

| Field                | Type            | Description                                                |
| -------------------- | --------------- | ---------------------------------------------------------- |
| `policy_id`          | string          | Logical identifier for the policy (e.g. `privacy_policy`). |
| `version`            | string          | Semantic version or timestamp tag (e.g. `2.0`).            |
| `title`              | string          | Display name for the policy version.                       |
| `content.sections[]` | array           | Ordered list of text blocks (title + markdown content).    |
| `effective_date`     | ISO-8601 string | When the policy becomes enforceable.                       |
| `language`           | IETF BCP 47 tag | Content language. Default: `en`.                           |
| `jurisdiction`       | string          | Optional geo/regulatory scope (e.g. `US`, `EU`).           |
| `changelog`          | string          | Human readable change summary.                             |
| `requires_reconsent` | boolean         | Signals that downstream clients must prompt users again.   |
| `status`             | enum            | `draft`, `published`, or `superseded`.                     |
| `policy_uuid`        | string (UUIDv4) | Immutable identifier for audit trails.                     |
| `published_at`       | ISO-8601 string | Timestamp when the version was activated.                  |
| `published_by`       | string          | Actor (human or system) that published the version.        |
| `previous_version`   | string          | Most recent predecessor, if any.                           |

Retention: all versions are stored for at least 7 years and never hard-deleted;
deprecated entries transition to `superseded` status but remain queryable via
`/v1/privacy/policies/:id/versions`.

## Consent Text Versioning

Consent prompts (marketing, analytics, functional, voice, etc.) are modeled
independently from the canonical policy. Each consent type maintains its own
version lineage with publish/retire semantics mirroring the policy workflow.

| Field               | Type    | Description                                           |
| ------------------- | ------- | ----------------------------------------------------- |
| `consent_type`      | string  | Identifier (e.g. `marketing`, `analytics`).           |
| `version`           | string  | Semantic version label.                               |
| `title`             | string  | Display heading shown to users.                       |
| `text`              | string  | Primary prompt text.                                  |
| `description`       | string  | Optional extended explanation.                        |
| `required`          | boolean | Whether opt-in is mandatory for core functionality.   |
| `opt_in_text`       | string  | Label for acceptance action.                          |
| `opt_out_text`      | string  | Label for decline action.                             |
| `language`          | string  | Language tag (default `en`).                          |
| `consent_text_uuid` | string  | Unique identifier for reference in ledger records.    |
| `status`            | enum    | `draft`, `published`, `retired`.                      |
| `previous_version`  | string  | Link to the prior entry within the same consent type. |

Only one version per consent type can be `published` at a time. Publishing a
newer version automatically retires the previous published record while keeping
the history intact.

## Consent Ledger Events

Every consent submission, withdrawal, or update writes an immutable record to
the consent ledger. Events are validated against the JSON schema at
`docs/schemas/consent-ledger-event.schema.json` and carry cryptographically
strong identifiers for downstream governance automation.

### Event Fields

| Field                         | Type            | Description                                                   |
| ----------------------------- | --------------- | ------------------------------------------------------------- |
| `consent_event_id`            | string          | UUIDv4 event identifier.                                      |
| `user_id`                     | string          | Subject identifier.                                           |
| `consent_type`                | string          | Consent category (marketing, analytics, etc.).                |
| `granted`                     | boolean         | `true` when consent granted, `false` when withdrawn.          |
| `policy_version`              | string          | Policy version acknowledged during the action.                |
| `consent_text_version`        | string          | Consent text version acknowledged.                            |
| `privacy_policy_acknowledged` | boolean         | Whether the user confirmed the policy.                        |
| `consent_text_acknowledged`   | boolean         | Whether the user confirmed the prompt text.                   |
| `withdrawal_reason`           | string \| null  | Optional reason supplied on withdrawal.                       |
| `timestamp`                   | ISO-8601 string | Event creation time in UTC.                                   |
| `action`                      | string          | `granted`, `withdrawn`, or `updated`.                         |
| `ip_address`                  | string \| null  | Source IP captured at submission time.                        |
| `user_agent`                  | string \| null  | Captured user agent string.                                   |
| `actor`                       | string \| null  | Authenticated actor performing the change (user id or admin). |
| `metadata`                    | object \| null  | Additional structured data (flow identifiers, locale, etc.).  |

### Retention & Access Controls

- Ledger events are retained for 10 years to comply with GDPR accountability.
- Write operations validate policy and consent-text versions against their
  currently published counterparts; stale submissions are rejected with
  `consent.outdated_version`.
- Access to ledger history is gated behind authenticated endpoints. Users can
  read their own ledger via `/v1/users/:id/consent-history-enhanced`;
  administrators require explicit RBAC grants to query on behalf of others.
- All ledger interactions emit audit trail entries (see
  `docs/security/AUDIT_LOGGING.md`) ensuring cross-correlation with security
  monitoring.

## API Surface Overview

| Method & Path                                                    | Description                                                      |
| ---------------------------------------------------------------- | ---------------------------------------------------------------- |
| `POST /v1/privacy/policies`                                      | Create a draft policy version.                                   |
| `POST /v1/privacy/policies/:id/versions/:version/publish`        | Promote a policy version to published.                           |
| `GET /v1/privacy/policies/:id/versions`                          | List all versions with metadata.                                 |
| `GET /v1/privacy/policies/:id/versions/:version`                 | Fetch a specific policy version.                                 |
| `GET /v1/privacy/policies/:id/current`                           | Retrieve the currently published policy.                         |
| `POST /v1/privacy/consent-texts`                                 | Create a draft consent text version.                             |
| `POST /v1/privacy/consent-texts/:type/versions/:version/publish` | Publish a consent prompt.                                        |
| `GET /v1/privacy/consent-texts/current`                          | List active consent prompts per type.                            |
| `POST /v1/users/:id/consent-enhanced`                            | Record consent/withdrawal with version linkage.                  |
| `GET /v1/users/:id/consent-history-enhanced`                     | Retrieve version-aware consent ledger history.                   |
| `GET /v1/users/:id/consent-compliance-check`                     | Check if user requires re-consent.                               |
| `GET /v1/privacy/consent-bundle`                                 | Bundle current policy + consent texts for UI registration flows. |
| `POST /v1/privacy/validate-consent-submission`                   | Validate submitted versions prior to storage.                    |

## Operational Guarantees

1. **Single Source of Truth** – Policy and consent text stores enforce
   uniqueness and ordered lineage; publishing automatically supersedes the prior
   active version.
2. **Immutable Ledger** – Events are append-only and keyed by UUID. Updates
   create new records rather than mutating existing entries.
3. **Compliance Readiness** – The ledger schema aligns with GDPR Article 7
   requirements. Evidence of consent (policy + text version, timestamp, actor,
   IP) is always retrievable.
4. **Localization Ready** – Multi-language support is built into both policy and
   consent-text records; clients can request bundles localized via
   `Accept-Language`.
5. **Programmatic Validation** – The Playwright compliance spec
   (`tests/security.privacy-consent-ledger.spec.ts`) enforces documentation &
   schema synchronization together with runtime validation in CI.

Refer to the schema file referenced above for machine-readable validation rules
used by automated pipelines and Playwright verification.
