dpdp-erasure-cli 1.0.0

package/src/modules/crypto/aes.ts

@@ -0,0 +1,158 @@
+import { fail } from "@/errors";
+
+
+const IV_LENGTH = 12; // 96-bit IV is the industry standard for GCM.
+const KEY_LENGTH = 32; // 256-bit key for AES-256.
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+function assertAesKeyLength(rawKey: Uint8Array) {
+  if (rawKey.length !== KEY_LENGTH) {
+    fail({
+      code: "CRYPTO_INVALID_KEY_LENGTH",
+      title: "Invalid AES key length",
+      detail: `Invalid key length. Expected ${KEY_LENGTH} bytes for AES-256, got ${rawKey.length} bytes.`,
+      category: "crypto",
+      retryable: false,
+    });
+  }
+}
+
+function toOwnedArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const copy = new Uint8Array(bytes.byteLength);
+  copy.set(bytes);
+  return copy.buffer as ArrayBuffer;
+}
+
+async function importAesKey(rawKey: Uint8Array, usages: readonly ("encrypt" | "decrypt")[]): Promise<CryptoKey> {
+  assertAesKeyLength(rawKey);
+
+  const keyBytes = rawKey.slice();
+  try {
+    return await globalThis.crypto.subtle.importKey(
+      "raw",
+      toOwnedArrayBuffer(keyBytes),
+      "AES-GCM",
+      false,
+      [...usages]
+    );
+  } finally {
+    keyBytes.fill(0);
+  }
+}
+
+/**
+ * Encrypts raw bytes using AES-256-GCM.
+ *
+ * This overload exists for sensitive call sites that need direct control over plaintext buffer
+ * lifecycle so the caller can explicitly wipe the source bytes after encryption.
+ *
+ * @param plaintext - Raw plaintext bytes to encrypt.
+ * @param rawKey - 32-byte symmetric key.
+ * @returns Combined buffer in `IV || ciphertext+tag` format.
+ * @throws {WorkerError} When key length is invalid.
+ */
+export async function encryptGCMBytes(plaintext: Uint8Array, rawKey: Uint8Array): Promise<Uint8Array> {
+  const key = await importAesKey(rawKey, ["encrypt"]);
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+  const ciphertextBuffer = await globalThis.crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    key,
+    toOwnedArrayBuffer(plaintext)
+  );
+
+  const combined = new Uint8Array(iv.length + ciphertextBuffer.byteLength);
+  combined.set(iv);
+  combined.set(new Uint8Array(ciphertextBuffer), iv.length);
+
+  return combined;
+}
+
+/**
+ * Encrypts UTF-8 plaintext using AES-256-GCM.
+ *
+ * @param plaintext - Text payload to encrypt.
+ * @param rawKey - 32-byte symmetric key.
+ * @returns Combined buffer in `IV || ciphertext+tag` format.
+ * @throws {WorkerError} When key length is invalid.
+ */
+export async function encryptGCM(plaintext: string, rawKey: Uint8Array): Promise<Uint8Array> {
+  const plaintextBytes = textEncoder.encode(plaintext);
+  try {
+    return await encryptGCMBytes(plaintextBytes, rawKey);
+  } finally {
+    plaintextBytes.fill(0);
+  }
+}
+
+/**
+ * Decrypts a buffer in `IV || ciphertext+tag` format.
+ *
+ * Returns raw bytes so high-sensitivity callers can zero the decrypted buffer immediately after
+ * parsing, instead of leaving plaintext in immutable JS string storage.
+ *
+ * @param combined - Combined encrypted payload produced by `encryptGCM`.
+ * @param rawKey - 32-byte symmetric key.
+ * @returns Decrypted plaintext bytes.
+ * @throws {WorkerError} When key/ciphertext is invalid or integrity verification fails.
+ */
+export async function decryptGCMBytes(combined: Uint8Array, rawKey: Uint8Array): Promise<Uint8Array> {
+  assertAesKeyLength(rawKey);
+
+  if (combined.length < IV_LENGTH + 16) {
+    fail({
+      code: "CRYPTO_INVALID_CIPHERTEXT",
+      title: "Invalid ciphertext",
+      detail: "Invalid ciphertext. Too short to be a valid AES-GCM payload.",
+      category: "crypto",
+      retryable: false,
+    });
+  }
+
+  const crypto = globalThis.crypto;
+
+  const iv = combined.slice(0, IV_LENGTH);
+  const ciphertext = combined.slice(IV_LENGTH);
+
+  const key = await importAesKey(rawKey, ["decrypt"]);
+
+  let decryptBuffer: ArrayBuffer;
+  try {
+    decryptBuffer = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv },
+      key,
+      toOwnedArrayBuffer(ciphertext)
+    );
+  } catch (error) {
+    fail({
+      code: "CRYPTO_INTEGRITY_FAILURE",
+      title: "AES-GCM integrity verification failed",
+      detail: "Decryption failed because the ciphertext or auth tag was corrupted.",
+      category: "crypto",
+      retryable: false,
+      cause: error,
+    });
+  }
+
+  return new Uint8Array(decryptBuffer);
+}
+
+/**
+ * Decrypts a buffer in `IV || ciphertext+tag` format` and decodes it as UTF-8 text.
+ *
+ * Prefer `decryptGCMBytes` when handling raw PII so the caller can explicitly wipe the plaintext
+ * buffer after use.
+ *
+ * @param combined - Combined encrypted payload produced by `encryptGCM`.
+ * @param rawKey - 32-byte symmetric key.
+ * @returns Decrypted UTF-8 plaintext.
+ * @throws {WorkerError} When key/ciphertext is invalid or integrity verification fails.
+ */
+export async function decryptGCM(combined: Uint8Array, rawKey: Uint8Array): Promise<string> {
+  const decryptedBytes = await decryptGCMBytes(combined, rawKey);
+  try {
+    return textDecoder.decode(decryptedBytes);
+  } finally {
+    decryptedBytes.fill(0);
+  }
+}

