Security & Privacy

Status: Published Last Updated: 2026-03-09

Overview

LifeDB stores maximally sensitive data — private messages, emails, call logs, personal notes. Security and privacy are foundational prerequisites for the system to exist. This document describes the security architecture, the guarantees it provides, and the design philosophy behind them.

Guiding principles:

Defense in depth. Multiple independent layers protect data. Transport encryption, application-level credential encryption, mandatory tenant scoping, permission enforcement, and (for cloud deployments) database-level row isolation all operate simultaneously. No single layer’s failure exposes data.
Structural enforcement over convention. Tenant isolation and permission scoping are enforced by the type system and interface design, not by developer discipline. Security invariants are impossible to accidentally bypass — they are required parameters, not optional checks.
Self-hosted is the baseline. The security model assumes you control the infrastructure. Cloud deployment adds layers on top without changing the core model.
Encryption protects at every boundary. Data in transit is encrypted via TLS. Data at rest is encrypted at the storage layer. Connector credentials receive additional application-level envelope encryption with key separation.

Authentication

API Key Model

Every API request is authenticated with an API key. Keys follow a split-key design: a short, non-secret identifier for efficient lookup paired with a cryptographic secret that is never stored in plaintext. The full key is displayed exactly once at creation — after that, only the identifier is visible.

Key secrets are stored as cryptographic hashes. Even full database access does not expose usable credentials.

Key Lifecycle

Keys support the full lifecycle you’d expect from a production credential system:

Creation with configurable permissions, data scope, rate limits, and optional expiry
Zero-downtime rotation — multiple active keys per configuration allow seamless credential rollover
Immediate revocation — takes effect on the next request, no propagation delay
Automatic expiry — optional TTL enforced at verification time
Usage tracking — last-used timestamps for operational visibility and stale key detection

Consumer Tiers

API keys are issued at one of three tiers, each with different permission ceilings:

Tier	Purpose	Typical Permissions
Owner	Account holder, full administrative access	All operations
Consumer	Applications reading data (AI assistants, dashboards)	Read access, optionally scoped to specific data
Connector	Data source integrations writing data into LifeDB	Write access for ingestion

Authorization

Two-Layer Permission Model

Permissions are enforced at two independent layers:

Operation layer — validates that the API key is permitted to perform the requested operation (read, write, delete) on the requested entity type. Unauthorized operations are rejected before any data access occurs.
Data scope layer — restricts which data the key can see. Every database query is structurally scoped to the key’s tenant and, optionally, further restricted by platform, person, conversation, or time range.

These layers are independent. A key might be authorized to read messages but scoped to only see messages from a specific platform. Both checks must pass.

Mandatory Tenant Isolation

Every data access operation requires a tenant scope. This is not a convention — it is a required parameter at the interface level. Code that omits tenant scoping does not compile.

Tenant isolation is enforced at the query layer: every database query includes tenant filtering as a structural part of the query, applied automatically by the query builder. Individual queries cannot opt out.

Data Scoping

API keys can be scoped beyond tenant isolation to restrict access to a subset of data:

Platform filtering — limit to specific data sources (e.g., only iMessage data)
Person filtering — limit to interactions with specific people
Conversation filtering — limit to specific conversations
Temporal bounds — limit to a date range

Scoping is enforced at the data layer. A scoped key physically cannot retrieve data outside its scope, regardless of the query it constructs.

Audit Trail

Every API request is logged with:

The key identifier and consumer tier
The operation performed and entity types accessed
The timestamp
The outcome (success, denied, error)

Denied requests are logged with the reason for denial. Audit logs are retained for compliance and operational review.

Credential Management

Envelope Encryption

Connector credentials (OAuth tokens, platform API keys) are encrypted using envelope encryption — an industry-standard approach used by AWS, GCP, and Azure for key management:

Each credential is encrypted with its own unique data encryption key (DEK)
Each DEK is encrypted (wrapped) with a key encryption key (KEK)
The KEK never enters the database

This separation means that database access alone cannot decrypt credentials. The KEK is stored externally — as an environment variable for self-hosted deployments, or in a hardware-backed key management service (KMS) for cloud deployments.

Key Rotation

KEK rotation re-wraps data encryption keys with the new KEK without ever decrypting the underlying credentials. This is a fast, safe operation that can run without downtime and without exposing plaintext credential material.

Credentials track which KEK version encrypted them, enabling incremental rotation.

Data Deletion

LifeDB provides thorough, verifiable data deletion designed for GDPR compliance.

