dpdp-erasure-cli 1.0.0

package/tests/config.test.ts

@@ -0,0 +1,395 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { readWorkerConfig } from "@modules/config";
+
+const masterKeyHex = "42".repeat(32);
+const hmacKeyBase64 = Buffer.from(new Uint8Array(32).fill(0x24)).toString("base64");
+
+async function writeYaml(contents: string): Promise<string> {
+  const directory = await mkdtemp(join(tmpdir(), "worker-config-"));
+  const path = join(directory, "compliance.worker.yml");
+  await writeFile(path, contents, "utf8");
+  return path;
+}
+
+async function removeYaml(path: string) {
+  await rm(path, { force: true });
+  await rm(dirname(path), { recursive: true, force: true });
+}
+
+describe("Worker configuration", () => {
+  const pathsToDelete: string[] = [];
+
+  afterEach(async () => {
+    for (const path of pathsToDelete.splice(0, pathsToDelete.length)) {
+      await removeYaml(path);
+    }
+  });
+
+  it("parses strict YAML config with strongly typed graph and satellite definitions", async () => {
+    const path = await writeYaml(`
+      version: "1.0"
+      database:
+        app_schema: tenant_app
+        engine_schema: tenant_engine
+        replica_db_url: postgres://replica:replica@replica-host:5432/postgres
+      compliance_policy:
+        default_retention_years: 0
+        notice_window_hours: 72
+        retention_rules:
+          - rule_name: PMLA_FINANCIAL
+            legal_citation: "Prevention of Money Laundering Act, 2002, Sec 12"
+            if_has_data_in:
+              - transactions
+            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
+        root_pii_columns:
+          email: HMAC
+          full_name: STATIC_MASK
+      satellite_targets:
+        - table: marketing_leads
+          lookup_column: email
+          action: redact
+          masking_rules:
+            email: HMAC
+        - table: audit_logs
+          lookup_column: user_identifier
+          action: hard_delete
+      blob_targets:
+        - table: users
+          column: kyc_document_url
+          provider: aws_s3
+          region: ap-south-1
+          action: versioned_hard_delete
+          retention_mode: governance
+          expected_bucket_owner: "123456789012"
+      purge_policy:
+        enabled: true
+        selector:
+          kind: boolean_column
+          column: purge_eligible
+          value: true
+        max_batch_size: 50000
+        actor_opaque_id: system:dpo-purge
+        legal_framework: DPDP_2023
+        legal_citation: "DPDP Act, 2023 Sec 12; client-approved purge schedule"
+      outbox:
+        batch_size: 20
+        lease_seconds: 90
+        max_attempts: 12
+        base_backoff_ms: 1500
+      security:
+        notification_lease_seconds: 180
+        master_key_env: DPDP_MASTER_KEY
+        hmac_key_env: DPDP_HMAC_KEY
+      integrity:
+        expected_schema_hash: "${"1".repeat(64)}"
+      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 obligations."
+    `);
+    pathsToDelete.push(path);
+
+    const config = await readWorkerConfig(
+      {
+        DPDP_MASTER_KEY: masterKeyHex,
+        DPDP_HMAC_KEY: `base64:${hmacKeyBase64}`,
+      },
+      path
+    );
+
+    expect(config.database.app_schema).toBe("tenant_app");
+    expect(config.database.engine_schema).toBe("tenant_engine");
+    expect(config.database.replica_db_url).toBe("postgres://replica:replica@replica-host:5432/postgres");
+    expect(config.compliance_policy.default_retention_years).toBe(0);
+    expect(config.compliance_policy.notice_window_hours).toBe(72);
+    expect(config.compliance_policy.retention_rules).toEqual([
+      {
+        rule_name: "PMLA_FINANCIAL",
+        legal_citation: "Prevention of Money Laundering Act, 2002, Sec 12",
+        if_has_data_in: ["transactions"],
+        retention_years: 10,
+      },
+      {
+        rule_name: "RBI_KYC",
+        legal_citation: "RBI KYC Directions, 2016, Sec 38",
+        if_has_data_in: ["kyc_documents"],
+        retention_years: 5,
+      },
+    ]);
+    expect(config.graph.root_table).toBe("users");
+    expect(config.graph.root_id_column).toBe("id");
+    expect(config.graph.root_pii_columns).toEqual({
+      email: "HMAC",
+      full_name: "STATIC_MASK",
+    });
+    expect(config.satellite_targets).toHaveLength(2);
+    expect(config.blob_targets).toEqual([
+      {
+        table: "users",
+        column: "kyc_document_url",
+        lookup_column: undefined,
+        provider: "aws_s3",
+        region: "ap-south-1",
+        action: "versioned_hard_delete",
+        retention_mode: "governance",
+        expected_bucket_owner: "123456789012",
+        require_version_id: true,
+        masking_blob_path: undefined,
+      },
+    ]);
+    expect(config.purge_policy).toEqual({
+      enabled: true,
+      selector: {
+        kind: "boolean_column",
+        column: "purge_eligible",
+        value: true,
+      },
+      max_batch_size: 50000,
+      actor_opaque_id: "system:dpo-purge",
+      legal_framework: "DPDP_2023",
+      legal_citation: "DPDP Act, 2023 Sec 12; client-approved purge schedule",
+    });
+    expect(config.outbox.batch_size).toBe(20);
+    expect(config.security.notification_lease_seconds).toBe(180);
+    expect(config.legal_attestation).toEqual({
+      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 obligations.",
+    });
+    expect(Buffer.from(config.masterKey).toString("hex")).toBe(masterKeyHex);
+    expect(Buffer.from(config.hmacKey).toString("base64")).toBe(hmacKeyBase64);
+  });
+
+  it("fails closed when required compliance fields are null", async () => {
+    const path = await writeYaml(`
+      version: "1.0"
+      database:
+        app_schema: tenant_app
+        engine_schema: tenant_engine
+      compliance_policy:
+        default_retention_years: null
+        notice_window_hours: 48
+        retention_rules:
+          - 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
+        root_pii_columns:
+          email: HMAC
+      satellite_targets:
+        - table: marketing_leads
+          lookup_column: email
+          action: redact
+          masking_rules:
+            email: HMAC
+      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: "${"1".repeat(64)}"
+      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 obligations."
+    `);
+    pathsToDelete.push(path);
+
+    await expect(
+      readWorkerConfig(
+        {
+          DPDP_MASTER_KEY: masterKeyHex,
+          DPDP_HMAC_KEY: `base64:${hmacKeyBase64}`,
+        },
+        path
+      )
+    ).rejects.toThrow(/default_retention_years/i);
+  });
+
+  it("rejects malicious identifier injection in root_table", async () => {
+    const path = await writeYaml(`
+version: "1.0"
+database:
+  app_schema: tenant_app
+  engine_schema: tenant_engine
+compliance_policy:
+  default_retention_years: 0
+  notice_window_hours: 48
+  retention_rules:
+    - 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; DROP TABLE clients;--"
+  root_id_column: id
+  max_depth: 32
+  root_pii_columns:
+    email: HMAC
+satellite_targets:
+  - table: marketing_leads
+    lookup_column: email
+    action: redact
+    masking_rules:
+      email: HMAC
+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: "${"1".repeat(64)}"
+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 obligations."
+`);
+    pathsToDelete.push(path);
+
+    await expect(
+      readWorkerConfig(
+        {
+          DPDP_MASTER_KEY: masterKeyHex,
+          DPDP_HMAC_KEY: `base64:${hmacKeyBase64}`,
+        },
+        path
+      )
+    ).rejects.toThrow(/invalid graph root table/i);
+  });
+
+  it("fails closed when legal_attestation is missing", async () => {
+    const path = await writeYaml(`
+version: "1.0"
+database:
+  app_schema: tenant_app
+  engine_schema: tenant_engine
+compliance_policy:
+  default_retention_years: 0
+  notice_window_hours: 48
+  retention_rules:
+    - 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
+  root_pii_columns:
+    email: HMAC
+satellite_targets:
+  - table: marketing_leads
+    lookup_column: email
+    action: redact
+    masking_rules:
+      email: HMAC
+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: "${"1".repeat(64)}"
+`);
+    pathsToDelete.push(path);
+
+    await expect(
+      readWorkerConfig(
+        {
+          DPDP_MASTER_KEY: masterKeyHex,
+          DPDP_HMAC_KEY: `base64:${hmacKeyBase64}`,
+        },
+        path
+      )
+    ).rejects.toThrow(/legal_attestation/i);
+  });
+
+  it("fails closed when purge automation is enabled without an attested selector", async () => {
+    const path = await writeYaml(`
+version: "1.0"
+database:
+  app_schema: tenant_app
+  engine_schema: tenant_engine
+compliance_policy:
+  default_retention_years: 0
+  notice_window_hours: 48
+  retention_rules:
+    - 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
+  root_pii_columns:
+    email: HMAC
+purge_policy:
+  enabled: true
+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: "${"1".repeat(64)}"
+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 obligations."
+`);
+    pathsToDelete.push(path);
+
+    await expect(
+      readWorkerConfig(
+        {
+          DPDP_MASTER_KEY: masterKeyHex,
+          DPDP_HMAC_KEY: `base64:${hmacKeyBase64}`,
+        },
+        path
+      )
+    ).rejects.toThrow(/purge_policy\.selector/i);
+  });
+});

