feat(security): make user erasure durable across restores

Document the accepted user-data trust boundary and selective E2EE architecture, including the data inventory, threat model, key and recovery constraints, migration path, and security gates.

Record pseudonymous erasure requests before deletion, scrub residual identifiers and browser stores, enforce application-log and verification retention, and replay tombstones before the API restarts after a database restore.

Add automatic backup retention, fail-closed restore checks, operator guidance, corrected privacy copy, the named retention-index migration, and coverage across unit, component, and PostgreSQL paths.

Implements #312.

Author: Medformatik

SECURITY.md

@@ -130,6 +130,11 @@ If you self-host OpenMapX, a few recommendations:
   database and follow the operator-controlled cutoff procedure in
   [Monitoring & logs](docs/docs/administration/monitoring.md#purging-historical-application-logs);
   upgrades never delete these records automatically.
+- Treat PostgreSQL snapshots as sensitive user-data copies. Ordinary synchronized
+  content is not end-to-end encrypted, and deleting a live account does not
+  rewrite an existing backup. Restrict and encrypt off-host copies as appropriate,
+  set an expiry policy, and review the
+  [user-data trust model](docs/docs/developer/user-data-trust-model.md).
 - Subscribe to the repository's "Releases only" notifications so security
   releases reach you.
 

apps/api/.env.example

@@ -37,6 +37,14 @@ CORS_ORIGIN=http://localhost:3000,http://127.0.0.1:3000
 # `openssl rand -hex 32`.
 DATABASE_URL=postgresql://postgres:postgres@localhost:5432/openmapx
 
+# Account-erasure durability. Production Compose creates and mounts these.
+# Local development must create a 32-byte base64url key (no trailing newline)
+# and initialize the journal through `openmapx compose render` before deletion.
+# ERASURE_JOURNAL_PATH=../../infra/docker/data/erasure/journal.jsonl
+# ERASURE_JOURNAL_KEY_FILE=../../infra/docker/secrets/erasure-journal-key
+# BACKUP_RETENTION_DAYS=30
+# LEGAL_SERVER_LOG_RETENTION_DAYS=30
+
 # Redis / Valkey (optional, recommended for transit caching)
 # Matches the redis service started by `pnpm openmapx services start --preset dev`.
 # REDIS_PASSWORD_FILE is required whenever REDIS_URL is set: point it at the

apps/api/src/auth.ts

@@ -24,6 +24,7 @@ import {
 import { db } from "./db";
 import { user as userTable } from "./db/schema";
 import { managedOAuthProviderOptions } from "./managed-oauth-provider";
+import { userErasureHooks } from "./services/user-erasure";
 import { auditAdminActionsHook } from "./utils/auth-audit-hook";
 import { configuredTrustedWebOrigins } from "./utils/csrf.js";
 import { sendMail } from "./utils/email";
@@ -139,6 +140,9 @@ const authOptions = {
     encryptOAuthTokens: true,
   },
   databaseHooks: {
+    user: {
+      delete: userErasureHooks,
+    },
     account: {
       create: {
         after: async (account) => {

apps/api/src/db/__tests__/user-erasure-postgres.test.ts

@@ -0,0 +1,121 @@
+import { randomUUID } from "node:crypto";
+import { eq, sql } from "drizzle-orm";
+import { describe, expect, it } from "vitest";
+import { cleanupResidualUserData } from "../../services/user-erasure";
+import { db } from "../index";
+import { adminAuditLog, appLog, user, verification } from "../schema";
+
+const skipDatabase = process.env.OPENMAPX_RUN_DATABASE_TESTS !== "1";
+
+describe.skipIf(skipDatabase)("user erasure constraints with PostgreSQL", () => {
+  it("keeps every direct user foreign key on an explicit erase-safe action", async () => {
+    const result = await db.execute(sql`
+      SELECT child.relname AS table_name,
+             child_column.attname AS column_name,
+             constraint.confdeltype AS delete_action
+      FROM pg_constraint constraint
+      JOIN pg_class parent ON parent.oid = constraint.confrelid
+      JOIN pg_class child ON child.oid = constraint.conrelid
+      JOIN pg_attribute child_column
+        ON child_column.attrelid = child.oid
+       AND child_column.attnum = constraint.conkey[1]
+      WHERE constraint.contype = 'f'
+        AND parent.relname = 'user'
+      ORDER BY child.relname, child_column.attname
+    `);
+
+    const rows = Array.from(result as Iterable<Record<string, unknown>>).map(
+      (row) => `${row.table_name}.${row.column_name}:${row.delete_action}`,
+    );
+    expect(rows).toEqual([
+      "account.user_id:c",
+      "admin_audit_log.actor_id:n",
+      "admin_job.created_by:n",
+      "installed_extension.installed_by:n",
+      "installed_integration.installed_by:n",
+      "integration_secret.updated_by:n",
+      "labeled_place.user_id:c",
+      "mangrove_keypair.user_id:c",
+      "mobile_auth_handoff.user_id:c",
+      "oauth_access_token.user_id:c",
+      "oauth_client.user_id:c",
+      "oauth_consent.user_id:c",
+      "oauth_refresh_token.user_id:c",
+      "parked_location.user_id:c",
+      "passkey.user_id:c",
+      "personal_timeline_connection.user_id:c",
+      "personal_vehicle.user_id:c",
+      "saved_list.user_id:c",
+      "service_secret.updated_by:n",
+      "session.user_id:c",
+      "share_link.user_id:c",
+      "two_factor.user_id:c",
+    ]);
+  });
+
+  it("scrubs residual identifiers from verification, audit, and persisted logs", async () => {
+    const suffix = randomUUID();
+    const userId = `erasure-user-${suffix}`;
+    const email = `erasure-${suffix}@example.test`;
+    const auditId = randomUUID();
+    let userInserted = false;
+    let auditInserted = false;
+    let appLogId: number | undefined;
+    try {
+      await db.insert(user).values({ id: userId, name: "Erasure test", email });
+      userInserted = true;
+      await db.insert(verification).values({
+        id: randomUUID(),
+        identifier: `change-email:${userId}:${email}`,
+        value: userId,
+        expiresAt: new Date(Date.now() + 60_000),
+      });
+      await db.insert(adminAuditLog).values({
+        id: auditId,
+        actorId: userId,
+        targetId: userId,
+        targetType: "user",
+        action: "test",
+        details: { subject: userId, contact: email },
+        ipAddress: "192.0.2.1",
+        userAgent: "erasure-test",
+      });
+      auditInserted = true;
+      const [insertedLog] = await db
+        .insert(appLog)
+        .values({
+          level: "warn",
+          source: "test",
+          msg: `failure for ${email}`,
+          metadata: { subject: userId },
+        })
+        .returning({ id: appLog.id });
+      appLogId = insertedLog?.id;
+
+      await cleanupResidualUserData({ id: userId, email });
+      await db.delete(user).where(eq(user.id, userId));
+
+      expect(await db.select().from(verification).where(eq(verification.value, userId))).toEqual(
+        [],
+      );
+      expect(
+        await db
+          .select()
+          .from(appLog)
+          .where(eq(appLog.id, appLogId as number)),
+      ).toEqual([]);
+      const [audit] = await db.select().from(adminAuditLog).where(eq(adminAuditLog.id, auditId));
+      expect(audit).toMatchObject({
+        actorId: null,
+        targetId: null,
+        details: null,
+        ipAddress: null,
+        userAgent: null,
+      });
+    } finally {
+      if (userInserted) await db.delete(user).where(eq(user.id, userId));
+      if (auditInserted) await db.delete(adminAuditLog).where(eq(adminAuditLog.id, auditId));
+      if (appLogId !== undefined) await db.delete(appLog).where(eq(appLog.id, appLogId));
+    }
+  });
+});

apps/api/src/db/app-log-schema.ts

@@ -10,5 +10,8 @@ export const appLog = pgTable(
     metadata: jsonb("metadata"),
     createdAt: timestamp("created_at").defaultNow().notNull(),
   },
-  (t) => [index("app_logs_level_source_idx").on(t.level, t.source, t.createdAt)],
+  (t) => [
+    index("app_logs_level_source_idx").on(t.level, t.source, t.createdAt),
+    index("app_logs_created_at_idx").on(t.createdAt),
+  ],
 );

apps/api/src/db/auth-schema.ts

@@ -90,7 +90,10 @@ export const verification = pgTable(
       .$onUpdate(() => /* @__PURE__ */ new Date())
       .notNull(),
   },
-  (table) => [index("verification_identifier_idx").on(table.identifier)],
+  (table) => [
+    index("verification_identifier_idx").on(table.identifier),
+    index("verification_expiresAt_idx").on(table.expiresAt),
+  ],
 );
 
 export const passkey = pgTable(

apps/api/src/db/migrations/0019_user_erasure_retention.sql

@@ -0,0 +1,2 @@
+CREATE INDEX "app_logs_created_at_idx" ON "app_logs" USING btree ("created_at");--> statement-breakpoint
+CREATE INDEX "verification_expiresAt_idx" ON "verification" USING btree ("expires_at");