Skip to main content

Future-Proofing & Advanced Controls

These features are scaffolding for scale and research. They are disabled by default, keep the current behavior unchanged, and must be explicitly enabled. Use them only when you understand the trade-offs.

Feature Flags (all default to false)​

# Key rotation (enterprise/compliance)
ENABLE_KEY_ROTATION=false
ACTIVE_ENCRYPTION_KEY_VERSION=1

# Metrics / SIEM (observability)
ENABLE_METRICS=false
METRICS_BIND_ADDRESS=127.0.0.1
METRICS_PORT=9090

# Experimental privacy (research-only)
ENABLE_EXPERIMENTAL_PRIVACY=false
PRIVACY_PROCESSOR=identity  # identity | dp_noise | secure_sketch
DP_NOISE_EPSILON=1.0
DP_NOISE_DELTA=1e-5

1) Key Rotation (manual, not automatic)​

What it does: Allows safe encryption-key rotation without wiping the database. Mixed key versions continue to work during transitions.

How to enable (opt-in):

  1. Set ENABLE_KEY_ROTATION=true and choose ACTIVE_ENCRYPTION_KEY_VERSION (default 1).
  2. Provide keys via env vars when rotating: ENCRYPTION_KEY (old) and NEW_ENCRYPTION_KEY (new).
  3. Run the admin CLI from backend/:
python admin.py config-check          # verify flags
python admin.py rotation-status       # inspect current versions
ENCRYPTION_KEY=old NEW_ENCRYPTION_KEY=new \
  python admin.py rotate-key 1 2 --confirm

Safety:

  • Atomic (all-or-nothing) rotation with rollback on failure.
  • Audit trail recorded in rotation_events.
  • DB locked during rotation; schedule during low traffic.

2) Metrics & SIEM (observability)​

What it does: Exposes Prometheus-compatible metrics for health, errors, and security signals (auth failures, rate-limit triggers, encryption errors).

How to enable (opt-in):

  1. Set ENABLE_METRICS=true.
  2. Keep default binding 127.0.0.1:9090 (recommended). To expose beyond localhost, also set ALLOW_PUBLIC_METRICS=true and place behind auth/firewall.
  3. Scrape with Prometheus or curl directly:
curl http://127.0.0.1:9090/metrics

Metrics include:

  • Requests: identify/register/delete (success/failed)
  • Security: auth failures, rate-limit triggers, encryption errors
  • Latency histograms: identify, embedding, match

3) Experimental Privacy Processors (research-only)​

What it does: Adds optional embedding transforms for privacy research.

Processors:

  • identity (default, no-op; production-safe)
  • dp_noise (Gaussian noise; impacts accuracy)
  • secure_sketch (hash-based projection; significant accuracy loss)

How to enable (research only):

ENABLE_EXPERIMENTAL_PRIVACY=true
PRIVACY_PROCESSOR=dp_noise
DP_NOISE_EPSILON=1.0
DP_NOISE_DELTA=1e-5

Warnings:

  • ⚠️ Reduced matching accuracy; do not enable in production without testing.
  • ⚠️ Logged as experimental when active.
  • ⚠️ Revert by setting ENABLE_EXPERIMENTAL_PRIVACY=false.

When to Enable​

  • Key rotation: Compliance, incident response, reducing key lifetime.
  • Metrics: Production monitoring, alerting, SIEM ingestion.
  • Privacy processors: Academic or lab experiments on privacy/accuracy trade-offs.

What Stays the Same by Default​

  • No feature is active unless explicitly enabled.
  • Startup guards, encryption requirements, auth, and rate limiting remain enforced.
  • Database schema changes are backward-compatible (no manual migration needed).

For deeper detail, see the repository docs: backend/ADVANCED_FEATURES.md and backend/SAFETY_VERIFICATION.md.