dpdp-erasure-cli 1.0.0

package/.env.example

@@ -0,0 +1,55 @@
+# Compliance Engine Worker / Introspector
+# The worker does need runtime configuration. In production, prefer Docker/Kubernetes secrets
+# and compliance.worker.yml over a local .env file. This file is for local development only.
+
+LOG_LEVEL=info
+
+# Client application database. This is the database inside the client's VPC/VPS.
+DATABASE_URL=postgres://dpdp:dpdp@127.0.0.1:55432/dpdp_local
+
+# Control Plane worker endpoints.
+API_CLIENT_ID=worker-1
+API_WORKER_TOKEN=replace-with-worker-token
+API_REQUEST_SIGNING_SECRET=replace-with-worker-request-signing-secret
+API_SYNC_URL=http://127.0.0.1:3000/api/v1/worker/sync
+API_BASE_URL=http://127.0.0.1:3000/api/v1/worker/tasks
+API_OUTBOX_URL=http://127.0.0.1:3000/api/v1/worker/outbox
+
+# Metrics and health server exposed by the worker.
+METRICS_PORT=9464
+
+# Legal notice delivery. Required for production notice dispatch.
+MAILER_WEBHOOK_URL=http://127.0.0.1:18080/mail
+MAILER_TIMEOUT_MS=10000
+
+# Local crypto material. For production, use compliance.worker.yml key sources:
+# env, file, aws_kms, gcp_secret_manager, or hashicorp_vault.
+DPDP_MASTER_KEY=replace-with-32-byte-base64-key
+DPDP_HMAC_KEY=replace-with-64-hex-or-base64-hmac-key
+
+# Optional signed worker config verification.
+DPDP_CONFIG_SIGNING_PUBLIC_KEY_SPKI_BASE64=
+DPDP_CONFIG_SIGNATURE_PATH=./compliance.worker.yml.sig
+
+# Optional AWS credentials for S3/blob purge and AWS KMS.
+# Prefer ECS/EC2 IAM roles in production.
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_SESSION_TOKEN=
+AWS_REGION=ap-south-1
+AWS_EC2_METADATA_DISABLED=true
+AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=
+AWS_CONTAINER_CREDENTIALS_FULL_URI=
+AWS_CONTAINER_AUTHORIZATION_TOKEN=
+AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE=
+
+# Optional Google Secret Manager provider.
+GCP_ACCESS_TOKEN=
+
+# Optional HashiCorp Vault provider.
+VAULT_ADDR=
+VAULT_TOKEN=
+VAULT_NAMESPACE=
+
+# Test runner override.
+TEST_DATABASE_URL=postgres://dpdp:dpdp@127.0.0.1:55432/dpdp_local

package/Dockerfile

@@ -0,0 +1,33 @@
+# syntax=docker/dockerfile:1.7
+
+ARG BUN_VERSION=1.3.12
+
+FROM oven/bun:${BUN_VERSION}-slim AS deps
+WORKDIR /workspace
+
+COPY . .
+RUN bun install --frozen-lockfile --production
+
+FROM oven/bun:${BUN_VERSION}-slim AS verify
+WORKDIR /workspace
+
+COPY . .
+RUN bun install --frozen-lockfile
+
+RUN bun run worker:typecheck
+
+FROM oven/bun:${BUN_VERSION}-slim AS runtime
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV METRICS_PORT=9464
+
+COPY --from=deps /workspace/node_modules /app/node_modules
+COPY --from=deps /workspace/package.json /app/package.json
+COPY --from=deps /workspace/tsconfig.json /app/tsconfig.json
+COPY apps/worker /app/apps/worker
+
+EXPOSE 9464
+
+WORKDIR /app/apps/worker
+ENTRYPOINT ["bun", "src/index.ts"]

package/compliance.worker.yaml

