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#
- Single Source of Truth – Policy and consent text stores enforce uniqueness and ordered lineage; publishing automatically supersedes the prior active version.
- Immutable Ledger – Events are append-only and keyed by UUID. Updates create new records rather than mutating existing entries.
- Compliance Readiness – The ledger schema aligns with GDPR Article 7 requirements. Evidence of consent (policy + text version, timestamp, actor, IP) is always retrievable.
- Localization Ready – Multi-language support is built into both policy and
consent-text records; clients can request bundles localized via
Accept-Language. - 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.