dpdp-erasure-cli 1.0.0

package/src/modules/engine/vault/satellite-mutation.ts

@@ -0,0 +1,193 @@
+import type { Tsql } from "@/types";
+import { fail } from "@/errors";
+import { quoteQualifiedIdentifier } from "@/utils";
+import { generateHMACWithKey } from "@modules/crypto";
+import type { SatelliteTarget } from "@modules/config";
+import { normalizeRootRowValue, type RootMutationContext } from "./context";
+import { redactSatelliteTable } from "./satellite";
+
+const DEFAULT_SATELLITE_BATCH_SIZE = 1000;
+
+/**
+ * Summary of a single satellite-table mutation.
+ */
+export interface SatelliteMutationResult {
+  table: string;
+  action: "redact" | "hard_delete";
+  affectedRows: number;
+}
+
+/**
+ * Yields the Bun event loop between large mutation batches to keep heartbeats responsive.
+ */
+export async function yieldWorkerEventLoop(): Promise<void> {
+  if (typeof globalThis.Bun !== "undefined" && typeof globalThis.Bun.sleep === "function") {
+    await globalThis.Bun.sleep(0);
+    return;
+  }
+
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+}
+
+async function hardDeleteSatelliteRows(
+  tx: Tsql,
+  appSchema: string,
+  tableName: string,
+  lookupColumn: string,
+  lookupValue: string,
+  tenantId?: string,
+  batchSize: number = DEFAULT_SATELLITE_BATCH_SIZE
+): Promise<number> {
+  if (!Number.isInteger(batchSize) || batchSize < 1) {
+    fail({
+      code: "SATELLITE_BATCH_SIZE_INVALID",
+      title: "Invalid satellite batch size",
+      detail: "satellite batchSize must be an integer greater than 0.",
+      category: "validation",
+      retryable: false,
+    });
+  }
+
+  let totalDeleted = 0;
+
+  while (true) {
+    const tenantFilter = tenantId ? tx` AND tenant_id = ${tenantId}` : tx``;
+    const deletedRows = await tx<{ id: string | number }[]>`
+      WITH batch AS (
+        SELECT id
+        FROM ${tx(appSchema)}.${tx(tableName)}
+        WHERE ${tx(lookupColumn)} = ${lookupValue}
+        ${tenantFilter}
+        LIMIT ${batchSize}
+        FOR UPDATE SKIP LOCKED
+      )
+      DELETE FROM ${tx(appSchema)}.${tx(tableName)}
+      WHERE id IN (SELECT id FROM batch)
+      RETURNING id
+    `;
+
+    if (deletedRows.length === 0) {
+      break;
+    }
+
+    totalDeleted += deletedRows.length;
+    await yieldWorkerEventLoop();
+  }
+
+  return totalDeleted;
+}
+
+async function mutateSatelliteTarget(
+  tx: Tsql,
+  appSchema: string,
+  target: SatelliteTarget,
+  lockedRootRow: Record<string, unknown>,
+  hmacKey: CryptoKey,
+  tenantId?: string
+): Promise<SatelliteMutationResult> {
+  const lookupValue = normalizeRootRowValue(lockedRootRow[target.lookup_column]);
+  if (lookupValue === null) {
+    return {
+      table: `${appSchema}.${target.table}`,
+      action: target.action,
+      affectedRows: 0,
+    };
+  }
+
+  const tableCheck = quoteQualifiedIdentifier(appSchema, target.table);
+  const colCheck = await tx.unsafe(`SELECT * FROM ${tableCheck} LIMIT 0`);
+  const existingCols = new Set((colCheck.columns ?? []).map((c) => c.name));
+  if (!existingCols.has(target.lookup_column)) {
+    fail({
+      code: "SATELLITE_COLUMN_MISSING",
+      title: "Satellite lookup column missing from database schema",
+      detail: `Lookup column "${target.lookup_column}" does not exist in target table "${appSchema}.${target.table}".`,
+      category: "database",
+      retryable: false,
+      fatal: false,
+    });
+  }
+
+  if (target.action === "redact") {
+    const newHmacValue = await generateHMACWithKey(
+      `${appSchema}:${target.table}:${target.lookup_column}:${lookupValue}`,
+      hmacKey
+    );
+    const affectedRows = await redactSatelliteTable(
+      tx,
+      `${appSchema}.${target.table}`,
+      target.lookup_column,
+      lookupValue,
+      newHmacValue,
+      DEFAULT_SATELLITE_BATCH_SIZE,
+      tenantId
+    );
+
+    return {
+      table: `${appSchema}.${target.table}`,
+      action: target.action,
+      affectedRows,
+    };
+  }
+
+  const affectedRows = await hardDeleteSatelliteRows(
+    tx,
+    appSchema,
+    target.table,
+    target.lookup_column,
+    lookupValue,
+    tenantId
+  );
+
+  return {
+    table: `${appSchema}.${target.table}`,
+    action: target.action,
+    affectedRows,
+  };
+}
+
+/**
+ * Applies all configured satellite mutations inside the active vault transaction.
+ *
+ * @param tx - Active repeatable-read transaction.
+ * @param appSchema - Client application schema.
+ * @param rootContext - Validated root and satellite configuration.
+ * @param lockedRootRow - Locked root row snapshot.
+ * @param hmacKey - Pre-imported worker HMAC key.
+ * @param tenantId - Optional tenant discriminator.
+ * @returns One result entry per configured satellite target.
+ */
+export async function mutateSatelliteTargets(
+  tx: Tsql,
+  appSchema: string,
+  rootContext: RootMutationContext,
+  lockedRootRow: Record<string, unknown>,
+  hmacKey: CryptoKey,
+  tenantId?: string
+): Promise<SatelliteMutationResult[]> {
+  const settled = await Promise.allSettled(
+    rootContext.satelliteTargets.map(async (target) => {
+      const result = await mutateSatelliteTarget(
+        tx,
+        appSchema,
+        target,
+        lockedRootRow,
+        hmacKey,
+        tenantId
+      );
+      await yieldWorkerEventLoop();
+      return result;
+    })
+  );
+
+  const rejected = settled.find(
+    (result): result is PromiseRejectedResult => result.status === "rejected"
+  );
+  if (rejected) {
+    throw rejected.reason;
+  }
+
+  return settled.map(
+    (result) => (result as PromiseFulfilledResult<SatelliteMutationResult>).value
+  );
+}