@@ -0,0 +1,64 @@
+# Example `compliance.worker.yaml`
+version: "1.0"
+database:
+  app_schema: "mock_app"
+  engine_schema: "dpdp_engine"
+
+compliance_policy:
+  default_retention_years: 0
+  notice_window_hours: 48
+  retention_rules:
+    - rule_name: "PMLA_FINANCIAL"
+      legal_citation: "Prevention of Money Laundering Act, 2002, Sec 12"
+      if_has_data_in:
+        - "transactions"
+        - "invoices"
+      retention_years: 10
+    - rule_name: "RBI_KYC"
+      legal_citation: "RBI KYC Directions, 2016, Sec 38"
+      if_has_data_in:
+        - "kyc_documents"
+      retention_years: 5
+
+graph:
+  root_table: "users"
+  root_id_column: "id"
+  max_depth: 32
+  notice_email_column: "email"
+  notice_name_column: "full_name"
+  root_pii_columns:
+    email: "HMAC"
+    full_name: "STATIC_MASK"
+
+satellite_targets:
+  - table: "marketing_leads"
+    lookup_column: "email"
+    action: "redact"
+    masking_rules:
+      email: "HMAC"
+      name: "STATIC_MASK"
+  - table: "system_audit_logs"
+    lookup_column: "user_identifier"
+    action: "hard_delete"
+
+blob_targets: []
+
+outbox:
+  batch_size: 10
+  lease_seconds: 60
+  max_attempts: 10
+  base_backoff_ms: 1000
+
+security:
+  notification_lease_seconds: 120
+  master_key_env: "DPDP_MASTER_KEY"
+  hmac_key_env: "DPDP_HMAC_KEY"
+
+integrity:
+  expected_schema_hash: "0000000000000000000000000000000000000000000000000000000000000000"
+
+legal_attestation:
+  dpo_identifier: "dpo-name@client.com"
+  configuration_version: "v1.2.0"
+  legal_review_date: "2026-04-20"
+  acknowledgment: "I confirm this configuration accurately reflects our data retention obligations under DPDP Sec 12."

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "dpdp-erasure-cli",
+  "version": "1.0.0",
+  "module": "index.ts",
+  "type": "module",
+  "bin": {
+    "dpdp-cli": "./src/modules/cli/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "cli": "bun src/modules/cli/index.ts",
+    "test": "vitest run --fileParallelism=false",
+    "test:ui": "vitest run --ui"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/js-yaml": "^4.0.9",
+    "@types/pino": "^7.0.5",
+    "@vitest/ui": "4.1.5",
+    "vitest": "^4.1.5"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.5.2",
+    "boxen": "^8.0.1",
+    "cli-table3": "^0.6.5",
+    "commander": "^15.0.0",
+    "js-yaml": "^4.1.1",
+    "ora": "^9.4.0",
+    "picocolors": "^1.1.1",
+    "pino": "^10.3.1",
+    "postgres": "^3.4.9",
+    "zod": "^4.4.2"
+  }
+}

package/src/constants/index.ts

@@ -0,0 +1 @@
+export const MAX_DEPTH = 32;

package/src/errors/fail.ts

