@privacyscrubber/sdk 2.0.2

package/README.md

@@ -0,0 +1,258 @@
+# @privacyscrubber/sdk
+
+> **Zero-Trust Data Sanitization (ZTDS) & PII Redaction Engine**  
+> 100% Client-Side & In-Memory Execution. Zero Data Leakage. Zero Network Requests for Sanitization.
+
+The official Node.js / Browser SDK for [PrivacyScrubber.com](https://privacyscrubber.com). It provides enterprise-grade PII sanitization, cloud secrets redaction, cryptographic license enforcement, and deterministic token restoration for AI pipelines (OpenAI, Anthropic, LangChain, LlamaIndex).
+
+---
+
+## ⚡ Highlights
+
+- 🛡️ **Zero-Trust & In-Memory**: All sanitization executes locally in RAM. No PII or raw text is ever transmitted over the network.
+- 🤖 **Transparent AI Wrapper**: `wrapOpenAI(client)` automatically scrubs sensitive tokens before outbound API requests and deterministically restores them in responses.
+- ⚡ **High Throughput**: Under 2ms average execution time per 10k characters.
+- 📋 **23 Industry Compliance Profiles**: General, Dev/DevOps, Medical (HIPAA), Financial (PCI-DSS), Legal, HR, Executive, and more.
+- 🧾 **CISO Audit Receipts**: Automated generation of Markdown compliance receipts (GDPR Art. 4, HIPAA §164.514, SOC 2 Type II, ISO 27001, NIST SP 800-53).
+- 🔑 **Cryptographic License Engine**: Native RS256 JWT and cryptographic checksum verification.
+- 🏷️ **TypeScript Support**: Full `.d.ts` typings included out of the box.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @privacyscrubber/sdk
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Simple Sanitize & Restore
+
+```javascript
+import { sanitize, restore } from '@privacyscrubber/sdk';
+
+const rawPrompt = "Hello, my name is Alice Smith and my email is alice@corp.com.";
+
+// 1. Sanitize text before sending to LLM
+const { scrubbedText, tokenMap, telemetry, auditReceipt } = sanitize(rawPrompt);
+
+console.log(scrubbedText);
+// "Hello, my name is [NAME_1] and my email is [EMAIL_1]."
+
+console.log(auditReceipt);
+// > 🛡️ **PrivacyScrubber Audit Receipt**
+// > * **Risk Level:** 🔴 CRITICAL (HIGH EXPOSURE)
+// > * **Compliance Enforced:** ZTDS Standard, GDPR (Art. 4), CCPA/CPRA
+// > * **Tokens Masked:** 2 (1 NAME, 1 EMAIL)
+
+// 2. Restore response from LLM
+const aiResponse = "I have drafted a confirmation email to [NAME_1] ([EMAIL_1]).";
+const { restoredText } = restore(aiResponse, tokenMap);
+
+console.log(restoredText);
+// "I have drafted a confirmation email to Alice Smith (alice@corp.com)."
+```
+
+---
+
+### 2. Transparent OpenAI Client Wrapper
+
+Zero changes to your prompting architecture. Wrap your existing OpenAI SDK instance and PrivacyScrubber intercepts outbound prompts and restores incoming responses automatically:
+
+```javascript
+import OpenAI from 'openai';
+import { wrapOpenAI } from '@privacyscrubber/sdk';
+
+const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
+
+// Prompts are scrubbed in RAM before leaving your server, 
+// and the returned choice content is restored before reaching your application logic!
+const completion = await openai.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [
+        { role: 'user', content: 'Contact John Doe at john@acme.com regarding invoice #99281.' }
+    ]
+});
+
+console.log(completion.choices[0].message.content);
+```
+
+---
+
+### 3. Stateful Conversational Engine (`PrivacyScrubberEngine`)
+
+Maintain token map consistency across multi-turn chats or session threads:
+
+```javascript
+import { PrivacyScrubberEngine } from '@privacyscrubber/sdk';
+
+const engine = new PrivacyScrubberEngine({ defaultProfile: 'General' });
+
+// Turn 1
+const turn1 = engine.sanitize("My name is John Doe and my phone is 555-0199.");
+// Tokens: [NAME_1], [PHONE_1]
+
+// Turn 2: Re-uses [NAME_1] for John Doe consistently
+const turn2 = engine.sanitize("John Doe needs an update on ticket #402.");
+// Tokens: [NAME_1]
+
+// Restore full thread context
+const restored = engine.restore("Notified [NAME_1] at [PHONE_1].");
+console.log(restored.restoredText);
+// "Notified John Doe at 555-0199."
+```
+
+---
+
+### 4. Specialized Industry Profiles & DevOps Secrets
+
+Sanitize AWS credentials, JWT tokens, Stripe API keys, database connection strings, and HIPAA records:
+
+```javascript
+import { sanitize } from '@privacyscrubber/sdk';
+
+const devLog = `
+AWS_KEY=AKIAIOSFODNN7EXAMPLE
+DB_URI=postgres://admin:secret123@db.internal:5432/prod
+`;
+
+const result = sanitize(devLog, { profile: 'Dev' });
+console.log(result.scrubbedText);
+// AWS_KEY=[AWS_KEY_1]
+// DB_URI=[SECRET_1]
+```
+
+---
+
+## 💼 Commercial Production Pipelines (Recipes)
+
+### 1. AI Mortgage & Loan Underwriting Pipeline (W-2, Paystubs & DTI Calculation)
+*Enables Loan Officers and AI Underwriting bots (e.g. CalChat) to analyze borrower income without violating GLBA or transmitting SSNs to OpenAI/Anthropic.*
+
+```javascript
+import OpenAI from 'openai';
+import { sanitize, restore } from '@privacyscrubber/sdk';
+
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+async function underwriteLoanApplication(w2RawText) {
+    // 1. Sanitize borrower W-2 in RAM (SSN, EIN, Employer, Address -> Masked; Wages/Rates -> Preserved)
+    const { scrubbedText, tokenMap } = sanitize(w2RawText, { profile: 'Finance' });
+
+    // 2. Transmit mathematical numbers to LLM for Debt-to-Income (DTI) & qualifying income calculation
+    const aiResponse = await openai.chat.completions.create({
+        model: 'gpt-4o',
+        messages: [
+            { role: 'system', content: 'You are an automated mortgage underwriting assistant. Calculate monthly qualifying income and front-end DTI.' },
+            { role: 'user', content: scrubbedText }
+        ]
+    });
+
+    // 3. Rehydrate borrower name and employer into the final formal credit memo
+    const { restoredText } = restore(aiResponse.choices[0].message.content, tokenMap);
+    return restoredText;
+}
+```
+
+### 2. Blind AI HR Screening Pipeline (EEOC & GDPR Compliant)
+*Strips names, photos, gender markers, contact details, and graduation years from candidate resumes to prevent algorithmic bias while retaining 100% skills, experience, and GPA.*
+
+```javascript
+import { sanitize } from '@privacyscrubber/sdk';
+
+function prepareCandidateForAIScoring(resumeText) {
+    const { scrubbedText, telemetry } = sanitize(resumeText, { profile: 'HR' });
+    
+    // Resume is now completely anonymous (Zero EEOC bias risk)
+    // Skills (Python, Kubernetes, Leadership) and achievements are 100% intact.
+    return { anonymousResume: scrubbedText, auditReceipt: telemetry };
+}
+```
+
+### 3. B2B Invoice & Expense Reconciliation Pipeline
+*Redacts corporate payment accounts (PCI-DSS), direct deposit info, and signatory names while preserving line items, tax rates (VAT/Sales Tax), quantities, and chart-of-accounts codes.*
+
+```javascript
+import { sanitize, restore } from '@privacyscrubber/sdk';
+
+function processVendorInvoice(invoiceText) {
+    const { scrubbedText, tokenMap } = sanitize(invoiceText, { profile: 'Accounting' });
+    // Line items ($350.00, $1,200.00) and general ledger accounts remain fully intact for AI categorization.
+    return { scrubbedText, tokenMap };
+}
+```
+
+---
+
+## 🔑 License Activation & Commercial Tiers
+
+PrivacyScrubber works free out-of-the-box with standard limits:
+- **Free Tier**: Up to 15,000 characters per request, General & standard profiles.
+- **PRO & TEAMS Tiers**: Unlimited throughput, all 23 specialized compliance profiles, custom regex rules, multi-user sync.
+
+### Activating Your License
+
+Set the environment variable or pass your key explicitly:
+
+```bash
+export PRIVACYSCRUBBER_KEY="your-license-key-here"
+```
+
+```javascript
+import { sanitize, validateLicense } from '@privacyscrubber/sdk';
+
+// Validate programmatically
+const license = validateLicense(process.env.PRIVACYSCRUBBER_KEY);
+console.log(`Active Tier: ${license.tier}, Valid: ${license.valid}`);
+
+// Or pass directly in options
+const result = sanitize(largeDocument, {
+    licenseKey: 'PS-PRO-XXXX-XXXX',
+    profile: 'Medical'
+});
+```
+
+To purchase or upgrade a license, visit:  
+👉 **[PrivacyScrubber Pricing & Licensing](https://privacyscrubber.com/pricing?utm_source=npm_core&utm_medium=readme&utm_campaign=dev_upsell)**
+
+---
+
+## 🛡️ Supported Compliance Frameworks
+
+- **GDPR (Art. 4)**: Direct & indirect personal identifiers.
+- **HIPAA (§164.514 Safe Harbor)**: 18 protected health information identifiers (MRN, dates, clinical IDs).
+- **PCI-DSS v4.0**: Primary Account Numbers (PAN), CVVs, banking tokens.
+- **SOC 2 Type II / ISO 27001 (A.8.11)**: Data masking and access segregation.
+- **NIST SP 800-53**: Automated secrets and credential redaction.
+
+---
+
+## 📄 Legacy API Compatibility
+
+Full backward compatibility is retained for existing integrations using `scrubText` and `unscrubText`:
+
+```javascript
+import { scrubText, unscrubText } from '@privacyscrubber/sdk';
+
+const result = scrubText("Raw text", [], {}, 'General', {}, true);
+const restored = unscrubText(result.scrubbedText, result.tokenMap);
+```
+
+---
+
+## 🔗 Ecosystem & Links
+
+- 🌐 **Web App**: [https://privacyscrubber.com](https://privacyscrubber.com)
+- 🔌 **MCP Server**: [@privacyscrubber/mcp-server](https://www.npmjs.com/package/@privacyscrubber/mcp-server)
+- 🧩 **Chrome Extension**: [Chrome Web Store](https://chromewebstore.google.com/detail/privacyscrubber/gmmimjcmidhmbjcbgeojpajefebfepco)
+- 📖 **Documentation & Support**: [https://privacyscrubber.com/docs](https://privacyscrubber.com/docs)
+- 💬 **Feedback & Feature Requests**: [https://privacyscrubber.com/feedback](https://privacyscrubber.com/feedback)
+
+---
+
+## ⚖️ License
+
+MIT License © 2026 PrivacyScrubber. Commercial features require an active PRO/TEAMS license.

package/index.d.ts

@@ -0,0 +1,217 @@
+/**
+ * TypeScript Definitions for @privacyscrubber/sdk
+ */
+
+export interface CustomRule {
+    name: string;
+    regex: RegExp;
+    mask?: string;
+    type?: string;
+}
+
+export type PiiProfile = 
+    | 'General'
+    | 'Dev'
+    | 'Medical'
+    | 'Financial'
+    | 'Legal'
+    | 'HR'
+    | 'Security'
+    | 'Marketing'
+    | 'BizOps'
+    | 'Sales'
+    | 'Support'
+    | 'RealEstate'
+    | 'Compliance'
+    | 'CCPA'
+    | 'Engineering'
+    | 'Agents'
+    | 'Academic'
+    | 'Creative'
+    | 'Tech'
+    | 'Personal'
+    | 'WealthMgmt'
+    | 'Insurance'
+    | 'Accounting'
+    | 'Pharma'
+    | 'Underwriting'
+    | 'Crypto'
+    | 'Cloud'
+    | 'E-Commerce'
+    | 'Education'
+    | 'Telecom'
+    | 'Cybersecurity'
+    | 'Gaming'
+    | 'Government'
+    | 'Automotive'
+    | 'SocialMedia'
+    | 'Logistics'
+    | 'Energy'
+    | 'Hospitality'
+    | 'Travel'
+    | 'Defense'
+    | string;
+
+export interface SanitizeOptions {
+    /** Target compliance profile (Default: 'General'). */
+    profile?: PiiProfile;
+    /** PrivacyScrubber PRO / TEAMS / SDK / ENTERPRISE license key. */
+    licenseKey?: string;
+    /** Custom regex rules array. */
+    customRules?: CustomRule[];
+    /** Custom label mappings (e.g. { NAME: 'INDIVIDUAL' }). */
+    tokenLabelMap?: Record<string, string>;
+    /** Pre-existing token session map for stateful conversation tracking. */
+    existingSessionMap?: Record<string, string>;
+    /** Whether to generate a CISO Markdown audit receipt (Default: true). */
+    generateReceipt?: boolean;
+    /** Throw PrivacyScrubberLicenseError when free tier limits are reached (Default: true). */
+    throwOnLimit?: boolean;
+}
+
+export interface LicenseMetadata {
+    isPro: boolean;
+    tier: 'PRO' | 'TEAMS' | 'SDK' | 'ENTERPRISE' | 'OEM' | 'FREE';
+    limit: number;
+    upgradeUrl?: string;
+    recommendation?: string;
+}
+
+export interface AuditTelemetry {
+    totalCount: number;
+    entities: Record<string, number>;
+    types: string[];
+    riskLevel: 'CLEAN (ZERO PII)' | 'LOW EXPOSURE' | 'MODERATE EXPOSURE' | 'CRITICAL (HIGH EXPOSURE)';
+    frameworksList: string[];
+}
+
+export interface SanitizeResult {
+    /** The scrubbed text with PII/secrets masked. */
+    scrubbedText: string;
+    /** The volatile in-memory token map needed to restore data. */
+    tokenMap: Record<string, string>;
+    /** Total number of tokens masked. */
+    count: number;
+    /** Execution duration in milliseconds. */
+    executionMs: number;
+    /** Active license state and tier info. */
+    license: LicenseMetadata;
+    /** CISO compliance telemetry. */
+    telemetry: AuditTelemetry;
+    /** Markdown formatted compliance audit receipt. */
+    auditReceipt: string;
+}
+
+export interface RestoreResult {
+    /** The desanitized text with original values restored. */
+    restoredText: string;
+    /** Number of tokens restored. */
+    restoredCount: number;
+}
+
+export interface LicenseValidationResult {
+    valid: boolean;
+    tier: 'PRO' | 'TEAMS' | 'SDK' | 'ENTERPRISE' | 'OEM' | null;
+    expires: number | null;
+    error: string | null;
+}
+
+export class PrivacyScrubberLicenseError extends Error {
+    tier: string;
+    currentLength: number;
+    limit: number;
+    profile: string;
+    upgradeUrl: string;
+}
+
+export function validateLicense(key: string): LicenseValidationResult;
+export function validateLicenseKey(key: string): 'PRO' | 'TEAMS' | 'SDK' | 'ENTERPRISE' | 'OEM' | null;
+
+export function buildAuditTelemetry(currentTokenMap?: Record<string, string> | string[]): AuditTelemetry;
+export function formatAuditReceipt(telemetry: AuditTelemetry): string;
+
+/**
+ * Sanitizes input text, masking all PII and secrets with zero network requests.
+ */
+export function sanitize(text: string, options?: SanitizeOptions): SanitizeResult;
+export function scrub(text: string, options?: SanitizeOptions): SanitizeResult;
+
+/**
+ * Restores masked tokens in AI outputs back to original plaintext in-memory.
+ */
+export function restore(aiResponse: string, tokenMap: Record<string, string>): RestoreResult;
+export function unscrub(aiResponse: string, tokenMap: Record<string, string>): RestoreResult;
+
+export interface EngineConfig {
+    licenseKey?: string;
+    apiKey?: string;
+    defaultProfile?: PiiProfile;
+    profile?: PiiProfile;
+    customRules?: CustomRule[];
+    tokenLabelMap?: Record<string, string>;
+    generateReceipt?: boolean;
+    initialSessionMap?: Record<string, string>;
+}
+
+export class PrivacyScrubberEngine {
+    constructor(config?: EngineConfig);
+    setLicenseKey(key: string): LicenseValidationResult;
+    sanitize(text: string, options?: SanitizeOptions & { persistSession?: boolean }): SanitizeResult;
+    restore(aiResponse: string, tokenMap?: Record<string, string> | null): RestoreResult;
+    resetSession(): void;
+}
+
+/**
+ * Transparent zero-trust wrapper for OpenAI SDK client.
+ */
+export function wrapOpenAI<T = any>(openaiClient: T, options?: SanitizeOptions): T;
+
+/**
+ * Middleware transform for LangChain and LlamaIndex pipelines.
+ */
+export function createLangChainTransform(options?: SanitizeOptions): {
+    preprocess: (input: string) => SanitizeResult;
+    postprocess: (output: string, tokenMap: Record<string, string>) => RestoreResult;
+};
+
+// Legacy exports
+export function scrubText(
+    text: string,
+    customRules?: any[],
+    tokenLabelMap?: Record<string, string>,
+    profile?: string,
+    existingSessionMap?: Record<string, string>,
+    isPro?: boolean
+): {
+    scrubbedText: string;
+    tokenMap: Record<string, string>;
+    count: number;
+    executionMs: number;
+};
+
+export function unscrubText(
+    aiResponse: string,
+    tokenMap: Record<string, string>
+): {
+    restoredText: string;
+    restoredCount: number;
+};
+
+declare const defaultExport: {
+    sanitize: typeof sanitize;
+    scrub: typeof scrub;
+    restore: typeof restore;
+    unscrub: typeof unscrub;
+    validateLicense: typeof validateLicense;
+    validateLicenseKey: typeof validateLicenseKey;
+    buildAuditTelemetry: typeof buildAuditTelemetry;
+    formatAuditReceipt: typeof formatAuditReceipt;
+    PrivacyScrubberEngine: typeof PrivacyScrubberEngine;
+    PrivacyScrubberLicenseError: typeof PrivacyScrubberLicenseError;
+    wrapOpenAI: typeof wrapOpenAI;
+    createLangChainTransform: typeof createLangChainTransform;
+    scrubText: typeof scrubText;
+    unscrubText: typeof unscrubText;
+};
+
+export default defaultExport;