dpdp-erasure-cli 1.0.0

package/tests/vault.compiled-targets.test.ts

@@ -0,0 +1,243 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { vaultUser } from "@modules/engine";
+import {
+  TEST_SECRETS,
+  createTestSql,
+  dropSchemas,
+  insertUser,
+  prepareWorkerSchemas,
+  uniqueSchema,
+} from "./helpers";
+import type { Sql } from "@/types";
+
+describe("Vault Engine compiled DAG execution", () => {
+  let sql: Sql;
+  const schemasToDrop: string[] = [];
+
+  beforeAll(() => {
+    sql = createTestSql();
+  });
+
+  afterAll(async () => {
+    await dropSchemas(sql, ...schemasToDrop);
+    await sql.end();
+  });
+
+  it("mutates a deep compiled target through precompiled joins instead of same-column satellite lookup", async () => {
+    const appSchema = uniqueSchema("vault_compiled_app");
+    const engineSchema = uniqueSchema("vault_compiled_engine");
+    schemasToDrop.push(appSchema, engineSchema);
+    await prepareWorkerSchemas(sql, appSchema, engineSchema, {
+      withDependencies: true,
+      withDeepDependencies: true,
+    });
+
+    const userId = await insertUser(sql, appSchema, "compiled@example.com", "Compiled User");
+    const [order] = await sql<{ id: number }[]>`
+      INSERT INTO ${sql(appSchema)}.orders (user_id, amount)
+      VALUES (${userId}, 500)
+      RETURNING id
+    `;
+    await sql`
+      INSERT INTO ${sql(appSchema)}.shipping_addresses (order_id, street, city)
+      VALUES (${order!.id}, '221B Baker Street', 'Mumbai')
+    `;
+
+    const result = await vaultUser(sql, userId, TEST_SECRETS, {
+      appSchema,
+      engineSchema,
+      now: new Date("2026-01-10T00:00:00.000Z"),
+      rootTable: "users",
+      rootIdColumn: "id",
+      rootPiiColumns: {
+        email: "HMAC",
+        full_name: "STATIC_MASK",
+      },
+      satelliteTargets: [],
+      compiledTargets: [
+        { table: `${appSchema}.users`, pii_columns: ["email", "full_name"] },
+        {
+          table: `${appSchema}.orders`,
+          parent: `${appSchema}.users`,
+          parent_columns: ["id"],
+          child_columns: ["user_id"],
+          pii_columns: [],
+        },
+        {
+          table: `${appSchema}.shipping_addresses`,
+          parent: `${appSchema}.orders`,
+          parent_columns: ["id"],
+          child_columns: ["order_id"],
+          pii_columns: ["street", "city"],
+          action: "redact",
+          mutation_rules: {
+            street: "STATIC_MASK",
+            city: "STATIC_MASK",
+          },
+        },
+      ],
+    });
+
+    expect(result.action).toBe("vaulted");
+    expect(result.dependencyCount).toBe(2);
+
+    const [address] = await sql<{ street: string | null; city: string | null }[]>`
+      SELECT street, city
+      FROM ${sql(appSchema)}.shipping_addresses
+      WHERE order_id = ${order!.id}
+    `;
+    expect(address).toEqual({
+      street: "[REDACTED]",
+      city: "[REDACTED]",
+    });
+
+    const [outbox] = await sql<{ payload: { satellite_mutations: Array<{ table: string; affectedRows: number }> } }[]>`
+      SELECT payload
+      FROM ${sql(engineSchema)}.outbox
+      WHERE event_type = 'USER_VAULTED'
+    `;
+    expect(outbox?.payload.satellite_mutations).toContainEqual({
+      table: `${appSchema}.shipping_addresses`,
+      action: "redact",
+      affectedRows: 1,
+    });
+  });
+
+  it("uses all configured primary key columns when mutating compiled targets", async () => {
+    const appSchema = uniqueSchema("vault_compiled_pk_app");
+    const engineSchema = uniqueSchema("vault_compiled_pk_engine");
+    schemasToDrop.push(appSchema, engineSchema);
+    await prepareWorkerSchemas(sql, appSchema, engineSchema);
+
+    await sql`
+      CREATE TABLE ${sql(appSchema)}.devices (
+        id SERIAL PRIMARY KEY,
+        user_id INTEGER NOT NULL REFERENCES ${sql(appSchema)}.users(id)
+      )
+    `;
+    await sql`
+      CREATE TABLE ${sql(appSchema)}.device_events (
+        device_id INTEGER NOT NULL REFERENCES ${sql(appSchema)}.devices(id),
+        event_seq INTEGER NOT NULL,
+        payload TEXT NOT NULL,
+        PRIMARY KEY (device_id, event_seq)
+      )
+    `;
+
+    const userId = await insertUser(sql, appSchema, "compiled-pk@example.com", "Compiled PK User");
+    const [device] = await sql<{ id: number }[]>`
+      INSERT INTO ${sql(appSchema)}.devices (user_id)
+      VALUES (${userId})
+      RETURNING id
+    `;
+    await sql`
+      INSERT INTO ${sql(appSchema)}.device_events (device_id, event_seq, payload)
+      VALUES
+        (${device!.id}, 1, 'first pii payload'),
+        (${device!.id}, 2, 'second pii payload')
+    `;
+
+    const result = await vaultUser(sql, userId, TEST_SECRETS, {
+      appSchema,
+      engineSchema,
+      now: new Date("2026-01-10T00:00:00.000Z"),
+      rootTable: "users",
+      rootIdColumn: "id",
+      rootPiiColumns: {
+        email: "HMAC",
+        full_name: "STATIC_MASK",
+      },
+      satelliteTargets: [],
+      compiledTargets: [
+        { table: `${appSchema}.users`, pii_columns: ["email", "full_name"] },
+        {
+          table: `${appSchema}.devices`,
+          parent: `${appSchema}.users`,
+          parent_columns: ["id"],
+          child_columns: ["user_id"],
+          pii_columns: [],
+        },
+        {
+          table: `${appSchema}.device_events`,
+          parent: `${appSchema}.devices`,
+          parent_columns: ["id"],
+          child_columns: ["device_id"],
+          primary_key_columns: ["device_id", "event_seq"],
+          pii_columns: ["payload"],
+          action: "redact",
+          mutation_rules: {
+            payload: "STATIC_MASK",
+          },
+        },
+      ],
+    });
+
+    expect(result.action).toBe("vaulted");
+    const rows = await sql<{ event_seq: number; payload: string }[]>`
+      SELECT event_seq, payload
+      FROM ${sql(appSchema)}.device_events
+      WHERE device_id = ${device!.id}
+      ORDER BY event_seq ASC
+    `;
+    expect(rows).toEqual([
+      { event_seq: 1, payload: "[REDACTED]" },
+      { event_seq: 2, payload: "[REDACTED]" },
+    ]);
+  });
+
+  it("treats compiled DAG targets as authoritative when legacy satellite targets are also present", async () => {
+    const appSchema = uniqueSchema("vault_compiled_authority_app");
+    const engineSchema = uniqueSchema("vault_compiled_authority_engine");
+    schemasToDrop.push(appSchema, engineSchema);
+    await prepareWorkerSchemas(sql, appSchema, engineSchema, { withDependencies: true });
+
+    const userId = await insertUser(sql, appSchema, "authority@example.com", "Authority User");
+    await sql`
+      INSERT INTO ${sql(appSchema)}.orders (user_id, amount)
+      VALUES (${userId}, 700)
+    `;
+
+    const result = await vaultUser(sql, userId, TEST_SECRETS, {
+      appSchema,
+      engineSchema,
+      now: new Date("2026-01-10T00:00:00.000Z"),
+      rootTable: "users",
+      rootIdColumn: "id",
+      rootPiiColumns: {
+        email: "HMAC",
+        full_name: "STATIC_MASK",
+      },
+      satelliteTargets: [
+        {
+          table: "legacy_target_that_must_not_run",
+          lookup_column: "user_id",
+          action: "redact",
+          masking_rules: {
+            payload: "STATIC_MASK",
+          },
+        },
+      ],
+      compiledTargets: [
+        { table: `${appSchema}.users`, pii_columns: ["email", "full_name"] },
+        {
+          table: `${appSchema}.orders`,
+          parent: `${appSchema}.users`,
+          parent_columns: ["id"],
+          child_columns: ["user_id"],
+          pii_columns: [],
+        },
+      ],
+    });
+
+    expect(result.action).toBe("vaulted");
+    expect(result.dependencyCount).toBe(1);
+
+    const [outbox] = await sql<{ payload: { execution_plan_source: string; satellite_mutations: unknown[] } }[]>`
+      SELECT payload
+      FROM ${sql(engineSchema)}.outbox
+      WHERE event_type = 'USER_VAULTED'
+    `;
+    expect(outbox?.payload.execution_plan_source).toBe("compiled");
+    expect(outbox?.payload.satellite_mutations).toEqual([]);
+  });
+});