@@ -0,0 +1,110 @@
+import { ERROR_REGISTRY, type ErrorCodeType } from "./registry";
+import { normalizeErrorType, WorkerError } from "./worker";
+import type { WorkerErrorContext, WorkerErrorCategory, RegistryEntry } from "./types";
+import { type WorkerValidationIssue } from "@/validation/zod";
+
+type ExtractBaseCode<T extends string> = T extends ErrorCodeType
+  ? T
+  : T extends `${string}_${infer Base extends ErrorCodeType}`
+  ? Base
+  : never;
+
+type DetailParams<Base extends ErrorCodeType> =
+  typeof ERROR_REGISTRY[Base] extends { detail: (...args: infer P) => string }
+  ? P
+  : never;
+
+type InferData<Base extends ErrorCodeType> =
+  DetailParams<Base> extends [infer D, ...any[]]
+  ? D
+  : never;
+
+type IsDataRequired<Base extends ErrorCodeType> = DetailParams<Base> extends []
+  ? false
+  : DetailParams<Base> extends [never]
+  ? false
+  : true;
+
+type FailOptions<T extends string> = {
+  code: T;
+  title?: string;
+  category?: WorkerErrorCategory;
+  retryable?: boolean;
+  fatal?: boolean;
+  cause?: unknown;
+  context?: WorkerErrorContext | null;
+  issues?: WorkerValidationIssue[] | null;
+} & (
+    [ExtractBaseCode<T>] extends [infer Base extends ErrorCodeType]
+    ? (
+      | { detail: string; data?: InferData<Base> }
+      | (IsDataRequired<Base> extends true
+        ? { detail?: never; data: InferData<Base> }
+        : { detail?: never; data?: InferData<Base> })
+    )
+    : {
+      title: string;
+      detail: string;
+      category: WorkerErrorCategory;
+    });
+
+export function fail<T extends string>(options: FailOptions<T>): never {
+  const { code, title, category, retryable, fatal, cause, context, issues } = options;
+
+  let meta: RegistryEntry | undefined = ERROR_REGISTRY[code as ErrorCodeType];
+  let baseCode = code as string;
+
+  if (!meta) {
+    // Isolate the longest valid registry suffix matching the prefixed string
+    const baseMatch = (Object.keys(ERROR_REGISTRY) as ErrorCodeType[])
+      .filter((k) => code.endsWith(`_${k}`))
+      .sort((a, b) => b.length - a.length)[0];
+
+    if (baseMatch) {
+      meta = ERROR_REGISTRY[baseMatch];
+      baseCode = baseMatch;
+    }
+  }
+
+  if (meta) {
+    let resolvedDetail: string;
+
+    if ('detail' in options && typeof options.detail === 'string') {
+      resolvedDetail = options.detail;
+    } else {
+      const targetDetail = 'detail' in meta ? meta.detail : undefined;
+      const inputData = (options as any).data ?? {};
+
+      resolvedDetail = typeof targetDetail === 'function'
+        ? (targetDetail as Function)(inputData)
+        : String(targetDetail);
+    }
+
+    throw new WorkerError({
+      code,
+      type: normalizeErrorType(baseCode),
+      title: title ?? meta.title,
+      category: category ?? meta.category,
+      fatal: fatal ?? meta.fatal,
+      retryable: retryable ?? meta.retryable,
+      detail: resolvedDetail,
+      cause: cause ?? null,
+      context: context ?? null,
+      issues: issues ?? null,
+    });
+  }
+
+  // Pure ad-hoc custom string signature layout engine
+  throw new WorkerError({
+    code,
+    type: normalizeErrorType(baseCode),
+    title: title ?? "Unhandled Application Fault",
+    category: category ?? "internal",
+    detail: (options as any).detail ?? "An unexpected runtime failure was triggered.",
+    retryable: retryable ?? false,
+    fatal: fatal ?? true,
+    cause: cause ?? null,
+    context: context ?? null,
+    issues: issues ?? null,
+  });
+}

package/src/errors/index.ts

@@ -0,0 +1,4 @@
+export * from "./worker";
+export * from "./registry";
+export * from "./fail";
+export * from "./types";

package/src/errors/inferer.ts

