Eve library

Privacy Policy & Consent Versioning

Guide

Revision 1

On this page

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

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.