dpdp-erasure-cli 1.0.2 → 1.0.4

package/.env.example

@@ -4,6 +4,9 @@
 
 LOG_LEVEL=info
 
+# Mandatory Legal Acknowledgement: Sets liability shift and confirms Apache 2.0 terms
+I_ACCEPT_APACHE2_AND_DPDP_OPERATIONAL_LIABILITY=true
+
 # 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
 

package/NOTICE

@@ -0,0 +1,56 @@
+DPDP Erasure Engine
+Copyright 2026 Dev Dhanadiya
+
+This product includes software developed at
+Dev Dhanadiya (https://github.com/devxdh)
+
+=======================================================================
+LEGAL AND ARCHITECTURAL DISCLAIMER (OPERATIONAL LIABILITY SHIFT)
+=======================================================================
+
+1. FAIL-CLOSED ARCHITECTURE AND SYSTEM FREEZES
+This software ("Engine for DPDP Workflows") is designed using an ACID
+Fail-Closed orchestration pattern. As explicitly stated in our
+documentation and marketing materials, the system relies on database
+locks ("FOR UPDATE SKIP LOCKED"), strict cryptographic schema hashing,
+and strict transaction boundaries. 
+
+If this Engine encounters ANY structural anomaly—including but not 
+limited to:
+- A mismatch between the live database schema and the legal manifest
+- Unresolved foreign key constraints
+- API or Worker thread unhandled exceptions
+- Transient network drops
+- Unsigned or unauthorized configurations
+
+The system is hard-coded to IMMEDIATELY AND PERMANENTLY HALT its execution 
+queues. It will not attempt dangerous roll-forwards. It will quarantine 
+itself.
+
+2. LIABILITY FOR COMPLIANCE TIMELINES (e.g. DPDP 30-DAY CLOCK)
+Because the Licensor provides this software purely as an API and a local 
+Worker intended to be deployed on the Licensee's own infrastructure, the 
+Licensor has zero physical, operational, or logical control over the 
+deployment environment.
+
+Consequently, by deploying this software, the Licensee (the Data Fiduciary) 
+expressly acknowledges and agrees that:
+- They are solely responsible for monitoring worker health, API endpoint 
+  uptime, and queue backlogs.
+- If a system freeze, thread drop, or JSON payload parsing error causes 
+  a delay in data erasure, the Licensee is solely liable for any resulting 
+  breach of DPDP timelines (or any other regulatory mandate).
+- The Licensor accepts ZERO liability for compliance failures resulting 
+  from operational deployment bugs, configuration errors, or architectural 
+  lockups.
+
+3. "AS-IS" DISTRIBUTION UNDER APACHE 2.0
+In strict accordance with Sections 7 and 8 of the Apache 2.0 License:
+This software is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR 
+CONDITIONS OF ANY KIND, either express or implied, including, without 
+limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, 
+MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+You are solely responsible for determining the appropriateness of using 
+or redistributing the Work and assume any risks associated with Your 
+exercise of permissions under this License.

package/README.md

@@ -1,67 +1,140 @@
-# DPDP Erasure Engine CLI (`dpdp-erasure-cli`)
+# Operator CLI Reference Guide (`dpdp-erasure-cli`)
 
 [![npm version](https://badge.fury.io/js/dpdp-erasure-cli.svg)](https://badge.fury.io/js/dpdp-erasure-cli)
 
-The **DPDP Erasure Engine Operator CLI** is an enterprise-grade utility designed to help data fiduciaries comply with modern privacy laws like the **Digital Personal Data Protection (DPDP) Act, 2023**.
+The **Operator CLI** (`dpdp-erasure-cli`) is the primary interface for data engineers, DevOps, and privacy operators to manage the DPDP Erasure Engine. 
 
-This CLI orchestrates the Data Plane, enabling you to inspect databases for Personally Identifiable Information (PII), generate privacy compliance manifests, sign them cryptographically, and execute safe erasure operations.
+It is used to introspect databases, classify PII, manage compliance manifests, sign them cryptographically, and simulate safe erasure operations locally.
 
 ---
 
 ## 🚀 Installation
 
-This CLI relies on [Bun](https://bun.sh/) for native SQLite and cryptographic bindings. Ensure you have Bun installed, then install the package globally:
+This CLI requires [Bun](https://bun.sh/) for native cryptographic bindings and high-performance execution. Ensure you have Bun installed, then install the package globally:
 
 ```bash
 npm install -g dpdp-erasure-cli
 ```
 
+*Alternatively, if running from the monorepo root:*
+```bash
+bun run --cwd ./apps/worker cli <command>
+```
+
 ---
 
-## 🛠️ Usage
+## 🛠️ Interactive Console
+
+If you run the CLI without any arguments, it will launch an interactive wizard to guide you through the available operations:
 
 ```bash
-dpdp-cli [command] [options]
+dpdp-cli
 ```
 
-### Core Commands
+---
 
-*   `scan`: Run a metadata-only schema scan across your database to detect potential PII columns based on column names.
-*   `introspect`: Safely analyze your database's Foreign Key (FK) DAG offline and draft a comprehensive PII mapping manifest (`compliance.worker.yml`).
-*   `keygen`: Provision secure Ed25519 cryptographic keys required for configuration signing.
-*   `sign`: Cryptographically sign your `compliance.worker.yml` manifest to lock in your legal attestation hash.
-*   `verify`: Perform deep integrity checks to compute mandatory schema hashes and ensure nothing has drifted.
-*   `check-integrity`: A CI/CD gate that fails closed unless the schema hash and compiled DAG match your live production database.
-*   `verify-schema`: Similar to check-integrity, designed specifically to verify that the live schema matches the legal attestation hash.
-*   `dry-run`: Simulate a full PII vault operation without mutating any production data.
-*   `graph`: Visualize recursive table dependencies (FK DAG) for a specific root table.
-*   `inspect`: Inspect an existing worker manifest and summarize the legal/configuration coverage.
-*   `init`: Interactively provision a fresh legal compliance manifest for a new project.
+## 📚 Core Commands & Configuration Guide
 
-### Example Workflow
+### 1. `introspect` (The Core Command)
+Safely analyze your database's Foreign Key (FK) Directed Acyclic Graph (DAG) offline and draft a comprehensive PII mapping manifest (`compliance.worker.yml`). This is the first step in setting up the engine.
 
-**1. Introspect your database to detect PII:**
 ```bash
-dpdp-cli introspect -u postgres://user:pass@localhost:5432/app_db -r public.users -s public -o ./compliance.worker.yml
+dpdp-cli introspect \
+  --url postgres://user:pass@localhost:5432/app_db \
+  --root public.users \
+  --schema public \
+  --output ./compliance.worker.yml.draft
 ```
 
-**2. Generate a secure keypair:**
+**Options:**
+*   `-u, --url <url>`: PostgreSQL Connection DSN.
+*   `-r, --root <table>`: The root table containing the user/subject identifier (e.g., `public.users`).
+*   `-s, --schema <schema>`: The target PostgreSQL schema (defaults to `public`).
+*   `-o, --output <path>`: Where to write the generated YAML draft (defaults to `compliance.worker.yml.draft`).
+*   `-d, --max-depth <depth>`: Limit for recursive Foreign Key traversal (default: `32`).
+*   `--sample-percent <percent>`: Percentage of data to sample using `TABLESAMPLE` for PII detection (default: `1`).
+*   `--threshold <score>`: Confidence score required to flag a column as PII (default: `0.75`).
+*   `--report <path>`: Write a readable Markdown report of the findings.
+
+---
+
+### 2. `scan` (Quick PII Check)
+A lightweight, metadata-only schema scan that looks for potential PII columns based purely on naming conventions, without the heavy block sampling used by `introspect`.
+
+```bash
+dpdp-cli scan --url "postgres://user:pass@localhost:5432/app_db" --schema public
+```
+
+---
+
+### 3. `keygen` (Security Provisioning)
+Provisions secure Ed25519 cryptographic keys required to sign your configuration manifest.
+
 ```bash
 dpdp-cli keygen
 ```
+*This generates a private key file (e.g., `worker.pkcs8.key`) and a public key.*
+
+---
+
+### 4. `sign` (Cryptographic Manifest Lock)
+To prevent unauthorized changes to data erasure rules in production, the manifest must be cryptographically signed by a Data Protection Officer (DPO) or Lead Engineer.
+
+```bash
+dpdp-cli sign --config ./compliance.worker.yml --key ./worker.pkcs8.key
+```
+*This generates a detached signature file (e.g., `compliance.worker.yml.sig`). The worker will fail to boot if this signature does not match the manifest.*
+
+---
+
+### 5. `check-integrity` & `verify-schema` (CI/CD Gates)
+These commands are designed for CI/CD pipelines to ensure the live database schema matches the legal attestation hash stored in the signed manifest.
 
-**3. Cryptographically sign your manifest:**
 ```bash
-dpdp-cli sign -c ./compliance.worker.yml -k ./coe-private.key
+# Verify the compiled DAG and live schema hash
+dpdp-cli check-integrity --url "postgres://.../app_db" --config ./compliance.worker.yml
+
+# Check only the live schema hash against the legal attestation
+dpdp-cli verify-schema --url "postgres://.../app_db" --config ./compliance.worker.yml
 ```
+*If a developer adds a new column to the database without updating and re-signing the manifest, these commands will exit with a non-zero status.*
+
+---
+
+### 6. `dry-run` (Safe Erasure Simulation)
+Simulates a PII vault and redaction operation for a specific user. It runs inside an isolated transaction that is automatically rolled back.
 
-**4. Perform a dry-run to ensure safety:**
 ```bash
-dpdp-cli dry-run -u postgres://user:pass@localhost:5432/app_db -c ./compliance.worker.yml
+dpdp-cli dry-run --id "user_12345" --url "postgres://.../app_db" --config ./compliance.worker.yml
 ```
+*This is the recommended safety check to help ensure your configuration captures related PII without breaking foreign keys.*
 
 ---
 
-## 📖 Complete Documentation
+### 7. `graph` (Dependency Visualization)
+Visualizes the recursive table dependencies (FK DAG) for a specific root table, helping you understand how data cascades down from a user.
+
+```bash
+dpdp-cli graph --table public.users --url "postgres://.../app_db"
+```
+
+---
+
+## ⚙️ Standard Workflow Example
+
+Setting up the engine generally follows this workflow:
+
+1.  **Introspect** the database to generate a draft manifest:
+    `dpdp-cli introspect -u postgres://... -r public.users -s public -o compliance.worker.yml`
+2.  **Review & Tweak** the `compliance.worker.yml` manually (fix false positives, add missing logical links, select masking actions like `HMAC` or `SET NULL`).
+3.  **Generate Keys** for signing:
+    `dpdp-cli keygen`
+4.  **Sign** the finalized manifest:
+    `dpdp-cli sign -c compliance.worker.yml -k worker.pkcs8.key`
+5.  **Dry-Run** an erasure to verify it behaves as expected:
+    `dpdp-cli dry-run -i "test_user_id" -u postgres://... -c compliance.worker.yml`
+6.  **Deploy** the signed manifest and the detached `.sig` file to your production Worker.
+
+---
 
-For comprehensive instructions on how the entire Engine operates, including the Control Plane API and architectural overviews, please refer to the **[Official GitHub Repository](https://github.com/devxdh/dpdp-erasure-engine)**.
+For architectural details and deep-dives into how the cryptographic shredding works, refer to the [Main Documentation](https://github.com/devxdh/dpdp-erasure-engine/tree/main/apps/docs).

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "dpdp-erasure-cli",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "license": "Apache-2.0",
+  "keywords": [
+    "dpdp",
+    "dpdp-2023",
+    "data-privacy",
+    "data-erasure",
+    "privacy-compliance",
+    "cryptographic-shredding",
+    "gdpr",
+    "compliance",
+    "cli"
+  ],
   "module": "index.ts",
   "type": "module",
   "bin": {
@@ -39,4 +50,4 @@
     "postgres": "^3.4.9",
     "zod": "^4.4.2"
   }
-}
+}

package/src/index.ts

@@ -116,6 +116,24 @@ async function sendMailerWebhook(
 
 async function main() {
   registerProcessGuard(logger);
+  
+  // Explicit Programmatic Legal Warning printed to standard output on boot
+  console.log("\n=======================================================================");
+  console.log("[ENGINE INIT] Copyright 2026 Dev Dhanadiya. Licensed under Apache 2.0.");
+  console.log("[ENGINE INIT] DESIGN PATTERN: ACID FAIL-CLOSED ORCHESTRATION ENGINE.");
+  console.log("[WARN] System will freeze execution queues upon any database conflict.");
+  console.log("[LEGAL] Under Apache 2.0 Sec 7 & 8, User assumes 100% liability for");
+  console.log("        monitoring API failures, worker drops, and DPDP timelines.");
+  console.log("=======================================================================\n");
+
+  if (process.env.I_ACCEPT_APACHE2_AND_DPDP_OPERATIONAL_LIABILITY !== "true") {
+    console.error("[CRITICAL ERROR] Engine initialization aborted.");
+    console.error("[CRITICAL ERROR] You must explicitly set 'I_ACCEPT_APACHE2_AND_DPDP_OPERATIONAL_LIABILITY=true'");
+    console.error("                 in your environment variables to acknowledge the Apache 2.0 disclaimer");
+    console.error("                 and assume full operational risk under the Indian DPDP Act 2023.");
+    process.exit(1);
+  }
+
   logger.info("Starting Compliance Worker");
 
   const configPath = new URL("../compliance.worker.yaml", import.meta.url)