package/src/modules/engine/vault/satellite.ts

@@ -0,0 +1,103 @@
+import { fail } from "@/errors";
+import type { Tsql } from "@/types";
+import { assertIdentifier } from "@/utils";
+
+interface SatelliteRowId {
+  id: number;
+}
+
+async function yieldWorkerEventLoop(): Promise<void> {
+  if (typeof globalThis.Bun !== "undefined" && typeof globalThis.Bun.sleep === "function") {
+    await globalThis.Bun.sleep(0);
+    return;
+  }
+
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+}
+
+function parseQualifiedTableName(tableName: string) {
+  const [schema, table, ...rest] = tableName.split(".");
+  if (!schema || !table || rest.length > 0) {
+    fail({
+      code: "SATELLITE_TABLE_INVALID",
+      title: "Invalid satellite table name",
+      detail: `Invalid table name "${tableName}". Expected "schema.table".`,
+      category: "validation",
+      retryable: false,
+      context: { tableName },
+    });
+  }
+
+  return {
+    schema: assertIdentifier(schema, "schema name"),
+    table: assertIdentifier(table, "table name"),
+  };
+}
+
+/**
+ * Redacts satellite table rows in cursor-sized batches using `FOR UPDATE SKIP LOCKED`.
+ *
+ * The function is designed for large tables and concurrent workers:
+ * each iteration locks and updates only one batch, yields back to Bun's event loop, then
+ * continues until no rows remain.
+ *
+ * @param tx - Active worker transaction.
+ * @param tableName - Qualified table name in `schema.table` form.
+ * @param lookupColumn - Column used to locate rows that reference the root subject.
+ * @param lookupValue - Value to match in `lookupColumn`.
+ * @param newHmacValue - Replacement value written during redaction.
+ * @param batchSize - Maximum rows processed per loop iteration.
+ * @param tenantId - Optional tenant discriminator.
+ * @returns Total number of rows redacted.
+ * @throws {WorkerError} When identifiers are invalid or batch sizing is unsafe.
+ */
+export async function redactSatelliteTable(
+  tx: Tsql,
+  tableName: string,
+  lookupColumn: string,
+  lookupValue: string,
+  newHmacValue: string,
+  batchSize: number = 1000,
+  tenantId?: string
+): Promise<number> {
+  if (!Number.isInteger(batchSize) || batchSize < 1) {
+    fail({
+      code: "SATELLITE_BATCH_SIZE_INVALID",
+      title: "Invalid satellite batch size",
+      detail: "batchSize must be an integer greater than 0.",
+      category: "validation",
+      retryable: false,
+    });
+  }
+
+  const { schema, table } = parseQualifiedTableName(tableName);
+  const safeLookupColumn = assertIdentifier(lookupColumn, "lookup column");
+  let totalRedacted = 0;
+
+  while (true) {
+    const tenantFilter = tenantId ? tx` AND tenant_id = ${tenantId}` : tx``;
+    const updatedRows = await tx<SatelliteRowId[]>`
+      WITH batch AS (
+        SELECT id
+        FROM ${tx(schema)}.${tx(table)}
+        WHERE ${tx(safeLookupColumn)} = ${lookupValue}
+        ${tenantFilter}
+        LIMIT ${batchSize}
+        FOR UPDATE SKIP LOCKED
+      )
+      UPDATE ${tx(schema)}.${tx(table)}
+      SET ${tx(safeLookupColumn)} = ${newHmacValue}
+      WHERE id IN (SELECT id FROM batch)
+      RETURNING id
+    `;
+
+    if (updatedRows.length === 0) {
+      break;
+    }
+
+    totalRedacted += updatedRows.length;
+    await yieldWorkerEventLoop();
+  }
+
+  return totalRedacted;
+}