@@ -0,0 +1,166 @@
+import { ZodError } from "zod";
+import type {
+  WorkerErrorCode,
+  WorkerErrorFallback,
+  WorkerErrorCategory,
+} from "./types";
+import { WorkerError } from "./worker";
+import { summarizeZodError } from "@/validation/zod";
+
+const RETRYABLE_POSTGRES_CODES = new Set([
+  "40001", // serialization_failure
+  "40P01", // deadlock_detected
+  "55P03", // lock_not_available
+  "57014", // query_canceled
+  "57P01", // admin_shutdown
+  "57P02", // crash_shutdown
+  "57P03", // cannot_connect_now
+]);
+
+function isAbortLikeError(value: unknown): value is Error {
+  return value instanceof Error && (value.name === "AbortError" || value.name === "TimeoutError");
+}
+
+function isPostgresError(value: unknown): value is Error & { code: string } {
+  return value instanceof Error && typeof (value as { code?: unknown }).code === "string";
+}
+
+export function inferRetryability(error: unknown, fallback?: WorkerErrorFallback): boolean {
+  if (fallback?.retryable !== undefined) {
+    return fallback.retryable;
+  }
+
+  if (isAbortLikeError(error)) {
+    return true;
+  }
+
+  if (isPostgresError(error)) {
+    if (error.code.startsWith("08")) {
+      return true;
+    }
+
+    return RETRYABLE_POSTGRES_CODES.has(error.code);
+  }
+
+  return false;
+}
+
+export function inferCategory(error: unknown, fallback?: WorkerErrorFallback): WorkerErrorCategory {
+  if (fallback?.category) {
+    return fallback.category;
+  }
+
+  if (error instanceof ZodError) {
+    return "validation";
+  }
+
+  if (isAbortLikeError(error)) {
+    return "network";
+  }
+
+  if (isPostgresError(error)) {
+    if (error.code === "40001" || error.code === "40P01" || error.code === "55P03") {
+      return "concurrency";
+    }
+
+    if (error.code.startsWith("08") || error.code.startsWith("57")) {
+      return "database";
+    }
+
+    return "database";
+  }
+
+  return "internal";
+}
+
+export function inferFatal(error: unknown, fallback?: WorkerErrorFallback): boolean {
+  if (fallback?.fatal !== undefined) {
+    return fallback.fatal;
+  }
+
+  if (error instanceof WorkerError) {
+    return error.fatal;
+  }
+
+  return false;
+}
+
+export function inferTitle(error: unknown, fallback?: WorkerErrorFallback): string {
+  if (fallback?.title) {
+    return fallback.title;
+  }
+
+  if (error instanceof ZodError) {
+    return "Validation failed";
+  }
+
+  if (isAbortLikeError(error)) {
+    return "Network operation timed out";
+  }
+
+  if (isPostgresError(error) && error.code === "40001") {
+    return "Serialization failure";
+  }
+
+  if (error instanceof Error && error.name) {
+    return error.name;
+  }
+
+  return "Unexpected worker error";
+}
+
+export function inferDetail(error: unknown, fallback?: WorkerErrorFallback): string {
+  if (fallback?.detail) {
+    return fallback.detail;
+  }
+
+  if (error instanceof ZodError) {
+    return summarizeZodError(error);
+  }
+
+  if (error instanceof Error && error.message.trim().length > 0) {
+    return error.message;
+  }
+
+  return "An unexpected worker error occurred.";
+}
+
+export function inferCode(error: unknown, fallback?: WorkerErrorFallback): WorkerErrorCode {
+  if (fallback?.code) {
+    return fallback.code;
+  }
+
+  if (error instanceof WorkerError) {
+    return error.code;
+  }
+
+  if (error instanceof ZodError) {
+    return "VALIDATION_FAILED";
+  }
+
+  if (isAbortLikeError(error)) {
+    return "NETWORK_TIMEOUT";
+  }
+
+  if (isPostgresError(error)) {
+    if (error.code === "40001") {
+      return "DB_SERIALIZATION_FAILURE";
+    }
+
+    if (error.code === "40P01") {
+      return "DB_DEADLOCK_DETECTED";
+    }
+
+    if (error.code === "55P03") {
+      return "DB_LOCK_NOT_AVAILABLE";
+    }
+
+    if (error.code.startsWith("08")) {
+      return "DB_CONNECTION_ERROR";
+    }
+
+    return "DB_ERROR";
+  }
+
+  return "INTERNAL_UNEXPECTED";
+}

package/src/errors/registry.ts