package/src/modules/crypto/envelope.ts

@@ -0,0 +1,48 @@
+import { base64ToBytes } from "@/lib";
+import { decryptGCMBytes, encryptGCMBytes } from "./aes";
+
+const KEY_SIZE = 32;
+
+/**
+ * Generates a new random 32-byte data-encryption key.
+ *
+ * @returns Cryptographically secure DEK bytes.
+ */
+export function generateDEK(): Uint8Array {
+  const crypto = globalThis.crypto;
+  return crypto.getRandomValues(new Uint8Array(KEY_SIZE));
+}
+
+/**
+ * Wraps a DEK with the worker KEK.
+ *
+ * @param dek - Plain DEK bytes.
+ * @param kek - 32-byte KEK bytes.
+ * @returns Encrypted DEK blob.
+ */
+export async function wrapKey(dek: Uint8Array, kek: Uint8Array): Promise<Uint8Array> {
+  return encryptGCMBytes(dek, kek);
+}
+
+/**
+ * Unwraps a previously wrapped DEK with the worker KEK.
+ *
+ * @param wrappedKey - Encrypted DEK blob.
+ * @param kek - 32-byte KEK bytes.
+ * @returns Plain DEK bytes.
+ */
+export async function unwrapKey(wrappedKey: Uint8Array, kek: Uint8Array): Promise<Uint8Array> {
+  const decrypted = await decryptGCMBytes(wrappedKey, kek);
+  if (decrypted.length === KEY_SIZE) {
+    const dek = decrypted.slice();
+    decrypted.fill(0);
+    return dek;
+  }
+
+  try {
+    const legacyText = new TextDecoder().decode(decrypted);
+    return base64ToBytes(legacyText);
+  } finally {
+    decrypted.fill(0);
+  }
+}

package/src/modules/crypto/hmac.ts