package/tests/control-plane-client.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it, vi } from "vitest";
+import { createControlPlaneApiClient } from "@modules/network";
+
+describe("Control Plane API client", () => {
+  it("accepts offset-form ISO timestamps in worker sync payloads", async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        pending: true,
+        task: {
+          id: "task-notify-1",
+          task_type: "NOTIFY_USER",
+          payload: {
+            request_id: "01ce9849-189c-4c3d-ab91-b35eff852b9f",
+            subject_opaque_id: "usr_local_zero",
+            idempotency_key: "9943912a-1897-4860-ad9c-d32e9b3c2876",
+            trigger_source: "USER_CONSENT_WITHDRAWAL",
+            actor_opaque_id: "usr_local_zero",
+            legal_framework: "DPDP_2023",
+            request_timestamp: "2026-04-20T14:49:04.477+00:00",
+            cooldown_days: 0,
+            shadow_mode: false,
+          },
+        },
+      }),
+    }));
+
+    vi.spyOn(globalThis, "fetch").mockImplementation(fetchMock as any);
+
+    const client = createControlPlaneApiClient({
+      syncUrl: "https://control-plane.example/api/v1/worker/sync",
+      ackBaseUrl: "https://control-plane.example/api/v1/worker/tasks",
+      workerAuthHeaders: {
+        "x-client-id": "worker-1",
+        authorization: "Bearer worker-secret",
+      },
+      workerConfigHash: "ab".repeat(32),
+      workerConfigVersion: "v-test",
+      workerDpoIdentifier: "dpo@example.com",
+      pushOutboxEvent: async () => true,
+    });
+
+    const response = await client.syncTask();
+    expect(response).toEqual({
+      pending: true,
+      task: {
+        id: "task-notify-1",
+        task_type: "NOTIFY_USER",
+        payload: {
+          request_id: "01ce9849-189c-4c3d-ab91-b35eff852b9f",
+          subject_opaque_id: "usr_local_zero",
+          idempotency_key: "9943912a-1897-4860-ad9c-d32e9b3c2876",
+          trigger_source: "USER_CONSENT_WITHDRAWAL",
+          actor_opaque_id: "usr_local_zero",
+          legal_framework: "DPDP_2023",
+          request_timestamp: "2026-04-20T14:49:04.477+00:00",
+          cooldown_days: 0,
+          shadow_mode: false,
+        },
+      },
+    });
+
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      "https://control-plane.example/api/v1/worker/sync",
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          "x-worker-config-hash": "ab".repeat(32),
+          "x-worker-config-version": "v-test",
+          "x-worker-dpo-identifier": "dpo@example.com",
+        }),
+      })
+    );
+  });
+
+  it("sends authenticated task heartbeat requests to extend long-running leases", async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ ok: true }),
+    }));
+
+    vi.spyOn(globalThis, "fetch").mockImplementation(fetchMock as any);
+
+    const client = createControlPlaneApiClient({
+      syncUrl: "https://control-plane.example/api/v1/worker/sync",
+      ackBaseUrl: "https://control-plane.example/api/v1/worker/tasks",
+      workerAuthHeaders: {
+        "x-client-id": "worker-1",
+        authorization: "Bearer worker-secret",
+      },
+      workerConfigHash: "ab".repeat(32),
+      pushOutboxEvent: async () => true,
+    });
+
+    await expect(client.heartbeatTask?.("task-long-1")).resolves.toBe(true);
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      "https://control-plane.example/api/v1/worker/tasks/task-long-1/heartbeat",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          "x-client-id": "worker-1",
+          authorization: "Bearer worker-secret",
+        }),
+      })
+    );
+  });
+});

