dpdp-erasure-cli 1.0.0

package/src/secrets/resolvers.ts

@@ -0,0 +1,247 @@
+import { CODE, fail } from "@/errors";
+import type { EnvType } from "@/types";
+import { base64ToBytes } from "@/lib";
+import { type KeySourceConfig, signAwsKmsRequest } from "./kms";
+import { readLegacyEnvKey, readRuntimeSecret } from "./reader";
+import { decodeKeyMaterial, encodeVaultPathSegment, fetchJson, isRecord, normalizeBase64 } from "./repository";
+
+export interface ResolveKeyOptions {
+  env: EnvType
+  keyName: string;
+  legacyEnvName: string;
+  fallbackLegacyEnvName?: string;
+  source?: KeySourceConfig;
+  fetchFn?: typeof fetch;
+}
+
+async function requiredRuntimeSecret(
+  env: EnvType,
+  envName: string,
+  purpose: string
+): Promise<string> {
+  const value = await readRuntimeSecret(env, envName);
+  if (!value) {
+    fail({
+      code: CODE.KMS_SECRET_MISSING,
+      detail: `${envName} is required to resolve ${purpose}.`,
+      context: { envName, purpose },
+    });
+  }
+
+  return value;
+}
+
+/**
+ * Resolves a configured key source using only synchronous local sources.
+ *
+ * @param options - Key lookup contract and runtime environment map.
+ * @returns A 32-byte key resolved from env or file.
+ * @throws {WorkerError} If a remote key provider is configured on the sync path.
+ */
+export async function resolveConfiguredKeyAsync(options: ResolveKeyOptions): Promise<Uint8Array> {
+  const source = options.source;
+  if (!source) {
+    return readLegacyEnvKey(options);
+  }
+
+  if (source.provider === "env") {
+    return decodeKeyMaterial(
+      await requiredRuntimeSecret(
+        options.env,
+        source.env,
+        options.keyName
+      ), options.keyName
+    );
+  }
+
+  if (source.provider === "file") {
+    const rawKey = (await Bun.file(source.path).text()).trim();
+    return decodeKeyMaterial(rawKey, options.keyName)
+  }
+  fail({
+    code: "KMS_ASYNC_PROVIDER_ON_SYNC_PATH",
+    title: "Remote key provider requires async boot",
+    detail: `${source.provider} key sources require readWorkerConfigFromRuntime().`,
+    category: "configuration",
+    retryable: false,
+    fatal: true,
+    context: { provider: source.provider, keyName: options.keyName }
+  })
+}
+
+async function resolveAwsKmsKey(
+  source: Extract<KeySourceConfig, { provider: "aws_kms" }>,
+  options: ResolveKeyOptions
+): Promise<Uint8Array> {
+  const fetchFn = options.fetchFn ?? globalThis.fetch;
+  const endpoint = new URL(source.endpoint ?? `https://kms.${source.region}.amazonaws.com/`);
+  const body = JSON.stringify({
+    CiphertextBlob: source.ciphertext_blob_base64,
+    ...(source.key_id ? { KeyId: source.key_id } : {}),
+    ...(source.encryption_context ? { EncryptionContext: source.encryption_context } : {}),
+  });
+  const headers = await signAwsKmsRequest(endpoint, source.region, body, {
+    accessKeyId: await requiredRuntimeSecret(options.env,
+      source.access_key_id_env,
+      options.keyName
+    ),
+    secretAccessKey: await requiredRuntimeSecret(
+      options.env,
+      source.secret_access_key_env,
+      options.keyName
+    ),
+    sessionToken: await readRuntimeSecret(
+      options.env,
+      source.session_token_env
+    ) || undefined,
+  });
+
+  const json = await fetchJson(fetchFn, endpoint, { method: "POST", headers, body }, "AWS KMS");
+  if (!isRecord(json) || typeof json.Plaintext !== "string") {
+    fail({
+      code: CODE.KMS_RESPONSE_INVALID,
+      detail: "AWS KMS response did not include a base64 Plaintext field.",
+      context: { provider: "aws_kms" },
+    });
+  }
+
+  return decodeKeyMaterial(base64ToBytes(normalizeBase64(json.Plaintext)), options.keyName);
+}
+
+async function resolveGcpToken(
+  source: Extract<KeySourceConfig, { provider: "gcp_secret_manager" }>,
+  options: ResolveKeyOptions
+): Promise<string> {
+  const envToken = await readRuntimeSecret(options.env, source.access_token_env)
+  if (envToken) return envToken;
+
+  const json = await fetchJson(
+    options.fetchFn ?? globalThis.fetch,
+    source.metadata_token_url,
+    {
+      method: "GET",
+      headers: {
+        "metadata-flavor": "Google",
+      },
+    },
+    "GCP metadata server"
+  );
+
+  if (!isRecord(json) || typeof json.access_token !== "string") {
+    fail({
+      code: CODE.KMS_RESPONSE_INVALID,
+      detail: "GCP metadata token response did not include access_token.",
+      context: { provider: "gcp_metadata" },
+    })
+  }
+
+  return json.access_token;
+}
+
+async function resolveGcpSecretManagerKey(
+  source: Extract<KeySourceConfig, { provider: "gcp_secret_manager" }>,
+  options: ResolveKeyOptions
+): Promise<Uint8Array> {
+  const fetchFn = options.fetchFn ?? globalThis.fetch;
+  const endpoint = source.endpoint ?? `https://secretmanager.googleapis.com/v1/${source.secret_version}:access`
+  const accessToken = await resolveGcpToken(source, options);
+  const json = await fetchJson(
+    fetchFn,
+    endpoint,
+    {
+      method: "GET",
+      headers: {
+        authorization: `Bearer ${accessToken}`
+      },
+    },
+    "GCP Secret Manager"
+  );
+
+  const payload = isRecord(json) && isRecord(json.payload) ? json.payload : null;
+  if (!payload || typeof payload.data !== "string") {
+    fail({
+      code: CODE.KMS_RESPONSE_INVALID,
+      detail: "GCP Secret Manager response did not include payload.data.",
+      context: { provider: "gcp_secret_manager" },
+    });
+  }
+
+  return decodeKeyMaterial(base64ToBytes(normalizeBase64(payload.data)), options.keyName);
+}
+
+
+async function resolveVaultKey(
+  source: Extract<KeySourceConfig, { provider: "hashicorp_vault" }>,
+  options: ResolveKeyOptions
+): Promise<Uint8Array> {
+  const fetchFn = options.fetchFn ?? globalThis.fetch;
+  const address = source.address ?? await readRuntimeSecret(options.env, source.address_env);
+  if (!address) {
+    fail({
+      code: CODE.KMS_SECRET_MISSING,
+      detail: `${source.address_env} or security key source address is required to resolve ${options.keyName}.`,
+      context: { provider: "hashicorp_vault", addressEnv: source.address_env },
+    });
+  }
+
+  const url = new URL(
+    `/v1/${encodeVaultPathSegment(source.mount)}/data/${encodeVaultPathSegment(source.path)}`,
+    address.endsWith("/") ? address : `${address}/`
+  );
+  if (source.version !== undefined) {
+    url.searchParams.set("version", String(source.version));
+  }
+
+  const headers = new Headers({
+    "x-vault-token": await requiredRuntimeSecret(options.env, source.token_env, options.keyName),
+  });
+  const namespace = await readRuntimeSecret(options.env, source.namespace_env);
+  if (namespace) {
+    headers.set("x-vault-namespace", namespace);
+  }
+
+  const json = await fetchJson(
+    fetchFn,
+    url,
+    { method: "GET", headers },
+    "HashiCorp Vault");
+  const data = isRecord(json) && isRecord(json.data) && isRecord(json.data.data) ? json.data.data : null;
+  const rawValue = data?.[source.field];
+  if (typeof rawValue !== "string") {
+    fail({
+      code: CODE.KMS_RESPONSE_INVALID,
+      detail: `HashiCorp Vault response did not include data.data.${source.field}.`,
+      context: { provider: "hashicorp_vault", field: source.field },
+    });
+  }
+
+  return decodeKeyMaterial(rawValue, options.keyName);
+};
+
+/**
+ * Resolves a configured key source from env, file, AWS KMS, GCP Secret Manager, or Vault KV v2.
+ *
+ * @param options - Key lookup contract and runtime environment map.
+ * @returns A 32-byte key suitable for Web Crypto operations.
+ * @throws {WorkerError} If retrieval fails or the provider returns invalid key material.
+ */
+export async function resolveConfiguredKey(options: ResolveKeyOptions): Promise<Uint8Array> {
+  const source = options.source;
+  if (!source) {
+    return readLegacyEnvKey(options);
+  }
+
+  if (source.provider === "env" || source.provider === "file") {
+    return resolveConfiguredKeyAsync(options);
+  }
+
+  if (source.provider === "aws_kms") {
+    return resolveAwsKmsKey(source, options);
+  }
+
+  if (source.provider === "gcp_secret_manager") {
+    return resolveGcpSecretManagerKey(source, options);
+  }
+
+  return resolveVaultKey(source, options);
+}

