# privguard-sdk

> **Zero-Latency, Privacy-Safe Runtime DPDPA Compliance SDK & Middleware for Node.js / Express.**

[![npm version](https://img.shields.io/npm/v/privguard-sdk.svg)](https://www.npmjs.com/package/privguard-sdk)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Zero Overhead](https://img.shields.io/badge/Client_Latency-0.00ms-brightgreen.svg)]()

PrivGuard SDK is a 100% dependency-free Node.js SDK and Express middleware that guarantees continuous runtime compliance with India's **Digital Personal Data Protection Act (DPDPA 2023)**, GDPR, and enterprise Behavior Contracts.

---

## 🚀 Key Features

- 🛡️ **Zero Raw PII Over Wire**: Performs local in-memory scrubbing and tenant-salted HMAC-SHA256 fingerprinting before transmitting metadata.
- ⚡ **Zero Client Latency (0.00ms)**: Decoupled asynchronous event batching ensures zero impact on HTTP request turnaround.
- 🔍 **Strict Identity & Algorithmic Validation**:
  - **Indian Aadhaar**: 100% mathematical Verhoeff checksum validation.
  - **Payment Cards**: 16-digit Luhn algorithm validation.
  - **Indian PAN & Credentials**: Regex pattern and case-insensitive credential scrubbing.
  - **Secrets & API Keys**: Shannon entropy analysis (>3.8 threshold) to detect leaked tokens.
- 📊 **Microservice Lineage Correlation**: Attaches W3C trace IDs across microservice hops to track data provenance and flag **Privacy Drift**.
- 📜 **Statutory Audit Feeds**: Automatically mounts `/api/audit-feed/*` endpoints for compliance audits.
- 🚪 **Privacy CI/CD Gate**: Includes `privguard-lint` CLI to block hardcoded secrets or unmasked PII logging before merge.

---

## 📦 Installation

```bash
npm install privguard-sdk
```

---

## 🛠️ Quick Start (Express Middleware)

```javascript
const express = require('express');
const { privguard } = require('privguard-sdk');

const app = express();
app.use(express.json());

// Attach PrivGuard Middleware
app.use(privguard({
  privguardUrl: process.env.PRIVGUARD_URL || 'http://localhost:5000',
  apiKey: process.env.PRIVGUARD_API_KEY || 'pg_live_xxxxxx',
  tenantId: process.env.TENANT_ID || 'tenant_default',
  serviceName: 'order-service',
  salt: process.env.FINGERPRINT_SECRET,
  batchSize: 10,
  flushIntervalMs: 500
}));

// Normal application routes
app.post('/api/orders', (req, res) => {
  // PII in req.body is automatically detected, sanitized, and fingerprinted locally
  res.json({ success: true, orderId: 'ORD-9812' });
});

app.listen(5001);
```

---

## 🔍 Standalone In-Memory Scanning

You can also use PrivGuard SDK as a standalone validator without Express:

```javascript
const { scanLocally, validateVerhoeff, validateLuhn, calculateShannonEntropy } = require('privguard-sdk');

// Scan arbitrary object or payload
const findings = scanLocally({
  email: 'user@example.com',
  aadhaar: '234567890123',
  apiKey: 'sk_live_98a7sd8f7as9d8f7asd8f'
}, 'your_tenant_secret');

console.log(findings);
// [
//   { piiType: 'EMAIL', field: 'email', confidence: 'HIGH', maskedValue: 'u***@example.com' },
//   { piiType: 'AADHAAR', field: 'aadhaar', confidence: 'HIGH', maskedValue: '****-****-0123' },
//   { piiType: 'HIGH_ENTROPY_SECRET', field: 'apiKey', entropy: 4.35 }
// ]
```

---

## 🚪 Privacy CI/CD Gate Linter

Run the included linter in your repository root or GitHub Actions workflow:

```bash
npx privguard-lint .
```

---

## 📄 License

Apache-2.0 © PrivGuard Team