package/tests/crypto.test.ts

@@ -0,0 +1,106 @@
+import { decryptGCM, decryptGCMBytes, encryptGCM, encryptGCMBytes, generateDEK, generateHMAC, unwrapKey, wrapKey } from "@modules/crypto";
+import { describe, it, expect } from "vitest";
+
+
+describe("Cryptographic Core (AES-256-GCM + Envelope + HMAC)", () => {
+  const KEK = new Uint8Array(32).fill(0x42); // Dummy Master Key
+  const rawPII = "User Email: john.doe@example.com, Phone: +91 9876543210";
+
+  describe("AES-256-GCM & Envelope Encryption", () => {
+    it("should successfully encrypt and decrypt PII using a unique DEK", async () => {
+      const userDEK = generateDEK();
+
+      // 1. Encrypt
+      const encryptedPII = await encryptGCM(rawPII, userDEK);
+      expect(encryptedPII.length).toBeGreaterThan(12 + 16); // IV (12) + Tag (16) + min 1 byte data
+
+      // 2. Decrypt
+      const decryptedPII = await decryptGCM(encryptedPII, userDEK);
+      expect(decryptedPII).toBe(rawPII);
+    });
+
+    it("should expose decrypted bytes for callers that need explicit memory wiping", async () => {
+      const userDEK = generateDEK();
+      const encryptedPII = await encryptGCM(rawPII, userDEK);
+
+      const decryptedBytes = await decryptGCMBytes(encryptedPII, userDEK);
+      expect(new TextDecoder().decode(decryptedBytes)).toBe(rawPII);
+
+      decryptedBytes.fill(0);
+      expect(Array.from(decryptedBytes).every((byte) => byte === 0)).toBe(true);
+    });
+
+    it("should successfully wrap and unwrap a DEK using a Master KEK", async () => {
+      const originalDEK = generateDEK();
+
+      // 1. Wrap
+      const wrappedDEK = await wrapKey(originalDEK, KEK);
+
+      // 2. Unwrap
+      const recoveredDEK = await unwrapKey(wrappedDEK, KEK);
+
+      expect(recoveredDEK).toEqual(originalDEK);
+    });
+
+    it("should fail decryption if the wrong KEK is used", async () => {
+      const originalDEK = generateDEK();
+      const wrappedDEK = await wrapKey(originalDEK, KEK);
+      const wrongKEK = new Uint8Array(32).fill(0x99);
+
+      await expect(unwrapKey(wrappedDEK, wrongKEK)).rejects.toThrow();
+    });
+
+    it("should fail decryption if the ciphertext is tampered with", async () => {
+      const userDEK = generateDEK();
+      const encryptedPII = await encryptGCM(rawPII, userDEK);
+
+      // Tamper with one byte in the middle of the ciphertext
+      if (encryptedPII[20] !== undefined) {
+        encryptedPII[20] ^= 0xFF;
+      }
+
+      await expect(decryptGCM(encryptedPII, userDEK)).rejects.toThrow();
+    });
+
+    it("should throw an error if encryptGCM is given an invalid key length", async () => {
+      const invalidKey = new Uint8Array(16); // 128-bit instead of 256-bit
+      await expect(encryptGCM(rawPII, invalidKey)).rejects.toThrow(/Invalid key length/);
+    });
+
+    it("should throw an error if decryptGCM is given an invalid key length", async () => {
+      const userDEK = generateDEK();
+      const encryptedPII = await encryptGCM(rawPII, userDEK);
+      const invalidKey = new Uint8Array(16);
+      await expect(decryptGCM(encryptedPII, invalidKey)).rejects.toThrow(/Invalid key length/);
+    });
+
+    it("should throw an error if decryptGCM is given a payload too short to be valid", async () => {
+      const userDEK = generateDEK();
+      const shortCiphertext = new Uint8Array(10); // Less than IV + Tag length
+      await expect(decryptGCM(shortCiphertext, userDEK)).rejects.toThrow(/Invalid ciphertext/);
+    });
+  });
+
+  describe("HMAC Pseudonymization", () => {
+    it("should generate a consistent hash for the same input and salt", async () => {
+      const salt = "somesalt123";
+      const hash1 = await generateHMAC(rawPII, salt);
+      const hash2 = await generateHMAC(rawPII, salt);
+      expect(hash1).toBe(hash2);
+      expect(hash1).toHaveLength(64); // SHA-256 hex length
+    });
+
+    it("should generate a different hash for the same input but different salt", async () => {
+      const hash1 = await generateHMAC(rawPII, "saltA");
+      const hash2 = await generateHMAC(rawPII, "saltB");
+      expect(hash1).not.toBe(hash2);
+    });
+
+    it("should generate a different hash for different inputs with the same salt", async () => {
+      const salt = "somesalt123";
+      const hash1 = await generateHMAC("user1@example.com", salt);
+      const hash2 = await generateHMAC("user2@example.com", salt);
+      expect(hash1).not.toBe(hash2);
+    });
+  });
+});