package/src/secrets/signature.ts

@@ -0,0 +1,78 @@
+import { fail } from "../errors";
+import { readRuntimeSecret } from "./reader";
+import { base64ToBytes } from "@/lib";
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const copy = new Uint8Array(bytes.length);
+  copy.set(bytes);
+  return copy.buffer as ArrayBuffer;
+}
+
+/**
+ * Verifies an optional detached Ed25519 signature for `compliance.worker.yml`.
+ *
+ * When no public key is configured the check is skipped. When a public key is configured, the
+ * worker fails closed unless the detached signature exists and verifies successfully.
+ *
+ * @param env - Runtime environment map.
+ * @param configPath - Path to the worker YAML manifest.
+ * @throws {WorkerError} When the signature is required but missing or invalid.
+ */
+export async function verifySignedWorkerConfig(
+  env: Record<string, string | undefined>,
+  configPath: string | URL
+): Promise<void> {
+  const publicKeySpkiBase64 = await readRuntimeSecret(
+    env,
+    "CONFIG_SIGNING_PUBLIC_KEY_SPKI_BASE64"
+  );
+  if (!publicKeySpkiBase64) {
+    return;
+  }
+
+  const signaturePath = env.DPDP_CONFIG_SIGNATURE_PATH ?? `${String(configPath)}.sig`;
+  let signatureBase64: string;
+  try {
+    signatureBase64 = (await Bun.file(signaturePath).text()).trim();
+  } catch (error) {
+    fail({
+      code: "CONFIG_SIGNATURE_MISSING",
+      title: "Missing worker config signature",
+      detail: `Detached config signature ${signaturePath} is required when config signing is enabled.`,
+      category: "configuration",
+      retryable: false,
+      fatal: true,
+      cause: error,
+    });
+  }
+
+  const publicKey = await globalThis.crypto.subtle.importKey(
+    "spki",
+    toArrayBuffer(base64ToBytes(await publicKeySpkiBase64)),
+    { name: "Ed25519" },
+    false,
+    ["verify"]
+  );
+  const configBytes = new Uint8Array(await Bun.file(configPath).arrayBuffer());
+  const verified = await globalThis.crypto.subtle.verify(
+    "Ed25519",
+    publicKey,
+    toArrayBuffer(base64ToBytes(signatureBase64)),
+    toArrayBuffer(configBytes)
+  );
+
+  if (!verified) {
+    fail({
+      code: "CONFIG_SIGNATURE_INVALID",
+      title: "Invalid worker config signature",
+      detail: `Detached config signature ${signaturePath} failed verification.`,
+      category: "integrity",
+      retryable: false,
+      fatal: true,
+      context: {
+        configPath: String(configPath),
+        signaturePath,
+      },
+    });
+  }
+}

