dpdp-erasure-cli 1.0.0

package/src/errors/worker.ts

@@ -0,0 +1,161 @@
+import type {
+  WorkerErrorCategory,
+  WorkerErrorCode,
+  WorkerErrorContext,
+  WorkerErrorOptions,
+  WorkerProblemDetails,
+  WorkerErrorFallback
+} from "./types";
+import { formatZodIssues, type WorkerValidationIssue } from "@/validation/zod";
+import {
+  inferCategory,
+  inferCode,
+  inferDetail,
+  inferFatal,
+  inferRetryability,
+  inferTitle
+} from "./inferer";
+import { ZodError } from "zod";
+
+function buildCause(cause: unknown): Error | undefined {
+  if (cause == null) return undefined;
+  if (cause instanceof Error) return cause;
+
+  return new Error(typeof cause === "string" ? cause : JSON.stringify(cause));
+}
+
+export function normalizeErrorType(code: WorkerErrorCode): string {
+  return `urn:dpdp:worker:error:${code.toLowerCase().replace(/^dpdp_/, "")}`;
+}
+
+/**
+ * WorkerError envelope mapped to RFC-7807-compatible problem details.
+ */
+export class WorkerError extends Error {
+  readonly type: string;
+  readonly code: WorkerErrorCode;
+  readonly title: string;
+  readonly detail: string;
+  readonly category: WorkerErrorCategory;
+  readonly retryable: boolean;
+  readonly fatal: boolean;
+  readonly context?: WorkerErrorContext | null;
+  readonly issues?: WorkerValidationIssue[] | null;
+
+  constructor(options: WorkerErrorOptions) {
+    const cause = buildCause(options.cause)
+    super(options.detail, { cause })
+
+    this.name = "WorkerError";
+    this.type = options.type ?? normalizeErrorType(options.code);
+    this.code = options.code;
+    this.title = options.title;
+    this.detail = options.detail;
+    this.category = options.category;
+    this.retryable = options.retryable ?? false;
+    this.fatal = options.fatal ?? false;
+    this.context = options.context ?? null;
+
+    /**
+    * Issue resolution:
+    * 1. Use explicitly provided issues.
+    * 2. If missing, check if the cause is a ZodError and format it.
+    * 3. Otherwise, null.
+    */
+    if (options.issues) {
+      this.issues = options.issues;
+    } else if (cause instanceof ZodError) {
+      this.issues = formatZodIssues(cause);
+    } else {
+      this.issues = null;
+    }
+  }
+
+  toProblem(instance?: string): WorkerProblemDetails {
+    const causeProblem = this.cause ? asWorkerError(this.cause).toProblem() : undefined;
+
+    const problem: WorkerProblemDetails = {
+      type: this.type,
+      code: this.code,
+      title: this.title,
+      detail: this.detail,
+      category: this.category,
+      retryable: this.retryable,
+      fatal: this.fatal,
+    };
+
+    if (instance) problem.instance = instance;
+    if (this.context) problem.context = this.context;
+    if (this.issues && this.issues.length > 0) problem.issues = this.issues;
+    if (causeProblem) problem.cause = causeProblem;
+
+    return problem;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isWorkerProblem(value: unknown): value is WorkerProblemDetails {
+  return isRecord(value) && typeof value.code === "string" && typeof value.detail === "string";
+}
+
+/**
+ * Constructs a normalized `WorkerError`
+ * 
+ * @param options - Error metadata and classification.
+ * @returns Worker error instance
+ */
+export function workerError(options: WorkerErrorOptions): WorkerError {
+  return new WorkerError(options)
+}
+
+/**
+ * Normalizes unknown error into `WorkerError`, applying fallback defaults when needed
+ * 
+ * @param error - Unknown thrown value.
+ * @param fallback - Optional fallback fields used when inference is ambiguous
+ * @returns Normalized Worker Error
+ */
+export function asWorkerError(error: unknown, fallback: WorkerErrorFallback = {}): WorkerError {
+  if (error instanceof WorkerError) return error;
+
+  if (isWorkerProblem(error)) {
+    return workerError({
+      code: error.code,
+      title: error.title,
+      detail: error.detail,
+      category: error.category,
+      retryable: error.retryable,
+      fatal: error.fatal,
+      context: error.context,
+      issues: error.issues,
+      cause: error.cause,
+      type: error.type,
+    });
+  };
+
+  return workerError({
+    code: inferCode(error, fallback),
+    title: inferTitle(error, fallback),
+    detail: inferDetail(error, fallback),
+    category: inferCategory(error, fallback),
+    retryable: inferRetryability(error, fallback),
+    fatal: inferFatal(error, fallback),
+    context: fallback.context,
+    issues: error instanceof ZodError ? (fallback.issues ?? formatZodIssues(error)) : fallback.issues,
+    cause: error instanceof Error ? error.cause : undefined
+  });
+};
+
+/**
+ * Serializes unknown errors into worker problem-details payload.
+ *
+ * @param error - Unknown thrown value.
+ * @param instance - Optional instance path/context identifier.
+ * @returns Structured worker problem details.
+ */
+export function serializeWorkerError(error: unknown, instance?: string): WorkerProblemDetails {
+  return asWorkerError(error).toProblem(instance);
+}

package/src/index.ts

@@ -0,0 +1,328 @@
+import postgres from "postgres";
+import { normalize } from "zod";
+import type { Sql } from "./types";
+import {
+  readWorkerConfigFromRuntime,
+  verifySignatureWorkerConfig,
+  assertConfigSchemaCompatibility,
+} from "./modules/config";
+import {
+  createRedactingSqlDebugLogger,
+  runMigrations
+} from "./modules/db";
+import {
+  assertSchemaIntegrity,
+  assertIndexPreflight
+} from "./modules/bootstrap";
+import { createFetchDispatcher, createS3Client, createControlPlaneApiClient } from "./modules/network";
+import { type MockMailer } from "./modules/engine";
+import { ComplianceWorker } from "./modules/worker";
+import { asWorkerError, workerError } from "./errors";
+import { getLogger, logError, registerProcessGuard } from "./utils";
+import { sha256HexDigest } from "./lib";
+import { readRuntimeSecret } from "./secrets";
+
+const logger = getLogger({ component: "bootstrap" });
+let workerBooted = false;
+let workerQuarantined = false;
+
+async function checkDatabaseHealth(sql: Sql): Promise<boolean> {
+  try {
+    await sql`SELECT 1`;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sleep(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function readPositiveIntegerEnv(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (!raw) {
+    return fallback;
+  }
+
+  const parsed = Number(raw);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function computeIdlePollDelayMs(emptyPolls: number, baseMs: number, maxMs: number): number {
+  const cappedExponent = Math.min(emptyPolls, 10);
+  const exponential = Math.min(baseMs * 2 ** cappedExponent, maxMs);
+  const jitter = Math.floor(globalThis.crypto.getRandomValues(
+    new Uint32Array(1))[0]! % Math.max(1, Math.floor(baseMs / 2)
+    ));
+  return Math.min(exponential + jitter, maxMs);
+}
+
+async function sendMailerWebhook(
+  url: string,
+  message: Parameters<MockMailer["sendEmail"]>[0],
+  timeoutMs: number
+): ReturnType<MockMailer["sendEmail"]> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(message),
+      signal: controller.signal,
+      redirect: "error",
+    });
+
+    if (!response.ok) {
+      throw workerError({
+        code: "MAILER_TRANSPORT_FAILED",
+        title: "Mailer transport failed",
+        detail: `MAILER_WEBHOOK_URL responded with HTTP ${response.status}.`,
+        category: "network",
+        retryable: response.status >= 500 || response.status === 429,
+        fatal: response.status >= 400 && response.status < 500 && response.status !== 429,
+      });
+    }
+
+    const providerMessageId = response.headers.get("x-message-id") ?? response.headers.get("x-provider-message-id");
+    return {
+      provider: new URL(url).hostname,
+      providerMessageId: providerMessageId ?? undefined,
+      metadata: {
+        status: response.status,
+      },
+    };
+  } catch (error) {
+    if (error instanceof DOMException && error.name === "AbortError") {
+      throw workerError({
+        code: "MAILER_TRANSPORT_TIMEOUT",
+        title: "Mailer transport timed out",
+        detail: `MAILER_WEBHOOK_URL did not respond within ${timeoutMs}ms.`,
+        category: "network",
+        retryable: true,
+        fatal: false,
+      });
+    }
+
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function main() {
+  registerProcessGuard(logger);
+  logger.info("Starting Compliance Worker");
+
+  const configPath = new URL("../compliance.worker.yaml", import.meta.url)
+  await verifySignatureWorkerConfig(process.env, configPath);
+  const file = await Bun.file(configPath).text();
+  const workerConfigHash = await sha256HexDigest(file);
+  const config = await readWorkerConfigFromRuntime(process.env, configPath);
+  const postgresDebug = (process.env.LOG_LEVEL ?? "info").toLowerCase() === "debug"
+    ? createRedactingSqlDebugLogger(logger, Object.keys(config.graph.root_pii_columns))
+    : undefined;
+
+  let sql: Sql | undefined;
+  let sqlReplica: Sql | undefined;
+
+  try {
+    sql = postgres(process.env.DB_URL ?? "postgres://postgres:postgres@localhost:5432/postgres", {
+      max: 10,
+      idle_timeout: 20,
+      connect_timeout: 10,
+      debug: postgresDebug
+    });
+
+    sqlReplica = config.database.replica_db_url
+      ? postgres(config.database.replica_db_url, {
+        max: 10,
+        idle_timeout: 20,
+        connect_timeout: 10,
+        debug: postgresDebug
+      })
+      : undefined
+
+    await runMigrations(sql, config.database.engine_schema)
+
+    const skipSchemaCheck = process.env.SKIP_SCHEMA_CHECK === "true";
+    if (skipSchemaCheck) {
+      logger.warn("Skipping schema integrity and compatibility checks as requested by SKIP_SCHEMA_CHECK=true");
+    } else {
+      try {
+        await assertSchemaIntegrity(
+          sql,
+          config.database.app_schema,
+          config.legal_attestation.schema_hash ?? config.integrity.expected_schema_hash
+        );
+        await assertConfigSchemaCompatibility(sql, config);
+        await assertIndexPreflight(sql, config);
+      } catch (error) {
+        const normalized = asWorkerError(error);
+        if (
+          normalized.code !== "SCHEMA_DRIFT_DETECTED" &&
+          normalized.code !== "CONFIG_SCHEMA_MISMATCH" &&
+          normalized.code !== "INDEX_PREFLIGHT_FAILED"
+        ) {
+          throw normalized;
+        }
+
+        workerQuarantined = true;
+        logger.error(
+          { code: normalized.code, detail: normalized.detail, context: normalized.context },
+          "Worker entered quarantine mode; mutation tasks will not be claimed until configuration/schema/indexes are repaired"
+        );
+      }
+    }
+
+    const workerClientId = process.env.API_CLIENT_ID ?? "worker-1";
+    const workerBearerToken = await readRuntimeSecret(process.env, "API_WORKER_TOKEN") || "worker-secret";
+    const requestSigningSecret = await readRuntimeSecret(process.env, "API_REQUEST_SIGNING_SECRET") || undefined;
+    const workerAuthHeaders = {
+      "x-client-id": workerClientId,
+      authorization: `Bearer ${workerBearerToken}`
+    } as const;
+
+    const pushOutboxEvent = createFetchDispatcher({
+      url: process.env.API_OUTBOX_URL ?? "http://localhost:3000/api/v1/worker/outbox",
+      token: workerBearerToken,
+      clientId: workerClientId,
+      requestSigningSecret,
+      timeoutMs: 10_000,
+    })
+
+    const mailerWebhookUrl = process.env.MAILER_WEBHOOK_URL;
+    if (!mailerWebhookUrl) {
+      throw workerError({
+        code: "MAILER_TRANSPORT_MISSING",
+        title: "Missing mailer transport",
+        detail: "MAILER_WEBHOOK_URL must be configured for production notice dispatch.",
+        category: "configuration",
+        retryable: false,
+        fatal: true,
+      });
+    }
+
+    const mailerTimeoutMs = Number(process.env.MAILER_TIMEOUT_MS ?? "10000");
+    const mailer: MockMailer = {
+      async sendEmail(message) {
+        await sendMailerWebhook(mailerWebhookUrl, message, mailerTimeoutMs);
+      },
+    };
+
+    const apiClient = createControlPlaneApiClient({
+      syncUrl: process.env.API_SYNC_URL ?? "http://localhost:3000/api/v1/worker/sync",
+      ackBaseUrl: process.env.API_BASE_URL ?? "http://localhost:3000/api/v1/worker/tasks",
+      workerAuthHeaders,
+      workerConfigHash,
+      workerConfigVersion: config.legal_attestation.configuration_version,
+      workerDpoIdentifier: config.legal_attestation.dpo_identifier,
+      pushOutboxEvent,
+      requestSigningSecret,
+      timeoutMs: 10_000,
+    });
+
+    const worker = new ComplianceWorker({
+      sql,
+      sqlReplica,
+      config,
+      secrets: { kek: config.masterKey, hmacKey: config.hmacKey },
+      apiClient,
+      mailer,
+      s3Client: config.blob_targets.length > 0 ? createS3Client() : undefined,
+      taskHeartbeatIntervalMs: readPositiveIntegerEnv("WORKER_TASK_HEARTBEAT_INTERVAL_MS", 30_000),
+    });
+
+    const metricsPort = Number(process.env.METRICS_PORT ?? "9466");
+
+    Bun.serve({
+      port: metricsPort,
+      fetch: async (request) => {
+        const url = new URL(request.url);
+        if (url.pathname === "/healthz") {
+          return new Response("ok", { status: 200 });
+        }
+
+        if (url.pathname === "/readyz") {
+          const ready = workerBooted && (await checkDatabaseHealth(sql!));
+          return new Response(ready ? "ready" : "not ready", {
+            status: ready ? 200 : 503,
+          });
+        }
+
+        return new Response("Not Found", { status: 404 });
+      },
+    });
+
+    workerBooted = true;
+    const pollBaseDelayMs = readPositiveIntegerEnv("WORKER_POLL_BASE_DELAY_MS", 1_000);
+    const pollMaxDelayMs = readPositiveIntegerEnv("WORKER_POLL_MAX_DELAY_MS", 30_000);
+    const taskConcurrency = readPositiveIntegerEnv("WORKER_TASK_CONCURRENCY", 1);
+    let emptyPolls = 0;
+
+    logger.info(
+      {
+        appSchema: config.database.app_schema,
+        engineSchema: config.database.engine_schema,
+        replicaEnabled: Boolean(sqlReplica),
+        metricsPort,
+        mailerTimeoutMs,
+        workerConfigHash,
+        workerConfigVersion: config.legal_attestation.configuration_version,
+        dpoIdentifier: config.legal_attestation.dpo_identifier,
+        quarantined: workerQuarantined,
+        pollBaseDelayMs,
+        pollMaxDelayMs,
+        taskConcurrency,
+      },
+      "DPDP Compliance Worker booted"
+    );
+
+    while (true) {
+      try {
+        const processedCount = workerQuarantined ? 0 : await worker.processTaskBatch(taskConcurrency);
+        const realy = await worker.flushOutbox();
+
+        if (processedCount > 0 || realy.claimed > 0) {
+          emptyPolls = 0;
+          continue;
+        }
+
+        const delayMs = computeIdlePollDelayMs(emptyPolls, pollBaseDelayMs, pollMaxDelayMs);
+        emptyPolls += 1;
+        await sleep(delayMs);
+
+      } catch (error) {
+        const normalized = logError(logger, error, "Worker loop iteration failed");
+        if (normalized.fatal) {
+          throw normalized;
+        }
+
+        await sleep(normalized.retryable
+          ? pollBaseDelayMs
+          : Math.min(pollMaxDelayMs, pollBaseDelayMs * 10)
+        );
+      }
+    }
+
+
+  } finally {
+    const shutdownTasks: Promise<unknown>[] = [];
+    if (sql) {
+      shutdownTasks.push(sql.end());
+    }
+    if (sqlReplica) {
+      shutdownTasks.push(sqlReplica.end());
+    }
+    await Promise.allSettled(shutdownTasks);
+  }
+};
+
+main().catch((error) => {
+  logError(logger, error, "Worker failed to start");
+  process.exit(1);
+});

package/src/lib/crypto/digest.ts

@@ -0,0 +1,22 @@
+const textEncoder = new TextEncoder();
+
+/**
+ * Converts binary data into lowercase hexadecimal representation.
+ * @param buffer - Input bytes.
+ * @returns Hex string.
+ */
+export function hexEncode(buffer: ArrayBuffer): string {
+  return Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Computes SHA-256 digest for UTF-8 text and returns lowercase hex.
+ * 
+ * @param input - Text payload to hash.
+ * @returns SHA-256 digest encoded as hex.
+ */
+export async function sha256HexDigest(input: string): Promise<string> {
+  const data = textEncoder.encode(input);
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", data);
+  return hexEncode(digest);
+}

package/src/lib/crypto/encoding.ts

@@ -0,0 +1,78 @@
+/**
+ * Web-native byte encoding helpers for Bun/Web Crypto code paths.
+ */
+
+function bytesToBinary(bytes: Uint8Array): string {
+  let output = "";
+  const chunkSize = 0x8000;
+
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    output += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize));
+  }
+
+  return output;
+}
+
+/**
+ * Encodes raw bytes as base64.
+ *
+ * @param bytes - Binary payload.
+ * @returns Base64 string.
+ */
+export function bytesToBase64(bytes: Uint8Array): string {
+  return btoa(bytesToBinary(bytes));
+}
+
+/**
+ * Decodes Base64 into raw bytes.
+ * 
+ * @param value - Base64 payload.
+ * @returns Decoded bytes.
+ * @throws {TypeError} when value is not valid Base64.
+ */
+export function base64ToBytes(value: string): Uint8Array {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+
+  return bytes;
+}
+
+/**
+ * Encodes raw bytes as lowercase hexadecimal.
+ *
+ * @param bytes - Binary payload.
+ * @returns Lowercase hex string.
+ */
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Decodes hexadecimal text into raw bytes
+ * 
+ * @param value - Hex payload
+ * @returns Decoded Bytes
+ * @throws {TypeError} When the input is not valid even-length hex.
+ */
+export function hexToBytes(value: string): Uint8Array {
+  if (value.length % 2 !== 0 || /[^0-9a-f]/i.test(value)) {
+    throw new TypeError("Invalid hexadecimal string.");
+  }
+
+  const bytes = new Uint8Array(value.length / 2)
+  for (let i = 0; i < value.length; i += 2) {
+    bytes[i / 2] = Number.parseInt(value.slice(i, i + 2), 16);
+  }
+
+  return bytes;
+}
+
+export function copyBytes(bytes: Uint8Array): Uint8Array {
+  const copy = new Uint8Array(bytes.length);
+  copy.set(bytes);
+  return copy as Uint8Array;
+}

package/src/lib/crypto/index.ts

@@ -0,0 +1,2 @@
+export * from "./digest";
+export * from "./encoding";

package/src/lib/index.ts

@@ -0,0 +1 @@
+export * from "./crypto";

package/src/modules/bootstrap/index.ts

@@ -0,0 +1,2 @@
+export * from "./preflight";
+export * from "./integrity";

package/src/modules/bootstrap/integrity.ts

@@ -0,0 +1,38 @@
+import type { Sql } from "@/types";
+import { detectSchemaDrift } from "@modules/db";
+import { fail } from "@/errors";
+
+/**
+ * Validates runtime schema fingerprint against the expected hash from worker configuration.
+ *
+ * @param sql - Postgres pool used to inspect `information_schema`.
+ * @param appSchema - Application schema expected by the worker.
+ * @param expectedSchemaHash - Expected SHA-256 schema fingerprint from config.
+ * @returns Detected schema hash when validation succeeds.
+ * @throws {WorkerError} When detected hash does not match expected hash.
+ */
+export async function assertSchemaIntegrity(
+  sql: Sql,
+  appSchema: string,
+  expectedSchemaHash: string
+): Promise<string> {
+  const detectedSchemaHash = await detectSchemaDrift(sql, appSchema);
+
+  if (detectedSchemaHash !== expectedSchemaHash) {
+    fail({
+      code: "SCHEMA_DRIFT_DETECTED",
+      title: "Schema drift detected",
+      detail: `Schema drift detected for ${appSchema}. Expected ${expectedSchemaHash}, received ${detectedSchemaHash}. Refusing to start.`,
+      category: "integrity",
+      retryable: false,
+      fatal: true,
+      context: {
+        appSchema,
+        expectedSchemaHash,
+        detectedSchemaHash,
+      },
+    });
+  }
+
+  return detectedSchemaHash;
+}