@@ -0,0 +1,122 @@
+import type { RegistryEntry, WorkerErrorCategory } from "./types";
+
+export type ErrorCodeType = keyof typeof ERROR_REGISTRY;
+
+export interface ErrorRegistryTypes {
+  title: string;
+  detail: (data: unknown) => string;
+  category: WorkerErrorCategory;
+  retryable: boolean;
+  fatal: boolean;
+}
+
+/**
+ * Centralized Error Registry
+ */
+export const ERROR_REGISTRY = {
+  UNREGISTERED_ERROR_CODE: {
+    title: "Unknown Error",
+    detail: (data: { code: string }) => `An unregistered error occurred: ${data.code}`,
+    category: "internal",
+    retryable: false,
+    fatal: true,
+  },
+  CONFIG_SIGNATURE_MISSING: {
+    title: "Missing worker config signature",
+    detail: (data: { value: string }) =>
+      `Detached config signature ${data.value} is required when config signing is enabled.`,
+    category: "configuration",
+    retryable: false,
+    fatal: true,
+  },
+  CONFIG_SIGNATURE_INVALID: {
+    title: "Invalid worker config signature",
+    detail: (data: { value: string }) => `Detached config signature ${data.value} failed verification.`,
+    category: "integrity",
+    retryable: false,
+    fatal: true,
+  },
+  SECRET_ENV_MISSING: {
+    title: "Required secret is missing",
+    detail: (data: { keyName: string }) => `${data.keyName} is required.`,
+    category: "configuration",
+    retryable: false,
+    fatal: true,
+  },
+  SECRET_ENV_INVALID: {
+    title: "Invalid secret format",
+    detail: (data: { keyName: string, KEY_LENGTH: number }) =>
+      `${data.keyName} must resolve to exactly ${data.KEY_LENGTH} bytes. Supported formats: 64-char hex or base64.`,
+    category: "configuration",
+    retryable: false,
+    fatal: true,
+  },
+  KMS_SECRET_MISSING: {
+    title: "Runtime secret is missing",
+    category: "configuration",
+    retryable: false,
+    fatal: true,
+  },
+  KMS_RESPONSE_INVALID: {
+    title: "Key provider response invalid",
+    category: "external",
+    retryable: false,
+    fatal: true,
+  },
+  VAULT_NOT_FOUND: {
+    title: "Vault record not found",
+    detail: (
+      data: {
+        appSchema: string,
+        rootTable: string,
+        normalizedSubjectId: string
+      }
+    ) => `Vault record not found for ${data.appSchema}.${data.rootTable}#${data.normalizedSubjectId}.`,
+    category: "validation",
+    retryable: false,
+    fatal: false
+  },
+  USER_ID_INVALID: {
+    title: "Invalid root identifier",
+    detail: () => "subjectId must be a non-empty string or number.",
+    category: "validation",
+    retryable: false,
+  },
+  OUTBOX_LEASE_LOST: {
+    title: "Outbox lease lost",
+    category: "concurrency",
+    retryable: true,
+  },
+  BLOB_URL_INVALID: {
+    title: "Invalid S3 URL",
+    category: "validation",
+    retryable: false,
+  },
+  BLOB_URL_UNSUPPORTED: {
+    title: "Unsupported blob URL protocol",
+    category: "validation",
+    retryable: false,
+  },
+  AWS_CREDENTIALS_INVALID: {
+    title: "AWS credentials invalid",
+    category: "configuration",
+    retryable: false,
+    fatal: true,
+  },
+  AWS_CREDENTIALS_UNAVAILABLE: {
+    title: "AWS IMDS unavailable",
+    category: "configuration",
+    retryable: true,
+    fatal: false,
+  }
+} as const satisfies Record<string, RegistryEntry>;
+
+/**
+ * Type-safe map for error codes derived from @constant {ERROR_REGISTRY}
+ * It standardizes the code without writing it manually every time
+ * 
+ * @example fail({ code: CODE.CONFIG_SIGNATURE_MISSING });
+ */
+export const CODE = Object.fromEntries(
+  Object.keys(ERROR_REGISTRY).map(k => [k, k])
+) as { [k in keyof typeof ERROR_REGISTRY]: k }

package/src/errors/types.ts

@@ -0,0 +1,65 @@
+import { type WorkerValidationIssue } from "@/validation/zod";
+
+export type WorkerErrorCode = string;
+
+export type WorkerErrorCategory =
+  | "configuration"
+  | "validation"
+  | "integrity"
+  | "concurrency"
+  | "database"
+  | "network"
+  | "crypto"
+  | "runtime"
+  | "external"
+  | "internal";
+
+export interface WorkerErrorContext {
+  [key: string]: unknown
+};
+
+export interface WorkerProblemDetails {
+  type: string;
+  title: string;
+  detail: string;
+  code: WorkerErrorCode;
+  category: WorkerErrorCategory;
+  retryable: boolean;
+  fatal: boolean;
+  instance?: string;
+  context?: WorkerErrorContext;
+  issues?: WorkerValidationIssue[];
+  cause?: WorkerProblemDetails;
+}
+
+export interface WorkerErrorOptions {
+  code: WorkerErrorCode;
+  title: string;
+  detail: string;
+  category: WorkerErrorCategory;
+  retryable?: boolean;
+  fatal?: boolean;
+  context?: WorkerErrorContext | null;
+  issues?: WorkerValidationIssue[] | null;
+  cause?: unknown;
+  type?: string;
+}
+
+export interface WorkerErrorFallback {
+  code?: WorkerErrorCode;
+  title?: string;
+  detail?: string;
+  category?: WorkerErrorCategory;
+  retryable?: boolean;
+  fatal?: boolean;
+  context?: WorkerErrorContext;
+  issues?: WorkerValidationIssue[];
+}
+
+export interface RegistryEntry<T = any> {
+  title: string;
+  detail?: (data: T) => string;
+  category: WorkerErrorCategory;
+  retryable: boolean;
+  fatal?: boolean;
+};