Soft Delete

Standard deletion makes data immediately invisible across all API responses while preserving it in storage for a configurable grace period. This allows recovery from accidental deletion.

Hard Purge

Permanent, irreversible removal. Two paths:

Scheduled purge — soft-deleted data is permanently removed after the retention window expires (default: 30 days). This is the normal path, and the timeline is compliant with GDPR’s “without undue delay” standard.
Immediate purge — bypasses the grace period for account deletion or explicit user requests for immediate erasure.

Purge Completeness

When data is permanently purged, removal spans all storage layers:

All versions of the entity (LifeDB maintains version history)
All relationships and cross-references involving the entity
All projected/denormalized copies
All search index entries
All provenance records referencing the entity
Audit logs are anonymized — entity references are replaced with deletion markers, preserving audit structure without retaining personal data

For account deletion, the process removes all data for the tenant across all storage.

Backup Alignment

Backups containing purged data expire per the backup retention policy. With the default 30-day purge grace period and 30-day backup retention, purged data is fully eliminated within 60 days. The system does not retroactively modify existing backups — this is standard practice and GDPR-accepted when retention policies are reasonable.

Purge Verification

Every purge operation produces a verifiable report documenting what was removed — counts and timestamps only, no personal data. Reports are retained for compliance audit.

Rate Limiting

API access is rate-limited per key with separate budgets for read and write operations. This prevents any single consumer from monopolizing system resources and ensures data ingestion cannot starve read access.

Rate limiting is enforced before request processing. Rejected requests receive standard HTTP 429 responses with headers indicating remaining budget, reset time, and retry guidance.

Transport Security

Encryption in Transit

All API connections require TLS 1.2 or higher, with TLS 1.3 preferred
Database connections use TLS for cloud deployments; optional for self-hosted on private networks

Security Headers

API responses include standard security headers:

HSTS enforcement for HTTPS
Content-type sniffing prevention
Frame embedding prevention
Cache suppression for personal data responses

Input Validation

All input is validated at the API boundary before reaching business logic
The GraphQL schema provides type-level validation
Business rules are validated in the domain layer
All database queries use parameterized statements — no string interpolation

Cloud Extensions

Cloud deployment adds security layers on top of the self-hosted baseline. The core security model is unchanged — layers are added.

Database-Level Row Isolation

PostgreSQL row-level security (RLS) policies provide defense-in-depth alongside application-layer tenant scoping. Even if a bug in application code bypassed tenant filtering, the database itself enforces that queries can only access rows belonging to the authenticated tenant.

OAuth 2.0

Cloud deployments add OAuth 2.0 authentication on top of the API key model:

User authentication via authorization code flow
OAuth tokens resolve to the same permission model as API keys
Token management UI for issuing, revoking, and scoping keys
Third-party OAuth for authorizing data source connections (Gmail, Slack, etc.)

Per-Tenant Key Isolation

In cloud deployments, each tenant’s connector credentials are encrypted with a tenant-specific key stored in a hardware-backed KMS:

Tenant key deletion makes all their credentials irrecoverable (cryptographic tenant isolation)
KMS provides hardware-backed key protection and audit logging
The encryption model is unchanged — only the key storage backend shifts from local to KMS

Privacy Considerations

Tenant isolation is structural. Every data access requires a tenant scope. No query can omit it — it’s a required parameter, not an optional filter.
Data scoping is additive restriction. Scoped API keys see a subset of tenant data. The data layer enforces this — consumers cannot bypass scope filters.
Credentials are isolated. Connector credentials are stored separately with application-level envelope encryption. Database access alone does not expose plaintext credentials.
Deletion is thorough. Hard purge removes data across all storage layers, including provenance records. Audit logs are anonymized to preserve structure without personal data.
Self-hosted data stays local. No telemetry, no phone-home, no data leaving your infrastructure.
Cloud adds layers, not replacements. Row-level security, KMS-backed encryption, per-tenant keys, and OAuth build on the self-hosted security model without replacing it.
Audit is comprehensive. Every API access is logged. Purge operations produce verifiable reports.

Vision

Project Vision — Privacy and data ownership principles

Product Specifications

Data Model — Entities and provenance model
API — Consumer API, permission model, scoping
Ingestion — Connector authentication and credential management

Technical Specifications

Architecture — System architecture and deployment model
Data Schema — Database design and tenant isolation
Search & Indexing — Search privacy and scope-filtered queries
Module Interfaces — Cross-module interface contracts
API Implementation — Middleware, authentication, and security headers