package/src/types/index.ts

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

package/src/types/types.ts

@@ -0,0 +1,23 @@
+import type postgres from "postgres";
+
+export type EnvType = Record<string, string | undefined>;
+
+export type Tsql = postgres.TransactionSql;
+
+export type Sql = postgres.Sql;
+
+export type SqlExecutor = postgres.TransactionSql | postgres.Sql;
+
+/**
+ * Safely replaces existing properties in a type with new definitions.
+ * Prevents TypeScript conflicts by removing the old field before applying the new one.
+ * 
+ * @example
+ * type User = { id: number; name: string; role: string };
+ * 
+ * type AdminUser = Override<User, { 
+ *   id: string; 
+ *   role: "admin" | "superadmin"; 
+ * }>;
+ */
+export type Override<T, R> = Omit<T, keyof R> & R;

package/src/utils/identifiers.ts

@@ -0,0 +1,48 @@
+import { fail } from "@/errors";
+
+const IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+/**
+ * Validates an identifier used in dynamic SQL fragments.
+ * 
+ * @param name - Candidate identifier.
+ * @param label - Human readable label used in validtation errors.
+ * @returns Unchanged identifier when valid.
+ * @throws {WorkerError} When `name` contains unsafe characters.
+ */
+export function assertIdentifier(name: string, label: string): string {
+  if (!IDENTIFIER_PATTERN.test(name)) {
+    fail({
+      code: "IDENTIFIER_INVALID",
+      title: "Invalid identifier",
+      detail: `Invalid ${label}: "${name}". Only letters, numbers, and underscores are allowed.`,
+      category: "validation",
+      retryable: false,
+      context: { label },
+    });
+  };
+  return name;
+}
+
+/**
+ * Quotes and escapes one SQL identifier.
+ *
+ * @param name - Untrusted identifier text.
+ * @returns Safe quoted identifier.
+ */
+export function quoteIdentifier(name: string): string {
+  return `"${name.replace(/"/g, "\"\"")}"`;
+}
+
+/**
+ * Quotes a `schema.table` pair after validating both identifiers.
+ *
+ * @param schema - Schema identifier.
+ * @param table - Table identifier.
+ * @returns Fully qualified quoted identifier string.
+ * @throws {WorkerError} When either identifier is invalid.
+ */
+export function quoteQualifiedIdentifier(schema: string, table: string): string {
+  return `${quoteIdentifier(assertIdentifier(schema, "schema name"))}.${quoteIdentifier(assertIdentifier(table, "table name"))}`;
+}
+

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export * from "./identifiers";
+export * from "./logger";
+export * from "./json";