package/src/modules/engine/vault/shadow.ts

@@ -0,0 +1,36 @@
+import type { VaultUserResult } from "../types";
+
+/**
+ * Internal control-flow error used to force rollback during `shadowMode`.
+ *
+ * The result payload survives the rollback and is returned to the caller so the full pipeline
+ * can be validated without persisting any mutation.
+ */
+export class ShadowModeRollback extends Error {
+  readonly result: VaultUserResult;
+
+  constructor(result: VaultUserResult) {
+    super("Shadow mode rollback.");
+    this.name = "ShadowModeRollback";
+    this.result = result;
+  }
+}
+
+/**
+ * Returns a vault result or throws a rollback sentinel when shadow mode is enabled.
+ *
+ * @param result - Completed vault result.
+ * @param shadowMode - Shadow-mode flag from runtime options.
+ * @returns Result when shadow mode is disabled.
+ * @throws {ShadowModeRollback} When shadow mode is enabled.
+ */
+export function finalizeVaultResult(
+  result: VaultUserResult,
+  shadowMode: boolean
+): VaultUserResult {
+  if (shadowMode) {
+    throw new ShadowModeRollback(result);
+  }
+
+  return result;
+}

package/src/modules/engine/vault/static-plan.ts

@@ -0,0 +1,116 @@
+import type { CompiledExecutionTargetInput } from "@modules/config";
+import { assertIdentifier } from "@/utils";
+import type { RootMutationContext } from "./context";
+import type { VaultUserOptions } from "../types";
+
+interface QualifiedTarget {
+  schema: string;
+  table: string;
+}
+
+/**
+ * Runtime summary of the DPO-attested static execution plan.
+ */
+export interface StaticExecutionPlan {
+  targets: CompiledExecutionTargetInput[];
+  dependencyCount: number;
+  source: "compiled" | "legacy_config";
+}
+
+function parseTargetTable(
+  value: string,
+  defaultSchema: string
+): QualifiedTarget {
+  const parts = value.split('.');
+  if (parts.length === 1) {
+    return {
+      schema: defaultSchema,
+      table: assertIdentifier(parts[0]!, "compiled DAG target table")
+    };
+  }
+
+  if (parts.length === 2) {
+    return {
+      schema: assertIdentifier(parts[0] as string, "compiled DAG target schema"),
+      table: assertIdentifier(parts[1] as string, "compiled DAG target table")
+    };
+  }
+
+  assertIdentifier(value, "compile DAG target table");
+  throw new Error("Unreadable compiled DAG target parser branch");
+}
+
+function targetKey(target: QualifiedTarget): string {
+  return `${target.schema}.${target.table}`;
+};
+
+function configuredMutationTargetKeys(
+  appSchema: string,
+  rootContext: RootMutationContext
+): Set<string> {
+  const keys = new Set<string>();
+  for (const target of rootContext.satelliteTargets) {
+    keys.add(targetKey({ schema: appSchema, table: target.table }));
+  }
+
+  for (const target of rootContext.blobTargets) {
+    keys.add(targetKey({ schema: appSchema, table: target.table }));
+  }
+
+  return keys;
+};
+
+/**
+ * Resolves the bounded runtime plan used by live vault execution.
+ * 
+ * The preferred source is the Introspector-generated `rules[].targets` manifest. If an older
+ * manifest has not yet adopted the compiled DAG block, the worker falls back to the explicitly
+ * configured satellite/blob target lists. It never runs recursive FK discovery inside the vault
+ * transaction. 
+ * 
+ * @param appSchema - Client application Schema.
+ * @param rootContext - Validated root and mutation target config.
+ * @param options - Vault options containing optional compiled targets.
+ * @returns Static dependency boundary used for dry-runs, vaulting, and hard-delete decisions.
+ */
+export function resolveStaticExecutionPlan(
+  appSchema: string,
+  rootContext: RootMutationContext,
+  options: Pick<VaultUserOptions, "compiledTargets">
+): StaticExecutionPlan {
+  const rootKey = targetKey({ schema: appSchema, table: rootContext.rootTable });
+  const explicitTargets = options.compiledTargets ?? [];
+
+  if (explicitTargets.length > 0) {
+    const seen = new Set<string>();
+    let dependencyCount = 0;
+
+    for (const target of explicitTargets) {
+      const key = targetKey(parseTargetTable(target.table, appSchema));
+      if (seen.has(key)) {
+        continue;
+      }
+
+      seen.add(key);
+
+      if (key !== rootKey) {
+        dependencyCount += 1;
+      }
+    };
+
+    return {
+      targets: explicitTargets,
+      dependencyCount,
+      source: "compiled"
+    };
+  }
+
+  const fallBackTargetKeys = configuredMutationTargetKeys(appSchema, rootContext);
+  fallBackTargetKeys.delete(rootKey);
+
+  return {
+    targets: [],
+    dependencyCount: fallBackTargetKeys.size,
+    source: "legacy_config"
+  }
+}

