Document Version: 1.0
Last Updated: 2025-10-03
Owners: Identity Engineering & Privacy Office
This document outlines how the Auth service manages personalization vectors, privacy budgets, and retention lifecycles.
Vector Storage#
- Supported vector types:
content_preferences,interaction_patterns,private_preferences,temporary_interaction,audit_test. - Privacy levels align with budget cost tiers:
minimal(cost 5, retention 30 days, high anonymization)aggregated(cost 10, retention 90 days, partial anonymization)detailed(cost 25, retention 180 days, no anonymization)
- Vector payloads are restricted to ≤512 dimensions and metadata is PII scrubbed by schema policy.
Privacy Budgets#
- Default budget: 100 units per rolling 30-day period per user.
- Each operation records consumption history with operation name, timestamp, and metadata.
- Exceeding budget returns
personalization.privacy_budget_exceededwith remaining amount and next reset. - Budgets auto-reset at period boundaries and can be reset manually by
administrators via
/v1/users/:id/personalization/privacy-budget/reset.
Retention & Cleanup#
- Default retention is derived from privacy level; vectors store an explicit
expires_attimestamp. - Expired vectors are removed via
/v1/personalization/cleanup/expired(supports dry-run and force modes). - Users can request targeted cleanup using
/v1/users/:id/personalization/cleanup, which also reclaims consumed budget.
Audit Logging#
- All personalization operations append to
/v1/users/:id/personalization/audit-logswith privacy impact metadata. - Logs cap at the 500 most recent entries to balance observability and storage.
API Overview#
| Endpoint | Description |
|---|---|
POST /v1/users/:id/personalization/vectors |
Create vector with privacy-level aware budget consumption |
GET /v1/users/:id/personalization/vectors |
List active vectors for user (owner/admin only) |
PUT /v1/users/:id/personalization/vectors/:vectorId |
Update vector dimensions/metadata |
DELETE /v1/users/:id/personalization/vectors/:vectorId |
Soft-delete vector and reclaim budget |
GET /v1/users/:id/personalization/privacy-budget |
Current budget snapshot |
POST /v1/users/:id/personalization/privacy-budget/consume |
Custom budget consumption logging |
POST /v1/users/:id/personalization/privacy-budget/reset |
Manual reset for support workflows |
GET /v1/users/:id/personalization/privacy-budget/analytics |
Returns breakdown and trend metrics |
POST /v1/personalization/cleanup/expired |
Global retention cleanup |
Refer to tests/auth.personalization-vectors.spec.ts for full compliance
coverage.