package/src/utils/json.ts

@@ -0,0 +1,35 @@
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+function sortJson(value: JsonValue): JsonValue {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJson(item));
+  }
+
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort((left, right) => left.localeCompare(right))
+        .map((key) => [key, sortJson((value as Record<string, JsonValue>)[key]!)])
+    );
+  }
+
+  return value;
+}
+
+
+/**
+ * Serializes unknown input into deterministic JSON text by sorting object keys recursively.
+ *
+ * Non-JSON values are first normalized using native `JSON.stringify` semantics, then canonicalized.
+ */
+export function canonicalJsonStringify(value: unknown): string {
+  const firstPass = JSON.stringify(value);
+  if (firstPass === undefined) {
+    throw new TypeError("Value is not JSON-serializable.");
+  }
+
+  const parsed = JSON.parse(firstPass) as JsonValue;
+  return JSON.stringify(sortJson(parsed));
+}
+

package/src/utils/logger.ts

@@ -0,0 +1,161 @@
+import pino, { type DestinationStream, type Logger } from "pino";
+import { asWorkerError } from "@/errors";
+
+export interface LoggerBindings {
+  [key: string]: string
+};
+
+const REDACTED_PATHS = [
+  "authorization",
+  "*.authorization",
+  "headers.authorization",
+  "req.headers.authorization",
+  "apiToken",
+  "*.apiToken",
+  "token",
+  "*.token",
+  "masterKey",
+  "*.masterKey",
+  "hmacKey",
+  "*.hmacKey",
+  "kek",
+  "*.kek",
+  "encrypted_pii",
+  "*.encrypted_pii",
+  "encrypted_pii.data",
+  "*.encrypted_pii.data",
+  "encrypted_dek",
+  "*.encrypted_dek",
+  "payload.data",
+  "*.payload.data",
+  "payload.email",
+  "*.payload.email",
+  "payload.full_name",
+  "*.payload.full_name",
+  "email",
+  "*.email",
+  "full_name",
+  "*.full_name",
+];
+
+function serializeErrorForLog(error: unknown) {
+  const normalizedError = asWorkerError(error);
+  return {
+    ...normalizedError.toProblem(),
+    stack: normalizedError.stack,
+  };
+};
+
+/**
+ * Creates a Pino logger configured for worker-safe redaction and structured error serialization.
+ * 
+ * @param bindings - Optional static bindings merged into every log record.
+ * @param destination - Optional Pino destination stream.
+ * @returns Configured Pino logger instance.
+ */
+export function createWorkerLogger(
+  bindings: LoggerBindings = {},
+  destination?: DestinationStream
+): Logger {
+  const instance = pino(
+    {
+      level: process.env.LOG_LEVEL ?? "info",
+      messageKey: "message",
+      timestamp: pino.stdTimeFunctions.isoTime,
+      base: {
+        service: "compliance-worker",
+        plane: "data"
+      },
+      redact: {
+        paths: REDACTED_PATHS,
+        censor: "[REDACTED]",
+      },
+      formatters: {
+        level: (label) => ({ level: label })
+      },
+      serializers: {
+        err: serializeErrorForLog
+      },
+    },
+    destination
+  )
+  return Object.keys(bindings).length > 0 ? instance.child(bindings) : instance;
+}
+
+export const logger = createWorkerLogger();
+
+/**
+ * Returns a child logger bound to contextual fields.
+ * 
+ * @param bindings - Context bindings added to each emitted record.
+ * @returns Child logger.
+ */
+export function getLogger(bindings: LoggerBindings): Logger {
+  return logger.child(bindings);
+}
+
+/**
+ * Logs and normalizes unknown errors using standardized worker error envelopes.
+ *
+ * @param loggerInstance - Logger to emit to.
+ * @param error - Unknown error value.
+ * @param message - Log message.
+ * @param bindings - Additional structured context.
+ * @returns Normalized `WorkerError`.
+ */
+export function logError(
+  loggerInstace: Logger,
+  error: unknown,
+  message: string,
+  bindings: LoggerBindings = {}
+) {
+  const normalizedError = asWorkerError(error);
+  const level = normalizedError.fatal ? "fatal" : normalizedError.retryable ? "warn" : "fatal"
+  loggerInstace[level]({ ...bindings, err: normalizedError });
+  return normalizedError;
+}
+
+function terminate(logger: Logger, error: unknown, code: number) {
+  const normalized = asWorkerError(error, {
+    code: "RUNTIME_FATAL",
+    title: "Fatal runtime error",
+    detail: "A fatal runtime error reached the process boundary.",
+    category: "runtime",
+    fatal: true,
+  });
+  logError(logger, normalized, "Fatal runtime error reached process boundary");
+  process.exit(code);
+}
+
+/**
+ * Registers process-level fatal guards for unhandled rejections and uncaught exceptions.
+ * 
+ * @param logger - Root logger used to emit terminal failure diagnostics.
+ * @returns vaild; installs listners on `process`.
+ */
+export function registerProcessGuard(logger: Logger) {
+  process.on("unhandledRejection", (reason) => {
+    terminate(logger, asWorkerError(reason, {
+      code: "RUNTIME_UNHANDLED_REJECTION",
+      title: "Unhandled promise rejections",
+      detail: "An unhandled promise rejection reach the process boundary.",
+      category: "runtime",
+      retryable: false,
+      fatal: true,
+    }), 1)
+  });
+
+  process.on("uncaughtException", (error) => {
+    terminate(logger, asWorkerError(error, {
+      code: "RUNTIME_UNCAUGHT_EXCEPTION",
+      title: "Uncaught exception",
+      detail: "An uncaught exception reached the process boundary.",
+      category: "runtime",
+      retryable: false,
+      fatal: true,
+    }), 1);
+  })
+}
+
+export const workerLogger = getLogger({ component: "worker" });
+export const outboxLogger = getLogger({ component: "outbox" });