package/src/modules/engine/vault/store.ts

@@ -0,0 +1,34 @@
+import type { SqlExecutor } from "@/types";
+import type { VaultRecord } from "../helpers";
+
+/**
+ * Fetches a vault row by root identity tuple.
+ *
+ * Lookup uses `(root_schema, root_table, root_id, tenant_id)` to avoid cross-tenant collisions.
+ *
+ * @param sql - Postgres pool or transaction.
+ * @param engineSchema - Worker engine schema.
+ * @param appSchema - Source application schema.
+ * @param userId - Source root identifier.
+ * @param rootTable - Source root table name.
+ * @param tenantId - Optional tenant discriminator.
+ * @returns Matching vault row or `null` when not yet vaulted.
+ */
+export async function getVaultRecordByUserId(
+  sql: SqlExecutor,
+  engineSchema: string,
+  appSchema: string,
+  userId: string | number,
+  rootTable: string = "users",
+  tenantId?: string
+): Promise<VaultRecord | null> {
+  const rows = await sql<VaultRecord[]>`
+    SELECT *
+    FROM ${sql(engineSchema)}.pii_vault
+    WHERE root_schema = ${appSchema}
+      AND root_table = ${rootTable}
+      AND root_id = ${userId.toString()}
+      AND tenant_id = ${tenantId ?? ""}
+  `;
+  return rows[0] ?? null;
+}