@@ -0,0 +1,60 @@
+import { bytesToHex } from "@/lib";
+
+const textEncoder = new TextEncoder();
+
+function copyToOwnedBytes(bytes: Uint8Array): Uint8Array {
+  const owned = new Uint8Array(bytes.byteLength);
+  owned.set(bytes);
+  return owned;
+}
+
+/**
+ * Imports HMAC-SHA256 key material once for repeated pseudonymization operations.
+ *
+ * @param keyMaterial - Raw key bytes or a legacy string secret.
+ * @returns Web Crypto HMAC key suitable for repeated `sign` calls.
+ */
+export async function importHmacKey(keyMaterial: Uint8Array | string): Promise<CryptoKey> {
+  const rawKey = typeof keyMaterial === "string"
+    ? copyToOwnedBytes(textEncoder.encode(keyMaterial))
+    : copyToOwnedBytes(keyMaterial);
+  const keyBuffer = rawKey.buffer.slice(rawKey.byteOffset, rawKey.byteOffset + rawKey.byteLength) as ArrayBuffer;
+  return globalThis.crypto.subtle.importKey(
+    "raw",
+    keyBuffer,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+}
+
+/**
+ * Computes deterministic HMAC-SHA256 with a pre-imported Web Crypto key.
+ *
+ * @param input - Plain input string to sign.
+ * @param key - Pre-imported HMAC-SHA256 key.
+ * @returns Lowercase hex digest.
+ */
+export async function generateHMACWithKey(input: string, key: CryptoKey): Promise<string> {
+  const signature = await globalThis.crypto.subtle.sign(
+    "HMAC",
+    key,
+    textEncoder.encode(input)
+  );
+
+  return bytesToHex(new Uint8Array(signature));
+}
+
+/**
+ * Computes deterministic HMAC-SHA256 for worker pseudonymization and lookup keys.
+ *
+ * Prefer `importHmacKey` + `generateHMACWithKey` when signing many values in one request.
+ *
+ * @param input - Plain input string to sign.
+ * @param salt - HMAC key material (salt/secret).
+ * @returns Lowercase hex digest.
+ */
+export async function generateHMAC(input: string, salt: string): Promise<string> {
+  const key = await importHmacKey(salt);
+  return generateHMACWithKey(input, key);
+}

package/src/modules/crypto/index.ts

@@ -0,0 +1,3 @@
+export * from "./hmac";
+export * from "./aes";
+export * from "./envelope";

package/src/modules/db/drift.ts

@@ -0,0 +1,36 @@
+import type { Sql } from "@/types";
+import { assertIdentifier } from "@/utils";
+import { sha256HexDigest } from "@/lib";
+
+interface SchemaColumnRow {
+  table_name: string;
+  column_name: string;
+  data_type: string;
+}
+
+/**
+ * Computes a deterministic SHA-256 fingerprint of the live application schema.
+ *
+ * The signature is built from ordered `table_name + column_name + data_type` tuples.
+ *
+ * @param sql - Postgres pool or transaction used for metadata query.
+ * @param appSchema - Application schema to fingerprint.
+ * @returns Hex-encoded SHA-256 schema hash.
+ * @throws {WorkerError} When `appSchema` is not a safe SQL identifier.
+ */
+export async function detectSchemaDrift(sql: Sql, appSchema: string): Promise<string> {
+  const safeAppSchema = assertIdentifier(appSchema, "application schema name");
+
+  const columns = await sql<SchemaColumnRow[]>`
+    SELECT table_name, column_name, data_type
+    FROM information_schema.columns
+    WHERE table_schema = ${safeAppSchema}
+    ORDER BY table_name ASC, ordinal_position ASC, column_name ASC
+  `;
+
+  const signature = columns.map(
+    (column) => `${column.table_name}${column.column_name}${column.data_type}`)
+    .join("");
+
+  return sha256HexDigest(signature)
+}

package/src/modules/db/graph.ts

@@ -0,0 +1,203 @@
+/**
+ * Dependency-graph discovery using PostgreSQL catalog metadata and recursive CTE traversal.
+ */
+
+import { assertIdentifier, quoteQualifiedIdentifier } from "@/utils";
+import { fail } from "@/errors";
+import type { SqlExecutor } from "@/types";
+
+export interface DependencyNode {
+  table_schema: string;
+  table_name: string;
+  column_name: string;
+  parent_table: string;
+  delete_action: "NO_ACTION" | "RESTRICT" | "CASCADE" | "SET_NULL" | "SET_DEFAULT" | "UNKNOWN";
+  depth: number;
+}
+
+export interface DependencyGraphOptions {
+  maxDepth?: number;
+  failOnUnsafeDeleteAction?: boolean;
+}
+
+const DEFAULT_MAX_DEPTH = 32;
+const UNSAFE_DELETE_ACTIONS = new Set(["CASCADE", "SET_NULL", "SET_DEFAULT"]);
+
+function normalizeDeleteAction(value: string): DependencyNode["delete_action"] {
+  switch (value) {
+    case "a":
+      return "NO_ACTION";
+    case "r":
+      return "RESTRICT";
+    case "c":
+      return "CASCADE";
+    case "n":
+      return "SET_NULL";
+    case "d":
+      return "SET_DEFAULT";
+    default:
+      return "UNKNOWN";
+  }
+}
+
+function resolveMaxDepth(input?: number): number {
+  if (input === undefined) {
+    return DEFAULT_MAX_DEPTH;
+  }
+
+  if (!Number.isInteger(input) || input < 1) {
+    fail({
+      code: "GRAPH_MAX_DEPTH_INVALID",
+      title: "Invalid graph max depth",
+      detail: "maxDepth must be an integer greater than 0.",
+      category: "validation",
+      retryable: false,
+    });
+  }
+
+  return input;
+}
+
+/**
+ * Discovers the transitive foreign-key dependency graph for a root table.
+ *
+ * The recursive CTE tracks visited OIDs to prevent cyclic loops, fails closed when the configured
+ * depth limit is reached, and rejects FK actions that would silently delete or rewrite dependent
+ * records outside the worker's explicit vault/redaction logic.
+ *
+ * @param sql - Postgres pool or active transaction.
+ * @param schema - Root table schema.
+ * @param rootTable - Root table name.
+ * @param options - Optional traversal controls.
+ * @returns Ordered dependency nodes containing table/column lineage metadata.
+ * @throws {WorkerError} When root table is missing, depth is invalid, unsafe FK actions are present,
+ * or the traversal depth limit is reached.
+ */
+export async function getDependencyGraph(
+  sql: SqlExecutor,
+  schema: string,
+  rootTable: string,
+  options: DependencyGraphOptions = {}
+): Promise<DependencyNode[]> {
+  const safeSchema = assertIdentifier(schema, "schema name");
+  const safeRootTable = assertIdentifier(rootTable, "table name");
+  const maxDepth = resolveMaxDepth(options.maxDepth);
+  const qualifiedRoot = quoteQualifiedIdentifier(safeSchema, safeRootTable);
+
+  const [rootExists] = await sql<{ oid: string | null }[]>`
+    SELECT to_regclass(${qualifiedRoot})::text AS oid
+  `;
+
+  if (!rootExists?.oid) {
+    fail({
+      code: "GRAPH_ROOT_TABLE_MISSING",
+      title: "Root table not found",
+      detail: `Root table ${safeSchema}.${safeRootTable} does not exist.`,
+      category: "validation",
+      retryable: false,
+      context: { schema: safeSchema, rootTable: safeRootTable },
+    });
+  }
+
+  const result = await sql<
+    Array<
+      Omit<DependencyNode, "delete_action"> & {
+        delete_action_code: string;
+        table_oid: number;
+        reached_limit: boolean;
+      }
+    >
+  >`
+    WITH RECURSIVE dependency_tree AS (
+      SELECT
+        connamespace::regnamespace::text AS table_schema,
+        conrelid::regclass::text AS table_name,
+        a.attname AS column_name,
+        confrelid::regclass::text AS parent_table,
+        c.confdeltype::text AS delete_action_code,
+        conrelid::oid AS table_oid,
+        ARRAY[confrelid::oid, conrelid::oid] AS path,
+        1 AS depth,
+        FALSE AS reached_limit
+      FROM pg_constraint c
+      JOIN pg_attribute a
+        ON a.attrelid = c.conrelid
+       AND a.attnum = ANY(c.conkey)
+      WHERE c.contype = 'f'
+        AND c.confrelid = to_regclass(${qualifiedRoot})
+
+      UNION ALL
+
+      SELECT
+        child.connamespace::regnamespace::text AS table_schema,
+        child.conrelid::regclass::text AS table_name,
+        a.attname AS column_name,
+        child.confrelid::regclass::text AS parent_table,
+        child.confdeltype::text AS delete_action_code,
+        child.conrelid::oid AS table_oid,
+        dt.path || child.conrelid::oid AS path,
+        dt.depth + 1 AS depth,
+        dt.depth + 1 >= ${maxDepth} AS reached_limit
+      FROM pg_constraint child
+      JOIN pg_attribute a
+        ON a.attrelid = child.conrelid
+       AND a.attnum = ANY(child.conkey)
+      JOIN dependency_tree dt
+        ON child.confrelid = dt.table_oid
+      WHERE child.contype = 'f'
+        AND dt.depth < ${maxDepth}
+        AND NOT child.conrelid::oid = ANY(dt.path)
+    )
+    SELECT DISTINCT ON (table_name, column_name)
+      table_schema,
+      table_name,
+      column_name,
+      parent_table,
+      delete_action_code,
+      depth,
+      table_oid,
+      reached_limit
+    FROM dependency_tree
+    ORDER BY table_name, column_name, depth ASC
+  `;
+
+  const graph = result.map(({ table_oid: _tableOid, reached_limit: _reachedLimit, delete_action_code, ...node }) => ({
+    ...node,
+    delete_action: normalizeDeleteAction(delete_action_code),
+  }));
+
+  if (options.failOnUnsafeDeleteAction !== false) {
+    const unsafe = graph.find((node) => UNSAFE_DELETE_ACTIONS.has(node.delete_action));
+    if (unsafe) {
+      fail({
+        code: "GRAPH_UNSAFE_DELETE_ACTION",
+        title: "Unsafe foreign-key delete action detected",
+        detail: `Foreign key ${unsafe.table_name}.${unsafe.column_name} uses ON DELETE ${unsafe.delete_action}; the worker refuses to run because Postgres could mutate dependent data outside the explicit erasure plan.`,
+        category: "integrity",
+        retryable: false,
+        fatal: true,
+        context: {
+          schema: safeSchema,
+          rootTable: safeRootTable,
+          table: unsafe.table_name,
+          column: unsafe.column_name,
+          deleteAction: unsafe.delete_action,
+        },
+      });
+    }
+  }
+
+  if (result.some((row) => row.depth >= maxDepth || row.reached_limit)) {
+    fail({
+      code: "GRAPH_DEPTH_LIMIT_REACHED",
+      title: "Dependency graph depth limit reached",
+      detail: `Dependency graph for ${safeSchema}.${safeRootTable} reached the safety limit of ${maxDepth}. Increase maxDepth before running destructive operations.`,
+      category: "integrity",
+      retryable: false,
+      fatal: true,
+      context: { schema: safeSchema, rootTable: safeRootTable, maxDepth },
+    });
+  }
+
+  return graph;
+}

package/src/modules/db/index.ts

@@ -0,0 +1,4 @@
+export * from "./migrations";
+export * from "./sql-debug";
+export * from "./drift";
+export * from "./graph";