package/src/validation/zod.ts

@@ -0,0 +1,70 @@
+import type { ZodError } from "zod";
+import type { $ZodIssue } from "zod/v4/core";
+
+/**
+ * Structured worker-side validation issue retained in problem details and log
+ */
+export interface WorkerValidationIssue {
+  path: string;
+  param: string;
+  code: string;
+  message: string;
+};
+
+function formatIssuePath(path: PropertyKey[]): string {
+  if (path.length === 0) {
+    return "<root>";
+  };
+
+  return path.reduce<string>((accumulator, segment) => {
+    if (typeof segment === "number") {
+      return `${accumulator}[${segment}]`;
+    }
+
+    return accumulator.length > 0 ? `${accumulator}.${String(segment)}` : String(segment);
+
+  }, "");
+}
+
+function toValidateIssue(issue: $ZodIssue) {
+  const path = formatIssuePath(issue.path);
+  return {
+    path,
+    param: path,
+    code: issue.code,
+    message: issue.message
+  };
+}
+
+/**
+ * Converts a Zod validation error into a deterministic issue list for worker diagnostics.
+ *
+ * @param error - Validation error raised by worker configuration or protocol parsing.
+ * @returns Flat issue list with normalized parameter paths and messages.
+ */
+export function formatZodIssues(error: ZodError) {
+  return error.issues.map(toValidateIssue);
+};
+
+/**
+ * Produces a compact summary for worker validation failures while preserving the full issue list.
+ *
+ * @param error - Validation error to summarize.
+ * @returns Human-readable summary for `WorkerProblemDetails.detail`.
+ */
+export function summarizeZodError(error: ZodError): string {
+  const issues = formatZodIssues(error);
+  if (issues.length === 0) {
+    return "Worker validation failed.";
+  };
+
+  if (issues.length === 1) {
+    const issue = issues[0];
+    if (!issue) {
+      return "Worker validation failed.";
+    };
+    return `${issue.param}: ${issue.message}`;
+  };
+
+  return `Worker validation failed with ${issues.length} issue(s)`;
+};