package/src/modules/engine/vault/vault.ts

@@ -0,0 +1,84 @@
+import type { Sql } from "@/types";
+import { CODE, fail } from "@/errors";
+import {
+  assertWorkerSecrets,
+  createUserHash,
+  resolveNoticeWindowHours,
+  resolveRetentionYears,
+  resolveSchemas
+} from "../helpers";
+import type { VaultUserOptions, VaultUserResult, WorkerSecrets } from "../types";
+import { resolveRootContext } from "./context";
+import { runVaultDryRun } from "./dry-run";
+import { runVaultMutation } from "./execution";
+
+/**
+ * Vaults or hard-deletes a configured root entity under repeatable-read guarantees.
+ *
+ * @param sql - Primary Postgres pool used for transactional writes.
+ * @param subjectId - Root identifier for the subject.
+ * @param secrets - Worker KEK/HMAC key material.
+ * @param options - Vault execution options, including graph, retention, tenancy, and dry-run flags.
+ * @returns Vault execution result with lifecycle timestamps and outbox classification.
+ * @throws {WorkerError} When validation, integrity, concurrency, or crypto preconditions fail.
+ */
+export async function vaultUser(
+  sql: Sql,
+  subjectId: string | number,
+  secrets: WorkerSecrets,
+  options: VaultUserOptions = {}
+): Promise<VaultUserResult> {
+  if (
+    (typeof subjectId !== "string" && typeof subjectId !== "number") ||
+    String(subjectId).trim().length === 0
+  ) {
+    fail({
+      code: `VAULT_${CODE.USER_ID_INVALID}`
+    });
+  }
+
+  const { appSchema, engineSchema } = resolveSchemas(options);
+  const rootContext = resolveRootContext(options);
+  const { kek, hmacKey } = assertWorkerSecrets(secrets);
+  const defaultRetentionYears = resolveRetentionYears(options.defaultRetentionYears);
+  const noticeWindowHours = resolveNoticeWindowHours(options.noticeWindowHours);
+  const now = options.now ? new Date(options.now) : new Date();
+  const tenantId = options.tenantId;
+  const normalizedSubjectId = String(subjectId);
+  const userHash = await createUserHash(
+    subjectId,
+    appSchema,
+    rootContext.rootTable,
+    hmacKey,
+    tenantId
+  );
+
+  if (options.dryRun) {
+    return runVaultDryRun(sql, options.sqlReplica, subjectId, {
+      appSchema,
+      engineSchema,
+      rootContext,
+      defaultRetentionYears,
+      noticeWindowHours,
+      now,
+      tenantId,
+      userHash,
+      compiledTargets: options.compiledTargets,
+    });
+  }
+
+  return runVaultMutation(sql, subjectId, {
+    appSchema,
+    engineSchema,
+    rootContext,
+    defaultRetentionYears,
+    noticeWindowHours,
+    now,
+    tenantId,
+    normalizedSubjectId,
+    userHash,
+    kek,
+    hmacKey,
+    options,
+  });
+}