package/tests/vault.replica.test.ts

@@ -0,0 +1,59 @@
+import type { Sql } from "@/types";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const getDependencyGraphMock = vi.fn();
+
+vi.mock("../src/db/graph", () => ({
+  getDependencyGraph: getDependencyGraphMock,
+}));
+
+const { vaultUser } = await import("@modules/engine");
+
+describe("Vault Engine Static Plan Routing", () => {
+  beforeEach(() => {
+    getDependencyGraphMock.mockReset();
+    getDependencyGraphMock.mockResolvedValue([]);
+  });
+
+  it("does not run recursive graph traversal during dry-run when a static plan is provided", async () => {
+    const primary = {
+      unsafe: vi.fn().mockResolvedValue([]),
+    } as unknown as Sql;
+    const replica = {
+      tag: "replica",
+    } as unknown as Sql;
+
+    const result = await vaultUser(
+      primary,
+      42,
+      {
+        kek: new Uint8Array(32).fill(0x42),
+        hmacKey: new Uint8Array(32).fill(0x24),
+      },
+      {
+        appSchema: "tenant_app",
+        engineSchema: "tenant_engine",
+        rootTable: "users",
+        rootIdColumn: "id",
+        rootPiiColumns: { email: "HMAC", full_name: "STATIC_MASK" },
+        satelliteTargets: [],
+        compiledTargets: [
+          { table: "tenant_app.users", pii_columns: ["email", "full_name"] },
+          {
+            table: "tenant_app.orders",
+            parent: "tenant_app.users",
+            join: "tenant_app.users.id = tenant_app.orders.user_id",
+            pii_columns: [],
+          },
+        ],
+        dryRun: true,
+        sqlReplica: replica,
+        now: new Date("2026-01-10T00:00:00.000Z"),
+      }
+    );
+
+    expect(result.action).toBe("dry_run");
+    expect(result.dependencyCount).toBe(1);
+    expect(getDependencyGraphMock).not.toHaveBeenCalled();
+  });
+});