package/tests/errors.test.ts

@@ -0,0 +1,69 @@
+import { asWorkerError, serializeWorkerError, workerError } from "@/errors";
+import { describe, expect, it } from "vitest";
+import { ZodError, z } from "zod";
+
+describe("WorkerError normalization", () => {
+  it("preserves explicit worker error metadata in RFC-9457-style problem details", () => {
+    const error = workerError({
+      code: "TEST_EXPLICIT",
+      title: "Explicit worker error",
+      detail: "The worker emitted a classified error.",
+      category: "internal",
+      retryable: false,
+      fatal: true,
+      context: { component: "test" },
+    });
+
+    expect(serializeWorkerError(error, "worker:test")).toEqual({
+      type: "urn:dpdp:worker:error:test_explicit",
+      title: "Explicit worker error",
+      detail: "The worker emitted a classified error.",
+      code: "TEST_EXPLICIT",
+      category: "internal",
+      retryable: false,
+      fatal: true,
+      instance: "worker:test",
+      context: { component: "test" },
+    });
+  });
+
+  it("classifies transient postgres failures as retryable concurrency/database errors", () => {
+    const postgresError = Object.assign(new Error("deadlock detected"), {
+      code: "40P01",
+    });
+
+    const normalized = asWorkerError(postgresError);
+
+    expect(normalized.code).toBe("DB_DEADLOCK_DETECTED");
+    expect(normalized.category).toBe("concurrency");
+    expect(normalized.retryable).toBe(true);
+    expect(normalized.fatal).toBe(false);
+  });
+
+  it("converts zod validation failures into structured validation errors", () => {
+    let validationError: ZodError | null = null;
+
+    try {
+      z.object({ default_retention_years: z.number().int().min(0) }).parse({
+        default_retention_years: null,
+      });
+    } catch (error) {
+      validationError = error as ZodError;
+    }
+
+    const normalized = asWorkerError(validationError);
+
+    expect(normalized.code).toBe("VALIDATION_FAILED");
+    expect(normalized.category).toBe("validation");
+    expect(normalized.detail).toContain("default_retention_years");
+    expect(normalized.toProblem("worker:test").issues).toEqual([
+      {
+        path: "default_retention_years",
+        param: "default_retention_years",
+        code: "invalid_type",
+        message: "Invalid input: expected number, received null",
+      },
+    ]);
+    expect(normalized.retryable).toBe(false);
+  });
+});