package/tests/vault.test.ts

@@ -0,0 +1,279 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  TEST_SECRETS,
+  createTestSql,
+  dropSchemas,
+  insertUser,
+  prepareWorkerSchemas,
+  uniqueSchema,
+} from "./helpers";
+import type { Sql } from "@/types";
+import { createUserHash, vaultUser } from "@modules/engine";
+import { decryptGCM, unwrapKey } from "@modules/crypto";
+
+describe("Vault Engine (Atomic State Machine)", () => {
+  let sql: Sql;
+  const schemasToDrop: string[] = [];
+
+  beforeAll(() => {
+    sql = createTestSql();
+  });
+
+  afterAll(async () => {
+    await dropSchemas(sql, ...schemasToDrop);
+    await sql.end();
+  });
+
+  async function prepare(options: { withDependencies?: boolean } = {}) {
+    const appSchema = uniqueSchema("vault_app");
+    const engineSchema = uniqueSchema("vault_engine");
+    schemasToDrop.push(appSchema, engineSchema);
+
+    await prepareWorkerSchemas(sql, appSchema, engineSchema, options);
+    return { appSchema, engineSchema };
+  }
+
+  function buildVaultOptions(
+    appSchema: string,
+    engineSchema: string,
+    now?: Date,
+    withCompiledDependencies = true
+  ) {
+    return {
+      appSchema,
+      engineSchema,
+      now,
+      rootTable: "users",
+      rootIdColumn: "id",
+      rootPiiColumns: {
+        email: "HMAC" as const,
+        full_name: "STATIC_MASK" as const,
+      },
+      satelliteTargets: [],
+      compiledTargets: withCompiledDependencies
+        ? [
+          { table: `${appSchema}.users`, pii_columns: ["email", "full_name"] },
+          {
+            table: `${appSchema}.orders`,
+            parent: `${appSchema}.users`,
+            join: `${appSchema}.users.id = ${appSchema}.orders.user_id`,
+            pii_columns: [],
+          },
+          {
+            table: `${appSchema}.profiles`,
+            parent: `${appSchema}.users`,
+            join: `${appSchema}.users.id = ${appSchema}.profiles.user_id`,
+            pii_columns: [],
+          },
+        ]
+        : [],
+    };
+  }
+
+  it("vaults, pseudonymizes, and keeps the original PII decryptable with the KEK", async () => {
+    const { appSchema, engineSchema } = await prepare({ withDependencies: true });
+    const now = new Date("2026-01-10T00:00:00.000Z");
+    const userId = await insertUser(sql, appSchema, "john.doe@example.com", "John Doe");
+
+    const result = await vaultUser(sql, userId, TEST_SECRETS, buildVaultOptions(appSchema, engineSchema, now));
+    expect(result.action).toBe("vaulted");
+    expect(result.userHash).toHaveLength(64);
+    expect(result.pseudonym).toMatch(/@dpdp\.invalid$/);
+    expect(result.dependencyCount).toBe(2);
+
+    const [publicUser] = await sql<{ email: string; full_name: string }[]>`
+      SELECT email, full_name
+      FROM ${sql(appSchema)}.users
+      WHERE id = ${userId}
+    `;
+
+    expect(publicUser?.email).toMatch(/^[0-9a-f]{64}$/);
+    expect(publicUser?.full_name).toBe("[REDACTED]");
+
+    const [vaultRow] = await sql`
+      SELECT *
+      FROM ${sql(engineSchema)}.pii_vault
+      WHERE root_schema = ${appSchema}
+        AND root_table = 'users'
+        AND root_id = ${userId.toString()}
+    `;
+    const [keyRow] = await sql`
+      SELECT *
+      FROM ${sql(engineSchema)}.user_keys
+      WHERE user_uuid_hash = ${result.userHash}
+    `;
+    const [outboxRow] = await sql`
+      SELECT *
+      FROM ${sql(engineSchema)}.outbox
+      WHERE idempotency_key = ${`vault:${appSchema}:users:id:${userId}`}
+    `;
+
+    expect(vaultRow?.user_uuid_hash).toBe(result.userHash);
+    expect(vaultRow?.dependency_count).toBe(2);
+    expect(vaultRow?.pseudonym).toBe(result.pseudonym);
+    expect(vaultRow?.notification_due_at).toBeDefined();
+    expect(keyRow?.encrypted_dek).toBeDefined();
+    expect(outboxRow?.event_type).toBe("USER_VAULTED");
+    expect(outboxRow?.status).toBe("pending");
+
+    expect(keyRow).toBeDefined();
+    expect(vaultRow).toBeDefined();
+    const dek = await unwrapKey(new Uint8Array(keyRow!.encrypted_dek), TEST_SECRETS.kek);
+    const encryptedPayload = new Uint8Array(Buffer.from((vaultRow!.encrypted_pii as { data: string }).data, "base64"));
+    const decryptedPii = await decryptGCM(encryptedPayload, dek);
+
+    expect(JSON.parse(decryptedPii)).toEqual({
+      email: "john.doe@example.com",
+      full_name: "John Doe",
+    });
+  });
+
+  it("hard deletes the user when the root table has no dependent tables", async () => {
+    const { appSchema, engineSchema } = await prepare({ withDependencies: false });
+    const userId = await insertUser(sql, appSchema, "delete.me@example.com", "Delete Me");
+
+    const result = await vaultUser(sql, userId, TEST_SECRETS, buildVaultOptions(appSchema, engineSchema, undefined, false));
+    expect(result.action).toBe("hard_deleted");
+    expect(result.dependencyCount).toBe(0);
+
+    const remainingUsers = await sql`SELECT * FROM ${sql(appSchema)}.users WHERE id = ${userId}`;
+    const vaultRows = await sql`SELECT * FROM ${sql(engineSchema)}.pii_vault WHERE root_id = ${userId.toString()}`;
+    const [outboxRow] = await sql`
+      SELECT *
+      FROM ${sql(engineSchema)}.outbox
+      WHERE idempotency_key = ${`hard-delete:${appSchema}:users:id:${userId}`}
+    `;
+
+    expect(remainingUsers).toHaveLength(0);
+    expect(vaultRows).toHaveLength(0);
+    expect(outboxRow?.event_type).toBe("USER_HARD_DELETED");
+  });
+
+  it("supports dry-run mode without mutating any state", async () => {
+    const { appSchema, engineSchema } = await prepare({ withDependencies: true });
+    const userId = await insertUser(sql, appSchema, "preview@example.com", "Preview User");
+
+    const result = await vaultUser(sql, userId, TEST_SECRETS, {
+      ...buildVaultOptions(appSchema, engineSchema, new Date("2026-01-10T00:00:00.000Z")),
+      dryRun: true,
+    });
+
+    expect(result.action).toBe("dry_run");
+    expect(result.plan?.summary).toContain(`root row ${userId}`);
+
+    const [publicUser] = await sql`SELECT email, full_name FROM ${sql(appSchema)}.users WHERE id = ${userId}`;
+    const vaultRows = await sql`SELECT * FROM ${sql(engineSchema)}.pii_vault WHERE root_id = ${userId.toString()}`;
+    const outboxRows = await sql`SELECT * FROM ${sql(engineSchema)}.outbox`;
+
+    expect(publicUser?.email).toBe("preview@example.com");
+    expect(vaultRows).toHaveLength(0);
+    expect(outboxRows).toHaveLength(0);
+  });
+
+  it("supports shadow mode by validating the full pipeline and rolling back all writes", async () => {
+    const { appSchema, engineSchema } = await prepare({ withDependencies: true });
+    const userId = await insertUser(sql, appSchema, "shadow@example.com", "Shadow User");
+
+    const result = await vaultUser(sql, userId, TEST_SECRETS, {
+      ...buildVaultOptions(appSchema, engineSchema, new Date("2026-01-10T00:00:00.000Z")),
+      shadowMode: true,
+    });
+
+    expect(result.action).toBe("vaulted");
+    expect(result.dryRun).toBe(false);
+
+    const [publicUser] = await sql<{ email: string; full_name: string }[]>`
+      SELECT email, full_name
+      FROM ${sql(appSchema)}.users
+      WHERE id = ${userId}
+    `;
+    const vaultRows = await sql`
+      SELECT *
+      FROM ${sql(engineSchema)}.pii_vault
+      WHERE root_schema = ${appSchema}
+        AND root_table = 'users'
+        AND root_id = ${userId.toString()}
+    `;
+    const outboxRows = await sql`
+      SELECT *
+      FROM ${sql(engineSchema)}.outbox
+      WHERE idempotency_key = ${`vault:${appSchema}:users:id:${userId}`}
+    `;
+
+    expect(publicUser?.email).toBe("shadow@example.com");
+    expect(publicUser?.full_name).toBe("Shadow User");
+    expect(vaultRows).toHaveLength(0);
+    expect(outboxRows).toHaveLength(0);
+  });
+
+  it("rolls back cleanly when the vault insert collides with an existing hash", async () => {
+    const { appSchema, engineSchema } = await prepare({ withDependencies: true });
+    const userId = await insertUser(sql, appSchema, "jane.smith@example.com", "Jane Smith");
+    const conflictingHash = await createUserHash(userId, appSchema, "users", TEST_SECRETS.hmacKey);
+
+    await sql`
+      INSERT INTO ${sql(engineSchema)}.pii_vault (
+        user_uuid_hash,
+        root_schema,
+        root_table,
+        root_id,
+        pseudonym,
+        encrypted_pii,
+        salt,
+        dependency_count,
+        retention_expiry,
+        notification_due_at,
+        created_at,
+        updated_at
+      )
+      VALUES (
+        ${conflictingHash},
+        ${appSchema},
+        'users',
+        '999999',
+        'conflict@dpdp.invalid',
+        ${sql.json({ v: 1, data: "AA==" })},
+        'conflictsalt',
+        1,
+        NOW(),
+        NOW(),
+        NOW(),
+        NOW()
+      )
+    `;
+
+    await expect(vaultUser(sql, userId, TEST_SECRETS, buildVaultOptions(appSchema, engineSchema))).rejects.toThrow();
+
+    const [publicUser] = await sql`SELECT email, full_name FROM ${sql(appSchema)}.users WHERE id = ${userId}`;
+    const keyRows = await sql`SELECT * FROM ${sql(engineSchema)}.user_keys WHERE user_uuid_hash = ${conflictingHash}`;
+    const outboxRows = await sql`
+      SELECT *
+      FROM ${sql(engineSchema)}.outbox
+      WHERE idempotency_key = ${`vault:${appSchema}:users:id:${userId}`}
+    `;
+
+    expect(publicUser?.email).toBe("jane.smith@example.com");
+    expect(publicUser?.full_name).toBe("Jane Smith");
+    expect(keyRows).toHaveLength(0);
+    expect(outboxRows).toHaveLength(0);
+  });
+
+  it("returns an idempotent already_vaulted result when the same user is processed twice", async () => {
+    const { appSchema, engineSchema } = await prepare({ withDependencies: true });
+    const userId = await insertUser(sql, appSchema, "repeat@example.com", "Repeat User");
+
+    const first = await vaultUser(sql, userId, TEST_SECRETS, buildVaultOptions(appSchema, engineSchema));
+    const second = await vaultUser(sql, userId, TEST_SECRETS, buildVaultOptions(appSchema, engineSchema));
+
+    expect(first.action).toBe("vaulted");
+    expect(second.action).toBe("already_vaulted");
+    expect(second.userHash).toBe(first.userHash);
+
+    const outboxRows = await sql`
+      SELECT *
+      FROM ${sql(engineSchema)}.outbox
+      WHERE idempotency_key = ${`vault:${appSchema}:users:id:${userId}`}
+    `;
+    expect(outboxRows).toHaveLength(1);
+  });
+});