@privacyscrubber/sdk 2.3.5 → 2.3.7

package/index.cjs

@@ -0,0 +1,2682 @@
+/**
+ * PrivacyScrubber Developer SDK (@privacyscrubber/sdk)
+ * Zero-Trust Data Sanitization & PII Redaction Engine.
+ * 
+ * 100% Client-Side / Server-Side in-memory execution.
+ * Zero telemetry network requests. Zero data leakage.
+ * 
+ * https://privacyscrubber.com
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+const { Transform } = require('stream');
+
+require('./polyfill.js');
+require('./ps-license-manager.js');
+
+// Access LicenseManager from global scope
+const LicenseManager = (typeof globalThis !== 'undefined' && globalThis.LicenseManager)
+    || (typeof global !== 'undefined' && global.LicenseManager)
+    || (typeof window !== 'undefined' && window.LicenseManager);
+
+// Synchronously load the production CJS core engine
+require('./scrubber-core.cjs');
+const scrubberPkg = (typeof globalThis !== 'undefined' && globalThis.PrivacyScrubberCore) 
+    || (typeof global !== 'undefined' && global.PrivacyScrubberCore)
+    || (typeof window !== 'undefined' && window.PrivacyScrubberCore);
+
+if (scrubberPkg && typeof scrubberPkg.init === 'function') {
+    scrubberPkg.init();
+}
+
+/**
+ * Built-in patterns for DevOps & Cloud Secrets detection.
+ */
+const DEVOPS_SECRETS_DETECTOR = [
+    { name: 'AWS Credentials', regex: /\b(?:AKIA|ASIA|AGPA|AIDA|AROA|AIPA)[A-Z0-9]{16}\b/g, label: 'AWS_KEY' },
+    { name: 'JSON Web Token (JWT)', regex: /\beyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\b/g, label: 'JWT_TOKEN' },
+    { name: 'API Token/Key (GitHub/Slack/NPM)', regex: /\b(?:ghp|gho|ghu|ghs|ghr|glpat|npm|xox[baprs])[-_][A-Za-z0-9_]{10,}\b/g, label: 'API_TOKEN' },
+    { name: 'Stripe API Key', regex: /\b(?:[rs]k)_(?:test|live)_[a-zA-Z0-9]{24,}\b/g, label: 'STRIPE_KEY' },
+    { name: 'OpenAI Project API Key', regex: /\b(?:sk|pk)-(?:proj-)?[a-zA-Z0-9_-]{16,}\b/gi, label: 'OPENAI_KEY' },
+    { name: 'Database Connection URI', regex: /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqp|mssql):\/\/[^\s"']+/gi, label: 'DB_URI' },
+    { name: 'Embedded Credentials URI', regex: /\b(?:https?|s?ftp):\/\/[a-zA-Z0-9_.%+-]+:[^\s/@:"']+@[a-zA-Z0-9_.-]+(?::\d+)?(?:\/[^\s"']*)?/gi, label: 'SECRET' },
+    { name: 'URL Query Parameter Secret', regex: /(?<=[?&](?:api_key|apikey|access_token|client_secret|auth_token|token|secret|password|private_key)=)[^\s"'\x26#)>]{8,}/gi, label: 'SECRET' },
+    { name: 'Bearer / Auth Header Token', regex: /(?<=\b(?:Bearer|Token)\s+)[a-zA-Z0-9_\-\.~+/=]{16,}\b/gi, label: 'SECRET' },
+    { name: 'Database/API Secret', regex: /\b(DB|POSTGRES|REDIS|MYSQL|AWS|SECRET|PASSWORD|TOKEN|API|KEY)[A-Z0-9_]*\s*[:=]\s*[^ \t\r\n"']{8,}\b/gi, label: 'SECRET' },
+    { name: 'Private Cryptographic Key (PEM Block)', regex: /-----BEGIN (?:RSA |EC |PGP |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----[\s\S]{10,8192}?-----END (?:RSA |EC |PGP |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/g, label: 'SECRET' },
+    { name: 'Private Cryptographic Key (Header)', regex: /-----BEGIN (?:RSA |EC |PGP |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/g, label: 'SECRET' }
+];
+
+/**
+ * Custom Error thrown when Free Tier limits are exceeded.
+ */
+class PrivacyScrubberLicenseError extends Error {
+    constructor(message, { tier = 'FREE', currentLength = 0, limit = 15000, profile = 'General' } = {}) {
+        super(message);
+        this.name = 'PrivacyScrubberLicenseError';
+        this.tier = tier;
+        this.currentLength = currentLength;
+        this.limit = limit;
+        this.profile = profile;
+        this.upgradeUrl = 'https://privacyscrubber.com/pricing?utm_source=npm_sdk&utm_medium=sdk_error&utm_campaign=dev_upsell';
+    }
+}
+
+/**
+ * Validates a PrivacyScrubber license key (RS256 JWT or Cryptographic Checksum).
+ * @param {string} key - License key string.
+ * @returns {{ valid: boolean, tier: 'PRO'|'TEAMS'|null, expires: number|null, error: string|null }}
+ */
+function validateLicense(key) {
+    if (!key || typeof key !== 'string') {
+        return { valid: false, tier: null, expires: null, error: 'No license key provided.' };
+    }
+    const cleanKey = key.trim();
+    if (!LicenseManager || typeof LicenseManager.validate !== 'function') {
+        return { valid: false, tier: null, expires: null, error: 'License manager engine unavailable.' };
+    }
+    const result = LicenseManager.validate(cleanKey);
+    return {
+        valid: !!result.valid,
+        tier: result.valid ? (result.tier || 'PRO') : null,
+        expires: result.expires || null,
+        error: result.valid ? null : (result.reason || 'Invalid license key.')
+    };
+}
+
+/**
+ * Legacy validator helper returning active tier or null.
+ * @param {string} key 
+ * @returns {'PRO'|'TEAMS'|null}
+ */
+function validateLicenseKey(key) {
+    const res = validateLicense(key);
+    return res.valid ? res.tier : null;
+}
+
+/**
+ * Builds CISO-grade compliance audit telemetry from masked tokens.
+ * @param {Record<string, string>|string[]} currentTokenMap 
+ * @returns {object}
+ */
+function buildAuditTelemetry(currentTokenMap = {}) {
+    const entities = {};
+    let totalCount = 0;
+
+    if (currentTokenMap && typeof currentTokenMap === 'object') {
+        const keys = Array.isArray(currentTokenMap) ? currentTokenMap : Object.keys(currentTokenMap);
+        for (const t of keys) {
+            if (!t) continue;
+            const tokenStr = typeof t === 'string' ? t : ((t && (t.token || t.mask)) ? String(t.token || t.mask) : '');
+            if (!tokenStr) continue;
+            const match = tokenStr.match(/\[([A-Z_]+)_\d+\]/);
+            const baseType = match ? match[1] : (tokenStr.replace(/\[|\]/g, '').replace(/_[0-9]+$/, '') || 'CUSTOM');
+            entities[baseType] = (entities[baseType] || 0) + 1;
+            totalCount++;
+        }
+    }
+
+    const types = Object.keys(entities);
+    let riskLevel = 'LOW EXPOSURE';
+
+    if (totalCount > 0) {
+        const hasHighRisk = types.some(t => ['ID', 'SSN', 'CREDIT_CARD', 'PASSPORT', 'BANK', 'API_KEY', 'SECRET', 'PASSWORD', 'MRN', 'KEY', 'AWS_KEY', 'STRIPE_KEY', 'JWT_TOKEN', 'API_TOKEN'].includes(t));
+        if (hasHighRisk || types.length >= 3 || totalCount >= 10) {
+            riskLevel = 'CRITICAL (HIGH EXPOSURE)';
+        } else if (types.length >= 2 || totalCount >= 3) {
+            riskLevel = 'MODERATE EXPOSURE';
+        } else {
+            riskLevel = 'LOW EXPOSURE';
+        }
+    } else {
+        riskLevel = 'CLEAN (ZERO PII)';
+    }
+
+    const frameworksSet = new Set(['ZTDS Standard']);
+    if (types.includes('NAME') || types.includes('EMAIL') || types.includes('PHONE')) {
+        frameworksSet.add('GDPR (Art. 4)');
+        frameworksSet.add('CCPA/CPRA');
+    }
+    if (types.includes('ID') || types.includes('SSN') || types.includes('PASSPORT') || types.includes('NATIONAL_ID')) {
+        frameworksSet.add('SOC 2 Type II');
+        frameworksSet.add('ISO 27001 (A.8.11)');
+    }
+    if (types.some(t => ['CREDIT_CARD', 'BANK', 'IBAN', 'FINANCIAL', 'CARD', 'STRIPE_KEY', 'TAX_ID', 'EIN', 'W2', '1099', 'SALARY', 'WAGE'].includes(t))) {
+        frameworksSet.add('PCI DSS v4.0');
+        frameworksSet.add('IRC § 7216 & GLBA');
+    }
+    if (types.some(t => ['MRN', 'HEALTH', 'MEDICAL', 'PATIENT', 'DIAGNOSIS', 'NPI', 'DEA'].includes(t))) {
+        frameworksSet.add('HIPAA §164.514');
+    }
+    if (types.some(t => ['CASE_NUMBER', 'DOCKET', 'PRIVILEGED', 'LEGAL', 'ATTORNEY', 'COURT', 'CONTRACT', 'NDA'].includes(t))) {
+        frameworksSet.add('FRE 502 (Privilege)');
+    }
+    if (types.some(t => ['API_KEY', 'SECRET', 'PASSWORD', 'TOKEN', 'KEY', 'AWS_KEY', 'JWT_TOKEN', 'API_TOKEN', 'CREDENTIAL'].includes(t))) {
+        frameworksSet.add('NIST SP 800-53');
+    }
+    if (totalCount > 0) {
+        frameworksSet.add('EU AI Act (Art. 50)');
+    }
+
+    const ipHoldings = {
+        standard: 'IETF draft-sibiryakov-ztds-protocol-00',
+        standardUrl: 'https://datatracker.ietf.org/doc/draft-sibiryakov-ztds-protocol/',
+        patent: "U.S. & Int'l Patents Pending (Paris Convention Priority)",
+        trademark: 'ZTDS™ Reg. #182655957 (ILPO Cl 9 & 42)'
+    };
+
+    const statutoryCitations = [
+        {
+            statute: 'EU AI Act (Art. 50)',
+            scope: 'AI Transparency & Data Minimization',
+            rule: '0-byte external network transmission; prevents unauthorized ingestion into frontier models.'
+        },
+        {
+            statute: 'GDPR (Art. 4, 25, 28, 32)',
+            scope: 'Pseudonymization & Processor Liability',
+            rule: 'Volatile client-side tokenization eliminates GDPR Article 28 data processor liability.'
+        },
+        {
+            statute: 'HIPAA 45 CFR § 164.514(b)',
+            scope: 'Safe Harbor De-Identification',
+            rule: 'Deterministic removal of all 18 PHI identifiers prior to AI analysis.'
+        },
+        {
+            statute: 'IRC § 7216 & IRS Pub. 1075',
+            scope: 'Tax Return Information Confidentiality',
+            rule: 'Strict criminal penalty safeguard against unauthorized disclosure of tax records to cloud LLMs.'
+        },
+        {
+            statute: 'FRE 502',
+            scope: 'Attorney-Client Privilege Preservation',
+            rule: 'Automated in-memory redaction prevents inadvertent waiver of legal privilege in AI workflows.'
+        }
+    ];
+
+    return {
+        totalCount,
+        entities,
+        types,
+        riskLevel,
+        frameworksList: Array.from(frameworksSet),
+        statutoryCitations,
+        ipHoldings,
+        multimodalEgress: '0.00 Bytes (Solid Blackout & Burn-in Verified)'
+    };
+}
+
+/**
+ * SSOT Alias for cross-plane parity with Web, Extension, and MCP.
+ */
+const buildCisoAuditTelemetry = buildAuditTelemetry;
+
+/**
+ * Formats structured audit telemetry into a human-readable Markdown Audit Receipt.
+ * @param {object} telemetry 
+ * @returns {string}
+ */
+function formatAuditReceipt(telemetry) {
+    if (!telemetry || telemetry.totalCount === 0) {
+        return "> 🛡️ **PrivacyScrubber Audit Receipt**: CLEAN (ZERO PII DETECTED)\n" +
+               "> * ⭐ **Star on GitHub:** [moxno/privacyscrubber-mcp](https://github.com/moxno/privacyscrubber-mcp) | **SDK & Enterprise:** [privacyscrubber.com/pricing](https://privacyscrubber.com/pricing)\n";
+    }
+    const entitiesList = Object.entries(telemetry.entities)
+        .map(([type, count]) => `${count} ${type}`)
+        .join(', ');
+
+    const icon = telemetry.riskLevel.includes('CRITICAL') ? '🔴' : (telemetry.riskLevel.includes('MODERATE') ? '🟠' : '🟢');
+
+    return `> 🛡️ **PrivacyScrubber Audit Receipt**\n` +
+           `> * **Risk Level:** ${icon} ${telemetry.riskLevel}\n` +
+           `> * **Compliance Enforced:** ${telemetry.frameworksList.join(', ')}\n` +
+           `> * **Tokens Masked:** ${telemetry.totalCount} (${entitiesList})\n` +
+           `> * ⭐ **Star on GitHub:** [moxno/privacyscrubber-mcp](https://github.com/moxno/privacyscrubber-mcp) | **SDK & Enterprise:** [privacyscrubber.com/pricing](https://privacyscrubber.com/pricing)\n`;
+}
+
+let communityNoticeLogged = false;
+
+function emitCommunityNoticeIfNeeded(isPro) {
+    if (communityNoticeLogged || isPro) return;
+    if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') {
+        communityNoticeLogged = true;
+        console.info('[@privacyscrubber/sdk] Running Community Edition (Core PII).\nTo unlock 25 Enterprise Profiles & DevOps Secrets in production: https://privacyscrubber.com/pricing/?tier=sdk');
+    }
+}
+
+/**
+ * Resets the community notice state for testing purposes.
+ * @private
+ */
+function _resetCommunityNoticeForTesting() {
+    communityNoticeLogged = false;
+}
+
+let devSecretNoticeLogged = false;
+
+function emitDevSecretNoticeIfNeeded(isPro, tokenMap = {}, limit = 15000) {
+    if (devSecretNoticeLogged || isPro) return;
+    if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') return;
+
+    const tokens = Object.keys(tokenMap || {});
+    const secretTokens = tokens.filter(t => {
+        const upper = t.toUpperCase();
+        return ['API_KEY', 'SECRET', 'PASSWORD', 'KEY', 'AWS_KEY', 'STRIPE_KEY', 'JWT_TOKEN', 'API_TOKEN', 'TOKEN'].some(k => upper.includes(k));
+    });
+
+    if (secretTokens.length > 0) {
+        devSecretNoticeLogged = true;
+        const count = secretTokens.length;
+        const secretSample = secretTokens.slice(0, 2).join(', ');
+        if (typeof process !== 'undefined' && process.stderr && typeof process.stderr.write === 'function') {
+            process.stderr.write(
+                `\n[PrivacyScrubber] Intercepted ${count} API secret(s) before LLM egress: ${secretSample}\n` +
+                `[PrivacyScrubber] Protected in local RAM (0 byte network egress). Free Tier active (${limit.toLocaleString()} char cap).\n` +
+                `[PrivacyScrubber] Developer SDK ($299/mo flat) for unlimited backend nodes, CI/CD gates & ETL pipelines: https://privacyscrubber.com/pricing?tier=sdk&src=cli_leak_guard\n\n`
+            );
+        }
+    }
+}
+
+/**
+ * Resets the dev secret notice state for testing purposes.
+ * @private
+ */
+function _resetDevSecretNoticeForTesting() {
+    devSecretNoticeLogged = false;
+}
+
+/**
+ * Generates an executive CISO & Legal Procurement Memo for enterprise approval of @privacyscrubber/sdk.
+ * 
+ * @param {object} [options={}] - Custom memo configuration options.
+ * @param {string} [options.appName='Internal AI Applications & LLM Pipelines'] - Target system name.
+ * @param {string} [options.developer='Engineering / AI Platform Team'] - Authoring team name.
+ * @param {'markdown'|'text'} [options.format='markdown'] - Output format ('markdown' or 'text').
+ * @param {number} [options.teamSize=10] - Size of engineering team.
+ * @param {string} [options.estimatedVolume='50M - 500M characters/month'] - Projected token volume.
+ * @returns {string}
+ */
+function generateProcurementMemo(options = {}) {
+    const {
+        appName = 'Internal AI Applications & LLM Pipelines',
+        developer = 'Engineering / AI Platform Team',
+        format = 'markdown',
+        teamSize = 10,
+        estimatedVolume = '50M - 500M characters/month'
+    } = options;
+
+    if (format === 'text') {
+        return `MEMORANDUM: ADOPTION OF PRIVACYSCRUBBER DEVELOPER SDK (ZTDS STANDARD)
+
+TO: Chief Information Security Officer (CISO), Data Protection Officer (DPO), VP Engineering
+FROM: ${developer}
+SUBJECT: Approval Request: Zero-Trust Data Sanitization (@privacyscrubber/sdk)
+TARGET SYSTEM: ${appName}
+ESTIMATED VOLUME: ${estimatedVolume}
+
+1. EXECUTIVE SUMMARY
+We propose standardizing on the PrivacyScrubber Developer SDK (@privacyscrubber/sdk) for in-memory Zero-Trust Data Sanitization across our AI ingestion pipelines. The SDK intercepts and redacts PII, regulatory identifiers, and cloud secrets locally in RAM before any prompt leaves our infrastructure.
+
+2. ZERO-TRUST ARCHITECTURAL INVARIANTS
+* Zero Network Egress: 100% local in-memory processing. Zero external API calls, zero telemetry egress, zero third-party sub-processors.
+* In-Memory Volatility: All masking maps remain in volatile process RAM and are discarded after request completion.
+* Sub-Millisecond Latency: Executes in <0.1ms per prompt in local RAM, eliminating latency overhead.
+
+3. COMPLIANCE & REGULATORY COVERAGE
+Pre-configured for 30 specialized industry profiles and compliance frameworks:
+* GDPR (Art. 4, 9, 32) & CCPA/CPRA: Ephemeral tokenization.
+* HIPAA (§164.514 Safe Harbor): MRNs, medical record codes, patient identifiers.
+* SOC 2 Type II & ISO 27001 (A.8.11): Zero persistent unencrypted PII.
+* PCI DSS v4.0: PAN, CVV, IBAN, bank ledger sanitization.
+* NIST SP 800-53: Cloud API keys, JWT tokens, AWS/Stripe secret leak protection.
+
+4. TOTAL COST OF OWNERSHIP (TCO) COMPARISON
+* Cloud DLP Proxies (AWS Macie, GCP DLP, Nightfall):
+  - Cost: $1,500 - $4,000 / month (usage-based billing).
+  - Latency: +200ms - 400ms added network roundtrip per AI prompt.
+  - Sub-processor Risk: Requires vendor DPA, external network egress.
+* PrivacyScrubber Developer SDK:
+  - Cost: $299 / month flat (or $2,990 / year) for unlimited nodes, microservices, and prompts.
+  - Latency: <0.1ms (in-process RAM).
+  - Sub-processor Risk: Zero (pure in-memory software library).
+
+5. ACTION REQUESTED
+Approve commercial license upgrade for ${developer} (${teamSize} engineers, unlimited backend nodes):
+* License Tier: Developer SDK ($299/month flat or $2,990/year)
+* Direct Procurement & License Activation: https://privacyscrubber.com/pricing?tier=sdk&src=ciso_memo
+* Enterprise / Invoicing Contact: enterprise@privacyscrubber.com
+`;
+    }
+
+    return `# Internal Memo: Adoption of PrivacyScrubber Developer SDK (ZTDS Standard)
+
+| **To** | Chief Information Security Officer (CISO), Data Protection Officer (DPO), VP Engineering |
+| :--- | :--- |
+| **From** | ${developer} |
+| **Date** | ${new Date().toISOString().split('T')[0]} |
+| **Subject** | Architectural Approval & License Procurement for Zero-Trust AI Sanitization |
+| **Target System** | ${appName} |
+| **Estimated Scope** | ~${teamSize} engineers / ${estimatedVolume} |
+
+---
+
+### 1. Executive Summary
+We recommend adopting the **PrivacyScrubber Developer SDK** (\`@privacyscrubber/sdk\`) to enforce **Zero-Trust Data Sanitization (ZTDS)** across all internal AI pipelines, LangChain agents, microservices, and developer toolchains.
+
+The SDK redacts PII, regulatory identifiers, and developer secrets **in-process before external API egress to OpenAI, Anthropic, or external LLM providers**, and deterministically restores original values upon response return.
+
+---
+
+### 2. Architectural Invariants (Zero-Trust Data Sanitization)
+* **Zero Remote Network Egress:** 100% of sanitization and token restoration executes in local Node.js process RAM. No prompt data or telemetry ever leaves our VPC/infrastructure.
+* **Ephemeral In-Memory Tokens:** Masking mappings (\`[EMAIL_1]\`, \`[NAME_1]\`, \`[SECRET_1]\`) are volatile and strictly scoped to request execution context.
+* **Ultra-Low Latency:** Micro-benchmarks verify <0.1ms execution overhead per prompt, compared to 200–400ms for network-based cloud DLP proxies.
+* **Full Reversibility:** Bidirectional round-trip reconstruction ensures downstream application logic receives intact responses without exposing sensitive data to model providers.
+
+---
+
+### 3. Compliance Framework Mapping
+The SDK enforces out-of-the-box sanitization matching mandatory compliance controls:
+* **GDPR (Regulation (EU) 2016/679) & CCPA/CPRA:** Eliminates cross-border PII transfer risk to third-party AI models.
+* **HIPAA (§164.514 Safe Harbor):** Automated scrubbing of Medical Record Numbers (MRNs), patient identifiers, and health insurance IDs.
+* **SOC 2 Type II & ISO 27001 (Control A.8.11):** Enforces data masking and prevents unauthorized logging of confidential client data.
+* **PCI DSS v4.0:** Sanitization of payment cards, IBANs, and financial ledger data.
+* **NIST SP 800-53:** DevOps secret interception for AWS keys, JWT tokens, database URIs, and private API keys.
+
+---
+
+### 4. Financial & Architectural Comparison (TCO)
+
+| Evaluation Factor | Traditional Cloud DLP (AWS/GCP/Nightfall) | PrivacyScrubber Developer SDK |
+| :--- | :--- | :--- |
+| **Pricing Model** | \$1,500 – \$4,000 / month (metered per GB/token) | **\$299 / month flat** (unlimited nodes & tokens) |
+| **Network Egress** | Requires outbound network calls to DLP vendor | **0 bytes** (100% local Node.js process memory) |
+| **Added Latency** | +200ms – +450ms network round-trip | **<0.1ms** (in-memory regular expressions) |
+| **Vendor Sub-processors** | Third-party cloud vendor added to vendor list | **None** (zero-network software library) |
+| **Deployment** | Complex API gateways and proxy configurations | \`npm install @privacyscrubber/sdk\` in 3 minutes |
+
+---
+
+### 5. Procurement Recommendation
+We request approval to acquire a **Developer SDK License** (\$299/month flat or \$2,990/year) to unlock unlimited throughput across all microservices and CI/CD pipelines.
+
+* **Direct Procurement Portal:** [https://privacyscrubber.com/pricing?tier=sdk&src=ciso_memo](https://privacyscrubber.com/pricing?tier=sdk&src=ciso_memo)
+* **Procurement / Invoicing Contact:** \`enterprise@privacyscrubber.com\`
+`;
+}
+
+/**
+ * Sanitizes input text, masking detected PII & secrets with reversible tokens.
+ * 
+ * @param {string} text - Raw input text.
+ * @param {object} [options={}] - Sanitization options.
+ * @param {string} [options.profile='General'] - Compliance detection profile.
+ * @param {string} [options.licenseKey] - Optional license key. Falls back to process.env.PRIVACYSCRUBBER_KEY.
+ * @param {Array<{name: string, pattern: string, regex: RegExp, label?: string}>} [options.customRules=[]] - Custom regex rules.
+ * @param {Record<string, string>} [options.tokenLabelMap={}] - Custom label mapping.
+ * @param {Record<string, string>} [options.existingSessionMap={}] - In-memory session map to preserve token IDs across turns.
+ * @param {boolean} [options.generateReceipt=true] - Generate a CISO Markdown audit receipt.
+ * @param {boolean} [options.throwOnLimit=true] - Throw PrivacyScrubberLicenseError when free tier limit is hit.
+ * @param {'throw'|'truncate'} [options.onLimit='throw'] - Action when character limit exceeded ('throw' or 'truncate').
+ * @param {boolean} [options.detectSecrets=false] - Auto-detect cloud credentials and API keys.
+ * @param {Set<string>|Array<string>} [options.ignoreList=null] - Values to preserve in cleartext.
+ * @returns {{
+ *   scrubbedText: string,
+ *   tokenMap: Record<string, string>,
+ *   count: number,
+ *   executionMs: number,
+ *   license: { isPro: boolean, tier: 'PRO'|'TEAMS'|'FREE', limit: number, wasTruncated: boolean, upgradeUrl?: string, recommendation?: string },
+ *   telemetry: object,
+ *   auditReceipt: string
+ * }}
+ */
+function sanitize(text, options = {}) {
+    if (!text || typeof text !== 'string') {
+        return {
+            scrubbedText: '',
+            tokenMap: {},
+            count: 0,
+            executionMs: 0,
+            license: { isPro: false, tier: 'FREE', limit: 15000, wasTruncated: false },
+            telemetry: buildAuditTelemetry({}),
+            auditReceipt: formatAuditReceipt(buildAuditTelemetry({}))
+        };
+    }
+
+    const {
+        profile = 'General',
+        licenseKey = (typeof process !== 'undefined' && process.env?.PRIVACYSCRUBBER_KEY) || '',
+        customRules = [],
+        tokenLabelMap = {},
+        existingSessionMap = {},
+        generateReceipt = true,
+        throwOnLimit = true,
+        onLimit = 'throw',
+        detectSecrets = false,
+        ignoreList = null
+    } = options;
+
+    const licenseCheck = validateLicense(licenseKey);
+    const rawTier = licenseCheck.valid ? (licenseCheck.tier || 'PRO') : 'FREE';
+
+    // Anti-Cannibalization Barrier (SSOT):
+    // PRO ($15/mo) and TEAMS ($99/mo) licenses are strictly human-seat licenses for Web App & Chrome Extension.
+    // Backend automation, microservices, RAG pipelines, and headless SDK execution require Developer SDK, OEM, or ENTERPRISE ($299/mo).
+    const isSdkTier = licenseCheck.valid && ['SDK', 'OEM', 'ENTERPRISE'].includes(rawTier);
+    const isSeatTier = licenseCheck.valid && ['PRO', 'TEAMS'].includes(rawTier);
+
+    if (isSeatTier) {
+        const keyPreview = licenseKey ? `${licenseKey.slice(0, 12)}...` : '';
+        const errorMsg = `[PrivacyScrubber] License tier mismatch: ${rawTier} license (${keyPreview}) is licensed strictly for human seats (Web App & Chrome Extension). Backend automation, microservices, and CRM pipelines require a Developer SDK license ($299/mo). Upgrade: https://privacyscrubber.com/pricing?tier=sdk&src=seat_tier_mismatch`;
+        if (throwOnLimit !== false) {
+            throw new PrivacyScrubberLicenseError(errorMsg, {
+                tier: rawTier,
+                currentLength: text.length,
+                limit: 15000,
+                profile: profile
+            });
+        }
+    }
+
+    const isPro = isSdkTier;
+    const tier = isPro ? rawTier : (isSeatTier ? rawTier : 'FREE');
+
+    emitCommunityNoticeIfNeeded(isPro);
+
+    const isSpecialized = profile && profile.toLowerCase() !== 'general';
+    const limit = isPro ? Infinity : (isSpecialized ? 5000 : 15000);
+
+    const shouldThrow = throwOnLimit && onLimit !== 'truncate';
+    let wasTruncated = false;
+
+    if (!isPro && text.length > limit) {
+        if (shouldThrow) {
+            const errorMsg = `[PrivacyScrubber] Free Tier character limit exceeded (${limit.toLocaleString()} chars for profile '${profile}', received ${text.length.toLocaleString()} chars). Upgrade to Developer SDK ($299/mo) for unlimited throughput: https://privacyscrubber.com/pricing?tier=sdk&src=dev_limit`;
+            throw new PrivacyScrubberLicenseError(errorMsg, {
+                tier: 'FREE',
+                currentLength: text.length,
+                limit: limit,
+                profile: profile
+            });
+        }
+        wasTruncated = true;
+    }
+
+    // Auto-inject DevOps Secrets rules when in Dev profile or when detectSecrets is requested
+    const activeRules = [...customRules];
+    if (profile.toLowerCase() === 'dev' || detectSecrets === true) {
+        DEVOPS_SECRETS_DETECTOR.forEach(rule => {
+            activeRules.push({
+                name: rule.name,
+                pattern: rule.regex.source,
+                regex: new RegExp(rule.regex.source, rule.regex.flags),
+                label: rule.label || 'SECRET'
+            });
+        });
+    }
+
+    const startTime = (typeof performance !== 'undefined' && typeof performance.now === 'function') 
+        ? performance.now() 
+        : Date.now();
+
+    const textToScrub = (!isPro && text.length > limit) ? text.slice(0, limit) : text;
+
+    const rawResult = scrubberPkg.scrubText(
+        textToScrub,
+        activeRules,
+        tokenLabelMap,
+        profile,
+        existingSessionMap,
+        isPro,
+        ignoreList
+    );
+
+    const endTime = (typeof performance !== 'undefined' && typeof performance.now === 'function') 
+        ? performance.now() 
+        : Date.now();
+
+    const executionMs = Math.round((endTime - startTime) * 100) / 100;
+    const telemetry = buildAuditTelemetry(rawResult.tokenMap || {});
+    const auditReceipt = generateReceipt ? formatAuditReceipt(telemetry) : '';
+
+    emitDevSecretNoticeIfNeeded(isPro, rawResult.tokenMap, limit);
+
+    let finalScrubbedText = rawResult.scrubbedText;
+    if (wasTruncated && (onLimit === 'truncate' || throwOnLimit === false)) {
+        finalScrubbedText += `\n\n<!-- [PrivacyScrubber] Input truncated at free tier limit (${limit.toLocaleString()} chars). For unlimited throughput: https://privacyscrubber.com/pricing?tier=sdk&src=truncation -->`;
+    }
+
+    const returnFullSessionMap = options.returnFullSessionMap === true;
+    const sessionMap = { ...(existingSessionMap || {}), ...(rawResult.tokenMap || {}) };
+
+    return {
+        scrubbedText: finalScrubbedText,
+        tokenMap: returnFullSessionMap ? sessionMap : (rawResult.tokenMap || {}),
+        sessionMap: sessionMap,
+        matches: rawResult.matches || [],
+        spans: rawResult.matches || [],
+        count: rawResult.count || 0,
+        executionMs: executionMs,
+        license: {
+            isPro: isPro,
+            tier: tier,
+            limit: limit,
+            wasTruncated: wasTruncated,
+            ...(isSeatTier && {
+                upgradeUrl: 'https://privacyscrubber.com/pricing?tier=sdk&src=seat_tier_mismatch',
+                recommendation: `Your ${rawTier} license is valid for interactive browser seats only. Upgrade to Developer SDK ($299/mo) for unlimited backend server throughput: https://privacyscrubber.com/pricing?tier=sdk`
+            }),
+            ...(!isPro && !isSeatTier && {
+                upgradeUrl: 'https://privacyscrubber.com/pricing?tier=sdk&src=dev_upsell',
+                recommendation: 'Upgrade to Developer SDK ($299/mo) for unlimited backend text processing, custom regex rules, and specialized compliance profiles.'
+            })
+        },
+        telemetry: telemetry,
+        auditReceipt: auditReceipt
+    };
+}
+
+/**
+ * Alias for sanitize.
+ */
+const scrub = sanitize;
+
+/**
+ * Ergonomic 1-liner: Sanitizes text and returns the scrubbed string directly.
+ * @param {string} text - Input text.
+ * @param {string} [profile='General'] - Target compliance profile.
+ * @returns {string} - Scrubbed string.
+ */
+function clean(text, profile = 'General') {
+    if (!text || typeof text !== 'string') return '';
+    const { scrubbedText } = sanitize(text, { profile });
+    return scrubbedText;
+}
+
+/**
+ * Primary High-Level Function: Restore / Unscrub AI response back to original entities in-memory.
+ * 
+ * @param {string} aiResponse - Text containing masked tokens (e.g. [EMAIL_1], [NAME_1]).
+ * @param {Record<string, string>} tokenMap - Volatile token map returned from sanitize().
+ * @returns {{ restoredText: string, restoredCount: number }}
+ */
+function restore(aiResponse, tokenMap = {}) {
+    if (!aiResponse || typeof aiResponse !== 'string') {
+        return { restoredText: '', restoredCount: 0 };
+    }
+    const result = scrubberPkg.unscrubText(aiResponse, tokenMap);
+    return {
+        restoredText: result.restoredText,
+        restoredCount: result.restoredCount || 0
+    };
+}
+
+/**
+ * Alias for restore.
+ */
+const unscrub = restore;
+const desanitize = restore;
+
+/**
+ * Recursively sanitizes all string values within an object or array.
+ * Preserves the exact structure, object keys, numbers, booleans, dates, and nulls.
+ * Maintains unified session token IDs and returns combined audit telemetry.
+ *
+ * @param {any} obj - Object, array, or primitive to sanitize.
+ * @param {object} [options={}] - Standard sanitization options (profile, licenseKey, etc.).
+ * @returns {{
+ *   sanitized: any,
+ *   tokenMap: Record<string, string>,
+ *   count: number,
+ *   executionMs: number,
+ *   telemetry: object,
+ *   auditReceipt: string
+ * }}
+ */
+function sanitizeObject(obj, options = {}) {
+    if (obj === null || obj === undefined) {
+        return {
+            sanitized: obj,
+            tokenMap: {},
+            count: 0,
+            executionMs: 0,
+            telemetry: buildAuditTelemetry({}),
+            auditReceipt: formatAuditReceipt(buildAuditTelemetry({}))
+        };
+    }
+
+    if (typeof obj === 'string') {
+        const res = sanitize(obj, options);
+        return {
+            sanitized: res.scrubbedText,
+            tokenMap: res.tokenMap,
+            count: res.count,
+            executionMs: res.executionMs,
+            telemetry: res.telemetry,
+            auditReceipt: res.auditReceipt
+        };
+    }
+
+    if (typeof obj !== 'object') {
+        return {
+            sanitized: obj,
+            tokenMap: {},
+            count: 0,
+            executionMs: 0,
+            telemetry: buildAuditTelemetry({}),
+            auditReceipt: formatAuditReceipt(buildAuditTelemetry({}))
+        };
+    }
+
+    const startTime = (typeof performance !== 'undefined' && typeof performance.now === 'function') 
+        ? performance.now() 
+        : Date.now();
+
+    const mergedSessionMap = { ...(options.existingSessionMap || {}) };
+    let totalCount = 0;
+
+    function traverseAndSanitize(val) {
+        if (val === null || val === undefined) return val;
+        if (typeof val === 'string') {
+            if (val.trim().length === 0) return val;
+            const res = sanitize(val, {
+                ...options,
+                existingSessionMap: mergedSessionMap,
+                generateReceipt: false
+            });
+            Object.assign(mergedSessionMap, res.tokenMap);
+            totalCount += res.count;
+            return res.scrubbedText;
+        }
+        if (Array.isArray(val)) {
+            return val.map(item => traverseAndSanitize(item));
+        }
+        if (val instanceof Date || val instanceof RegExp) {
+            return val;
+        }
+        if (typeof val === 'object') {
+            const out = {};
+            for (const [k, v] of Object.entries(val)) {
+                out[k] = traverseAndSanitize(v);
+            }
+            return out;
+        }
+        return val;
+    }
+
+    const sanitizedResult = traverseAndSanitize(obj);
+
+    const endTime = (typeof performance !== 'undefined' && typeof performance.now === 'function') 
+        ? performance.now() 
+        : Date.now();
+
+    const executionMs = Math.round((endTime - startTime) * 100) / 100;
+    const telemetry = buildAuditTelemetry(mergedSessionMap);
+    const auditReceipt = options.generateReceipt !== false ? formatAuditReceipt(telemetry) : '';
+
+    return {
+        sanitized: sanitizedResult,
+        tokenMap: mergedSessionMap,
+        count: totalCount,
+        executionMs: executionMs,
+        telemetry: telemetry,
+        auditReceipt: auditReceipt
+    };
+}
+
+/**
+ * Recursively restores all masked tokens within a sanitized object or array using the tokenMap.
+ *
+ * @param {any} obj - Sanitized object, array, or string.
+ * @param {Record<string, string>} tokenMap - Token map returned from sanitize() or sanitizeObject().
+ * @returns {any} - Restored object with original values.
+ */
+function restoreObject(obj, tokenMap = {}) {
+    if (obj === null || obj === undefined) return obj;
+    if (typeof obj === 'string') {
+        const res = restore(obj, tokenMap);
+        return res.restoredText;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(item => restoreObject(item, tokenMap));
+    }
+    if (typeof obj === 'object' && !(obj instanceof Date) && !(obj instanceof RegExp)) {
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            out[k] = restoreObject(v, tokenMap);
+        }
+        return out;
+    }
+    return obj;
+}
+
+/**
+ * Stateful PrivacyScrubber Engine class for backend servers & conversational pipelines.
+ */
+class PrivacyScrubberEngine {
+    constructor(config = {}) {
+        this.licenseKey = config.licenseKey || config.apiKey || (typeof process !== 'undefined' && process.env?.PRIVACYSCRUBBER_KEY) || '';
+        this.defaultProfile = config.defaultProfile || config.profile || 'General';
+        this.customRules = config.customRules || [];
+        this.tokenLabelMap = config.tokenLabelMap || {};
+        this.generateReceipt = config.generateReceipt !== false;
+        this.sessionMap = { ...(config.initialSessionMap || {}) };
+        this.ignoreList = new Set(config.ignoreList || []);
+        this.maxSessionTokens = config.maxSessionTokens || 10000;
+        
+        this.license = validateLicense(this.licenseKey);
+    }
+
+    /**
+     * Updates active license key.
+     * @param {string} key 
+     */
+    setLicenseKey(key) {
+        this.licenseKey = key;
+        this.license = validateLicense(this.licenseKey);
+        return this.license;
+    }
+
+    /**
+     * Sanitizes input text, maintaining stateful session memory if requested.
+     * @param {string} text 
+     * @param {object} [options={}] 
+     */
+    sanitize(text, options = {}) {
+        // Merge instance ignoreList with per-call ignoreList
+        const mergedIgnoreList = new Set(this.ignoreList);
+        if (options.ignoreList) {
+            (Array.isArray(options.ignoreList) ? options.ignoreList : [...options.ignoreList])
+                .forEach(v => mergedIgnoreList.add(v));
+        }
+
+        const mergedOptions = {
+            profile: options.profile || this.defaultProfile,
+            licenseKey: options.licenseKey || this.licenseKey,
+            customRules: [...this.customRules, ...(options.customRules || [])],
+            tokenLabelMap: { ...this.tokenLabelMap, ...(options.tokenLabelMap || {}) },
+            existingSessionMap: options.persistSession !== false ? this.sessionMap : (options.existingSessionMap || {}),
+            generateReceipt: options.generateReceipt !== undefined ? options.generateReceipt : this.generateReceipt,
+            throwOnLimit: options.throwOnLimit !== undefined ? options.throwOnLimit : true,
+            detectSecrets: options.detectSecrets !== undefined ? options.detectSecrets : false,
+            ignoreList: mergedIgnoreList.size > 0 ? mergedIgnoreList : null
+        };
+
+        const result = sanitize(text, mergedOptions);
+        if (options.persistSession !== false) {
+            Object.assign(this.sessionMap, result.tokenMap);
+            const maxTokens = options.maxSessionTokens || this.maxSessionTokens || 10000;
+            const keys = Object.keys(this.sessionMap);
+            if (keys.length > maxTokens) {
+                const pruneCount = keys.length - maxTokens;
+                for (let i = 0; i < pruneCount; i++) {
+                    delete this.sessionMap[keys[i]];
+                }
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Restores AI response using the engine's internal session map or an explicit tokenMap.
+     * @param {string} aiResponse 
+     * @param {Record<string, string>} [tokenMap] 
+     */
+    restore(aiResponse, tokenMap = null) {
+        const activeMap = tokenMap || this.sessionMap;
+        return restore(aiResponse, activeMap);
+    }
+
+    /**
+     * Resets the persistent session token map.
+     */
+    resetSession() {
+        for (const key of Object.keys(this.sessionMap)) {
+            delete this.sessionMap[key];
+        }
+    }
+
+    /**
+     * Marks a token as a false positive. The original plaintext value will be
+     * excluded from all future sanitize() calls on this engine instance.
+     * @param {string} token - The token to mark (e.g., '[NAME_1]').
+     * @returns {{ success: boolean, token?: string, original?: string, ignoreListSize?: number, reason?: string }}
+     */
+    markFalsePositive(token) {
+        const original = this.sessionMap[token];
+        if (!original) {
+            return { success: false, reason: `Token '${token}' not found in session map` };
+        }
+        this.ignoreList.add(original);
+        delete this.sessionMap[token];
+        return { success: true, token, original, ignoreListSize: this.ignoreList.size };
+    }
+
+    /**
+     * Clears the false positive ignore list.
+     */
+    clearIgnoreList() {
+        this.ignoreList.clear();
+    }
+
+    /**
+     * Creates a streaming token restorer bound to this engine's session map.
+     * @param {Record<string, string>} [tokenMap=null]
+     * @param {object} [options={}]
+     */
+    createStreamRestorer(tokenMap = null, options = {}) {
+        const activeMap = tokenMap || this.sessionMap;
+        return createStreamTokenRestorer(activeMap, options);
+    }
+
+    /**
+     * Wraps an async iterable LLM stream with real-time de-tokenization.
+     * @param {AsyncIterable<any>} stream
+     * @param {Record<string, string>} [tokenMap=null]
+     * @param {object} [options={}]
+     */
+    async* wrapStream(stream, tokenMap = null, options = {}) {
+        const activeMap = tokenMap || this.sessionMap;
+        yield* wrapAiStream(stream, activeMap, options);
+    }
+}
+
+/**
+ * Transparent Zero-Trust Wrapper for OpenAI Client.
+ * Automatically sanitizes outgoing messages before transmission to OpenAI,
+ * and restores completion tokens in the assistant response before returning!
+ * Seamlessly de-tokenizes streaming responses in real-time when stream: true.
+ * 
+ * @param {object} openaiClient - Instance of OpenAI SDK (e.g. new OpenAI()).
+ * @param {object} [options={}] - PrivacyScrubber configuration.
+ * @returns {object} Wrapped OpenAI client.
+ */
+function wrapOpenAI(openaiClient, options = {}) {
+    if (!openaiClient || !openaiClient.chat || !openaiClient.chat.completions) {
+        throw new Error('[PrivacyScrubber] Invalid OpenAI client instance passed to wrapOpenAI.');
+    }
+
+    const engine = new PrivacyScrubberEngine(options);
+    const originalCreate = openaiClient.chat.completions.create.bind(openaiClient.chat.completions);
+
+    openaiClient.chat.completions.create = async function(params, requestOptions) {
+        if (!params || !Array.isArray(params.messages)) {
+            return originalCreate(params, requestOptions);
+        }
+
+        const sessionTokenMap = {};
+        const sanitizedMessages = params.messages.map(msg => {
+            if (typeof msg.content === 'string') {
+                const res = engine.sanitize(msg.content, { existingSessionMap: sessionTokenMap });
+                Object.assign(sessionTokenMap, res.tokenMap);
+                return { ...msg, content: res.scrubbedText };
+            } else if (Array.isArray(msg.content)) {
+                const sanitizedChunks = msg.content.map(chunk => {
+                    if (chunk && chunk.type === 'text' && typeof chunk.text === 'string') {
+                        const res = engine.sanitize(chunk.text, { existingSessionMap: sessionTokenMap });
+                        Object.assign(sessionTokenMap, res.tokenMap);
+                        return { ...chunk, text: res.scrubbedText };
+                    }
+                    return chunk;
+                });
+                return { ...msg, content: sanitizedChunks };
+            }
+            return msg;
+        });
+
+        const modifiedParams = { ...params, messages: sanitizedMessages };
+        const response = await originalCreate(modifiedParams, requestOptions);
+
+        // Streaming support: transparently de-tokenize async iterable chunks
+        if (params.stream) {
+            const detok = new StreamingDetokenizer(sessionTokenMap);
+            return detok.wrapStream(response);
+        }
+
+        if (response && Array.isArray(response.choices)) {
+            response.choices.forEach(choice => {
+                if (choice.message) {
+                    if (typeof choice.message.content === 'string') {
+                        choice.message.content = engine.restore(choice.message.content, sessionTokenMap).restoredText;
+                    } else if (Array.isArray(choice.message.content)) {
+                        choice.message.content = choice.message.content.map(chunk => {
+                            if (chunk && chunk.type === 'text' && typeof chunk.text === 'string') {
+                                return { ...chunk, text: engine.restore(chunk.text, sessionTokenMap).restoredText };
+                            }
+                            return chunk;
+                        });
+                    }
+                }
+            });
+        }
+
+        return response;
+    };
+
+    return openaiClient;
+}
+
+/**
+ * Transparent Zero-Trust wrapper for Vercel AI SDK Language Models.
+ * Sanitizes input prompts in local RAM before model invocation and transparently
+ * de-tokenizes streaming text deltas and final text responses.
+ * 
+ * Compatible with Vercel AI SDK v3/v4: generateText, streamText, generateObject, streamObject.
+ * 
+ * @param {object} model - LanguageModel instance (e.g. openai('gpt-4o'), anthropic('claude-3-5-sonnet')).
+ * @param {object} [options={}] - PrivacyScrubber configuration options (profile, detectSecrets, licenseKey).
+ * @returns {object} Wrapped LanguageModel instance.
+ */
+function wrapAiModel(model, options = {}) {
+    if (!model || typeof model !== 'object') {
+        throw new Error('[PrivacyScrubber] Invalid model instance passed to wrapAiModel.');
+    }
+
+    const engine = new PrivacyScrubberEngine(options);
+    const wrapped = Object.create(model);
+
+    function sanitizePromptParts(prompt, sessionMap) {
+        if (!Array.isArray(prompt)) return prompt;
+        return prompt.map(msg => {
+            if (!msg) return msg;
+            if (typeof msg.content === 'string') {
+                const res = engine.sanitize(msg.content, { existingSessionMap: sessionMap });
+                Object.assign(sessionMap, res.tokenMap);
+                return { ...msg, content: res.scrubbedText };
+            }
+            if (Array.isArray(msg.content)) {
+                const newContent = msg.content.map(part => {
+                    if (part && part.type === 'text' && typeof part.text === 'string') {
+                        const res = engine.sanitize(part.text, { existingSessionMap: sessionMap });
+                        Object.assign(sessionMap, res.tokenMap);
+                        return { ...part, text: res.scrubbedText };
+                    }
+                    return part;
+                });
+                return { ...msg, content: newContent };
+            }
+            return msg;
+        });
+    }
+
+    if (typeof model.doGenerate === 'function') {
+        wrapped.doGenerate = async function(params) {
+            const sessionTokenMap = {};
+            const sanitizedParams = {
+                ...params,
+                prompt: sanitizePromptParts(params.prompt, sessionTokenMap)
+            };
+            const result = await model.doGenerate(sanitizedParams);
+            if (result && typeof result.text === 'string') {
+                result.text = engine.restore(result.text, sessionTokenMap).restoredText;
+            }
+            return result;
+        };
+    }
+
+    if (typeof model.doStream === 'function') {
+        wrapped.doStream = async function(params) {
+            const sessionTokenMap = {};
+            const sanitizedParams = {
+                ...params,
+                prompt: sanitizePromptParts(params.prompt, sessionTokenMap)
+            };
+            const result = await model.doStream(sanitizedParams);
+            if (result && result.stream) {
+                const detok = new StreamingDetokenizer(sessionTokenMap);
+                const originalStream = result.stream;
+
+                if (typeof originalStream.pipeThrough === 'function' && typeof TransformStream !== 'undefined') {
+                    result.stream = originalStream.pipeThrough(new TransformStream({
+                        transform(chunk, controller) {
+                            if (chunk && chunk.type === 'text-delta' && typeof chunk.textDelta === 'string') {
+                                const restored = detok.feed(chunk.textDelta);
+                                if (restored) controller.enqueue({ ...chunk, textDelta: restored });
+                            } else {
+                                controller.enqueue(chunk);
+                            }
+                        },
+                        flush(controller) {
+                            const rem = detok.flush();
+                            if (rem) controller.enqueue({ type: 'text-delta', textDelta: rem });
+                        }
+                    }));
+                } else if (typeof originalStream[Symbol.asyncIterator] === 'function') {
+                    async function* wrappedAsyncIterable() {
+                        for await (const chunk of originalStream) {
+                            if (chunk && chunk.type === 'text-delta' && typeof chunk.textDelta === 'string') {
+                                const restored = detok.feed(chunk.textDelta);
+                                if (restored) yield { ...chunk, textDelta: restored };
+                            } else {
+                                yield chunk;
+                            }
+                        }
+                        const rem = detok.flush();
+                        if (rem) yield { type: 'text-delta', textDelta: rem };
+                    }
+                    result.stream = wrappedAsyncIterable();
+                }
+            }
+            return result;
+        };
+    }
+
+    return wrapped;
+}
+
+const wrapAiSdk = wrapAiModel;
+
+/**
+ * Framework middleware helper for LangChain / LlamaIndex pipelines.
+ */
+function createLangChainTransform(options = {}) {
+    const engine = new PrivacyScrubberEngine(options);
+    return {
+        preprocess: (input) => engine.sanitize(input),
+        postprocess: (output, tokenMap) => engine.restore(output, tokenMap)
+    };
+}
+
+/**
+ * LangChain Document Transformer for RAG pre-ingestion pipelines.
+ * Compliant with LangChain BaseDocumentTransformer and Runnable interfaces.
+ *
+ * Intercepts LangChain Document objects ({ pageContent, metadata }) before
+ * embedding or vector storage, scrubbing PII in pageContent and optional sensitive metadata keys.
+ *
+ * @param {Object} [options={}]
+ * @param {string} [options.profile='General'] Detection profile ('General', 'Medical', 'Finance', 'Dev', etc.)
+ * @param {string[]} [options.sensitiveMetadataKeys=[]] Metadata keys to sanitize (e.g. ['author', 'user_id', 'contact'])
+ * @param {boolean} [options.attachTelemetry=true] Whether to attach _ztds_telemetry to document metadata
+ * @param {boolean} [options.attachTokenMap=false] Whether to attach _ztds_token_map to document metadata
+ * @returns {Object} Document transformer with transformDocuments and invoke methods
+ */
+function createDocumentTransformer(options = {}) {
+    const {
+        profile = 'General',
+        sensitiveMetadataKeys = [],
+        attachTelemetry = true,
+        attachTokenMap = false,
+        ...engineOptions
+    } = options;
+
+    const engine = new PrivacyScrubberEngine({ profile, ...engineOptions });
+
+    async function transformDocuments(documents) {
+        if (!Array.isArray(documents)) {
+            throw new TypeError("documents must be an array of LangChain Document objects");
+        }
+
+        const transformed = [];
+        for (const doc of documents) {
+            const pageContent = doc.pageContent || doc.text || "";
+            const metadata = { ...(doc.metadata || {}) };
+
+            // Sanitize page content
+            const scrubResult = engine.sanitize(pageContent, { profile });
+
+            // Sanitize designated sensitive metadata fields if present
+            if (Array.isArray(sensitiveMetadataKeys) && sensitiveMetadataKeys.length > 0) {
+                for (const key of sensitiveMetadataKeys) {
+                    if (metadata[key] && typeof metadata[key] === 'string') {
+                        const metaScrub = engine.sanitize(metadata[key], { profile });
+                        metadata[key] = metaScrub.scrubbedText;
+                    }
+                }
+            }
+
+            if (attachTelemetry) {
+                metadata._ztds_telemetry = {
+                    riskLevel: scrubResult.telemetry?.riskLevel || 'CLEAN (ZERO PII)',
+                    totalCount: scrubResult.count || 0,
+                    timestamp: new Date().toISOString()
+                };
+            }
+
+            if (attachTokenMap && scrubResult.tokenMap) {
+                metadata._ztds_token_map = { ...scrubResult.tokenMap };
+            }
+
+            transformed.push({
+                ...doc,
+                pageContent: scrubResult.scrubbedText,
+                metadata
+            });
+        }
+
+        return transformed;
+    }
+
+    return {
+        transformDocuments,
+        invoke: async (documents) => transformDocuments(documents),
+        sessionMap: engine.sessionMap,
+        restore: (output, tokenMap) => engine.restore(output, tokenMap || engine.sessionMap),
+        resetSession: () => engine.resetSession()
+    };
+}
+const createLangChainDocumentTransformer = createDocumentTransformer;
+
+/**
+ * LlamaIndex Node/Document Transform component for RAG ingestion.
+ *
+ * Compatible with LlamaIndex ingestion pipelines and custom transformations.
+ * Sanitizes node text while preserving node IDs, relationships, and metadata.
+ *
+ * @param {Object} [options={}]
+ * @returns {Object} LlamaIndex transform with transform method
+ */
+function createLlamaIndexTransform(options = {}) {
+    const { profile = 'General', ...engineOptions } = options;
+    const engine = new PrivacyScrubberEngine({ profile, ...engineOptions });
+
+    return {
+        transform: (nodes) => {
+            if (!nodes) return nodes;
+            const isArray = Array.isArray(nodes);
+            const list = isArray ? nodes : [nodes];
+
+            const transformed = list.map((node) => {
+                const text = typeof node.getContent === 'function' 
+                    ? node.getContent() 
+                    : (node.text || node.pageContent || '');
+                const result = engine.sanitize(text, { profile });
+                
+                if (typeof node.setContent === 'function') {
+                    node.setContent(result.scrubbedText);
+                } else {
+                    node.text = result.scrubbedText;
+                }
+
+                if (node.metadata) {
+                    node.metadata._ztds_sanitized = true;
+                    node.metadata._ztds_pii_count = result.count;
+                }
+                return node;
+            });
+
+            return isArray ? transformed : transformed[0];
+        },
+        sessionMap: engine.sessionMap,
+        restore: (text, map) => engine.restore(text, map || engine.sessionMap),
+        resetSession: () => engine.resetSession()
+    };
+}
+
+/**
+ * Universal Vector Database Ingestion Guard (Chroma, Pinecone, Qdrant, Weaviate, pgvector, Milvus).
+ *
+ * Guarantees zero-PII vector embedding and storage in local/cloud vector databases.
+ * Provides pre-ingestion record sanitization, query alignment, search result re-hydration,
+ * and transparent proxy wrapping of vector store clients.
+ *
+ * @param {Object} [options={}]
+ * @param {string} [options.profile='General']
+ * @param {string[]} [options.sensitiveMetadataKeys=[]]
+ * @param {boolean} [options.autoRestoreResults=true]
+ * @returns {Object} Vector ingestion guard utilities
+ */
+function createVectorIngestionGuard(options = {}) {
+    const {
+        profile = 'General',
+        sensitiveMetadataKeys = [],
+        autoRestoreResults = true,
+        ...engineOptions
+    } = options;
+
+    const engine = new PrivacyScrubberEngine({ profile, ...engineOptions });
+
+    /**
+     * Sanitizes raw database records prior to vector store upsert / add.
+     * Supports standard formats:
+     * - Chroma: { ids: [], documents: [], metadatas: [] }
+     * - Pinecone: [{ id, values, metadata }]
+     * - Qdrant: [{ id, vector, payload: { text, ... } }]
+     * - Universal: [{ id, text, metadata }]
+     */
+    function sanitizeRecords(records) {
+        if (!records) return records;
+
+        // Chroma-style columnar batch: { ids, documents, metadatas }
+        if (records.documents && Array.isArray(records.documents)) {
+            const sanitizedDocs = [];
+            const sanitizedMetas = records.metadatas ? [...records.metadatas] : [];
+            let totalTokens = 0;
+
+            records.documents.forEach((doc, idx) => {
+                const res = engine.sanitize(doc || '', { profile });
+                sanitizedDocs.push(res.scrubbedText);
+                totalTokens += res.count;
+
+                if (sanitizedMetas[idx]) {
+                    const meta = { ...sanitizedMetas[idx] };
+                    if (sensitiveMetadataKeys.length > 0) {
+                        for (const k of sensitiveMetadataKeys) {
+                            if (typeof meta[k] === 'string') {
+                                meta[k] = engine.sanitize(meta[k], { profile }).scrubbedText;
+                            }
+                        }
+                    }
+                    meta._ztds_sanitized = true;
+                    sanitizedMetas[idx] = meta;
+                }
+            });
+
+            return {
+                ...records,
+                documents: sanitizedDocs,
+                metadatas: sanitizedMetas,
+                _ztds_total_tokens: totalTokens
+            };
+        }
+
+        // Array of record objects (Pinecone, Qdrant, Weaviate, LangChain vectorstores)
+        if (Array.isArray(records)) {
+            let totalTokens = 0;
+            const sanitized = records.map((record) => {
+                const copy = { ...record };
+                // Handle text / document / pageContent / payload.text
+                const textField = copy.text !== undefined ? 'text' 
+                    : copy.document !== undefined ? 'document'
+                    : copy.pageContent !== undefined ? 'pageContent'
+                    : null;
+
+                if (textField && typeof copy[textField] === 'string') {
+                    const res = engine.sanitize(copy[textField], { profile });
+                    copy[textField] = res.scrubbedText;
+                    totalTokens += res.count;
+                }
+
+                // Handle Qdrant payload
+                if (copy.payload && typeof copy.payload === 'object') {
+                    copy.payload = { ...copy.payload };
+                    if (typeof copy.payload.text === 'string') {
+                        const res = engine.sanitize(copy.payload.text, { profile });
+                        copy.payload.text = res.scrubbedText;
+                        totalTokens += res.count;
+                    }
+                }
+
+                // Handle metadata
+                if (copy.metadata && typeof copy.metadata === 'object') {
+                    copy.metadata = { ...copy.metadata };
+                    for (const k of sensitiveMetadataKeys) {
+                        if (typeof copy.metadata[k] === 'string') {
+                            copy.metadata[k] = engine.sanitize(copy.metadata[k], { profile }).scrubbedText;
+                        }
+                    }
+                    copy.metadata._ztds_sanitized = true;
+                }
+
+                return copy;
+            });
+
+            return sanitized;
+        }
+
+        return records;
+    }
+
+    /**
+     * Sanitizes user queries before generating search embeddings.
+     * Ensures search vectors align with sanitized tokenized corpus representations.
+     */
+    function sanitizeQuery(query) {
+        if (typeof query !== 'string') return query;
+        const res = engine.sanitize(query, { profile });
+        const matches = res.scrubbedText.match(/\[[A-Z_]+_\d+\]/g);
+        const tokensDetected = matches ? matches.length : (res.count || 0);
+        return {
+            query: res.scrubbedText,
+            rawQuery: query,
+            tokensDetected,
+            tokenMap: res.tokenMap
+        };
+    }
+
+    /**
+     * Restores search results retrieved from vector DB using the volatile session map.
+     */
+    function restoreSearchResults(results, customTokenMap = null) {
+        const map = customTokenMap || engine.sessionMap;
+        if (!results || Object.keys(map).length === 0) return results;
+
+        function restoreText(t) {
+            if (typeof t !== 'string') return t;
+            return engine.restore(t, map).restoredText;
+        }
+
+        if (Array.isArray(results)) {
+            return results.map(item => {
+                const copy = { ...item };
+                if (typeof copy.pageContent === 'string') copy.pageContent = restoreText(copy.pageContent);
+                if (typeof copy.text === 'string') copy.text = restoreText(copy.text);
+                if (typeof copy.document === 'string') copy.document = restoreText(copy.document);
+                if (copy.payload && typeof copy.payload === 'object') {
+                    copy.payload = { ...copy.payload };
+                    if (typeof copy.payload.text === 'string') {
+                        copy.payload.text = restoreText(copy.payload.text);
+                    }
+                }
+                return copy;
+            });
+        }
+
+        return results;
+    }
+
+    /**
+     * Wraps an existing vector store client instance with zero-trust hooks.
+     */
+    function wrapVectorStore(vectorStore) {
+        const proxy = new Proxy(vectorStore, {
+            get(target, prop, receiver) {
+                const orig = Reflect.get(target, prop, receiver);
+                if (typeof orig !== 'function') return orig;
+
+                // Intercept ingestion methods: addDocuments, upsert, add, insert
+                if (prop === 'addDocuments') {
+                    return async function(docs, ...rest) {
+                        if (!Array.isArray(docs)) return orig.apply(target, [docs, ...rest]);
+                        const safeDocs = docs.map(doc => {
+                            const pageContent = doc.pageContent || doc.text || "";
+                            const metadata = { ...(doc.metadata || {}) };
+                            const scrubResult = engine.sanitize(pageContent, { profile });
+                            for (const key of sensitiveMetadataKeys) {
+                                if (metadata[key] && typeof metadata[key] === 'string') {
+                                    metadata[key] = engine.sanitize(metadata[key], { profile }).scrubbedText;
+                                }
+                            }
+                            metadata._ztds_telemetry = {
+                                riskLevel: scrubResult.telemetry?.riskLevel || 'CLEAN (ZERO PII)',
+                                totalCount: scrubResult.count || 0,
+                                timestamp: new Date().toISOString()
+                            };
+                            return { ...doc, pageContent: scrubResult.scrubbedText, metadata };
+                        });
+                        return orig.apply(target, [safeDocs, ...rest]);
+                    };
+                }
+
+                if (prop === 'upsert' || prop === 'add' || prop === 'insert') {
+                    return async function(records, ...rest) {
+                        const safeRecords = sanitizeRecords(records);
+                        return orig.apply(target, [safeRecords, ...rest]);
+                    };
+                }
+
+                // Intercept query methods: similaritySearch, query, search
+                if (prop === 'similaritySearch' || prop === 'query' || prop === 'search') {
+                    return async function(queryArg, ...rest) {
+                        const safeQ = typeof queryArg === 'string' ? sanitizeQuery(queryArg).query : queryArg;
+                        const rawResults = await orig.apply(target, [safeQ, ...rest]);
+                        if (autoRestoreResults) {
+                            return restoreSearchResults(rawResults);
+                        }
+                        return rawResults;
+                    };
+                }
+
+                return orig.bind(target);
+            }
+        });
+
+        return proxy;
+    }
+
+    return {
+        sanitizeRecords,
+        sanitizeQuery,
+        restoreSearchResults,
+        wrapVectorStore,
+        sessionMap: engine.sessionMap,
+        restore: (text, map) => engine.restore(text, map || engine.sessionMap),
+        resetSession: () => engine.resetSession()
+    };
+}
+
+/**
+ * Helper to escape special regex characters.
+ */
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Builds an ultra-fast streaming token replacement function.
+ * Preserves all whitespace, indentation, newlines, and code blocks (does NOT trim).
+ * Handles descending key ordering (e.g. [NAME_10] before [NAME_1]), case insensitivity,
+ * alternative delimiters (<...>, {{...}}, __...__), and possessive suffixes.
+ *
+ * @param {Record<string, string>} tokenMap
+ * @returns {(text: string) => string}
+ */
+function buildStreamReplacer(tokenMap = {}, options = {}) {
+    if (!tokenMap || typeof tokenMap !== 'object' || Object.keys(tokenMap).length === 0) {
+        return (text) => text || '';
+    }
+
+    const onTokenRestored = typeof options?.onTokenRestored === 'function' ? options.onTokenRestored : null;
+    const lookup = new Map();
+    const patterns = [];
+    const sortedKeys = Object.keys(tokenMap).sort((a, b) => b.length - a.length);
+
+    for (const k of sortedKeys) {
+        const val = tokenMap[k];
+        const inner = k.replace(/^\[|<|\{\{|__|\]|>|\}\}|__/g, '');
+        const match = inner.match(/^([A-Za-z_0-9]+?)[-_ ]?(\d+)$/);
+
+        if (match) {
+            const label = escapeRegex(match[1]);
+            const idx = match[2];
+            const patternStr = '(?:\\[\\s*' + label + '[-_\\s]*0*' + idx + '\\s*\\]|<\\s*' + label + '[-_\\s]*0*' + idx + '\\s*>|\\{\\{\\s*' + label + '[-_\\s]*0*' + idx + '\\s*\\}\\}|__\\s*' + label + '[-_\\s]*0*' + idx + '\\s*__|\\b' + label + '[-_\\s]+0*' + idx + '\\b)';
+            patterns.push(patternStr);
+            const normKey = (match[1] + '_' + parseInt(idx, 10)).toUpperCase();
+            lookup.set(normKey, val);
+            lookup.set(k, val);
+            lookup.set(k.toUpperCase(), val);
+        } else {
+            const safe = escapeRegex(k);
+            patterns.push(safe);
+            lookup.set(k, val);
+            lookup.set(k.toUpperCase(), val);
+        }
+    }
+
+    const unifiedRegex = new RegExp('(?:' + patterns.join('|') + ')(\'s|’s|s)?', 'gi');
+
+    return function replaceTokens(text) {
+        if (!text) return '';
+        unifiedRegex.lastIndex = 0;
+        return text.replace(unifiedRegex, (match, suffix) => {
+            const isPossessive = suffix && /('s|’s)$/i.test(suffix);
+            const coreMatch = suffix ? match.slice(0, match.length - suffix.length) : match;
+            let restored = null;
+
+            if (lookup.has(coreMatch)) {
+                restored = lookup.get(coreMatch);
+            } else if (lookup.has(coreMatch.toUpperCase())) {
+                restored = lookup.get(coreMatch.toUpperCase());
+            } else {
+                const inner = coreMatch.replace(/^\[|<|\{\{|__|\]|>|\}\}|__/g, '').trim();
+                const m = inner.match(/^([A-Za-z_0-9]+?)[-_ ]?(\d+)$/);
+                if (m) {
+                    const normKey = (m[1] + '_' + parseInt(m[2], 10)).toUpperCase();
+                    if (lookup.has(normKey)) {
+                        restored = lookup.get(normKey);
+                    }
+                }
+            }
+
+            if (restored !== null) {
+                if (onTokenRestored) {
+                    try { onTokenRestored({ token: match, originalValue: restored }); } catch (_) {}
+                }
+                return restored + (isPossessive ? "'s" : '');
+            }
+
+            if (lookup.has(match)) {
+                restored = lookup.get(match);
+                if (onTokenRestored) {
+                    try { onTokenRestored({ token: match, originalValue: restored }); } catch (_) {}
+                }
+                return restored;
+            }
+
+            return match;
+        });
+    };
+}
+
+/**
+ * Streaming Token Detokenizer with sliding window buffer for LLM chunk boundary splits.
+ * Seamlessly restores split tokens (e.g. [EM + AIL_1]), preserves multi-byte UTF-8,
+ * and maintains zero-latency streaming throughput.
+ */
+class StreamingDetokenizer {
+    constructor(tokenMap = {}, options = {}) {
+        this.tokenMap = tokenMap && typeof tokenMap === 'object' ? tokenMap : {};
+        this.options = options || {};
+        this.replacer = buildStreamReplacer(this.tokenMap, this.options);
+        this.pendingBuffer = '';
+        this.hasTokens = Object.keys(this.tokenMap).length > 0;
+        this._lastTokenCount = Object.keys(this.tokenMap).length;
+        this.decoder = new TextDecoder('utf-8', { fatal: false });
+    }
+
+    /**
+     * Backward-compatible buffer property getter/setter.
+     */
+    get buffer() {
+        return this.pendingBuffer;
+    }
+
+    set buffer(val) {
+        this.pendingBuffer = typeof val === 'string' ? val : '';
+    }
+
+    /**
+     * Dynamically updates the active token map for this streaming session.
+     * @param {Record<string, string>} newMap
+     */
+    updateTokenMap(newMap) {
+        if (newMap && typeof newMap === 'object') {
+            this.tokenMap = newMap;
+            this.replacer = buildStreamReplacer(this.tokenMap, this.options);
+            this.hasTokens = Object.keys(this.tokenMap).length > 0;
+            this._lastTokenCount = Object.keys(this.tokenMap).length;
+        }
+    }
+
+    /**
+     * Resets the internal sliding window buffer.
+     */
+    reset() {
+        this.pendingBuffer = '';
+    }
+
+    /**
+     * Feeds an incoming chunk (string, Uint8Array, or Buffer) and returns de-tokenized text.
+     * Buffers any unclosed token candidates at chunk boundaries until closed or flushed.
+     * @param {string | Uint8Array | Buffer} chunk
+     * @returns {string}
+     */
+    feed(chunk) {
+        if (chunk === undefined || chunk === null) return '';
+        let text = '';
+        if (typeof chunk === 'string') {
+            text = chunk;
+        } else if (chunk instanceof Uint8Array || (typeof Buffer !== 'undefined' && Buffer.isBuffer(chunk))) {
+            text = this.decoder.decode(chunk, { stream: true });
+        } else {
+            text = String(chunk);
+        }
+
+        if (!text) return '';
+
+        // Dynamically recompile if tokens were added to the referenced map
+        const currentTokenCount = Object.keys(this.tokenMap).length;
+        if (currentTokenCount !== this._lastTokenCount) {
+            this.replacer = buildStreamReplacer(this.tokenMap, this.options);
+            this.hasTokens = currentTokenCount > 0;
+            this._lastTokenCount = currentTokenCount;
+        }
+
+        if (!this.hasTokens) return text;
+
+        this.pendingBuffer += text;
+
+        // Candidate unclosed token at tail of buffer (inspect tail window up to 160 chars)
+        // Matches incomplete tokens starting with [, <, {{, or __, plus single delimiter prefixes { and _
+        const tailLen = 160;
+        const tail = this.pendingBuffer.length > tailLen ? this.pendingBuffer.slice(-tailLen) : this.pendingBuffer;
+        const offset = this.pendingBuffer.length > tailLen ? this.pendingBuffer.length - tailLen : 0;
+        const m = tail.match(/(?:\[|<|\{\{?|__?)[A-Za-z0-9_\-А-Яа-яЁё ]{0,128}$/);
+
+        if (m) {
+            const candidate = m[0];
+            // Only closed double-underscore tokens (e.g. __NAME_1__) could match m since '_' is in character class.
+            // Bracketed tokens ([, <, {{) cannot end with their closing delimiter here and must be buffered.
+            const isClosedUnderscoreToken = candidate.length >= 4 && candidate.startsWith('__') && candidate.endsWith('__');
+            if (isClosedUnderscoreToken && this.replacer(candidate) !== candidate) {
+                const toEmit = this.pendingBuffer;
+                this.pendingBuffer = '';
+                return this.replacer(toEmit);
+            }
+            const splitIdx = offset + m.index;
+            const safeToEmit = this.pendingBuffer.slice(0, splitIdx);
+            this.pendingBuffer = this.pendingBuffer.slice(splitIdx);
+            return safeToEmit ? this.replacer(safeToEmit) : '';
+        }
+
+        const toEmit = this.pendingBuffer;
+        this.pendingBuffer = '';
+        return this.replacer(toEmit);
+    }
+
+    /**
+     * Alias for feed() to maintain backwards compatibility with process() callers.
+     */
+    process(chunk) {
+        return this.feed(chunk);
+    }
+
+    /**
+     * Flushes remaining buffered tokens and finalizes UTF-8 stream decoder.
+     * @returns {string}
+     */
+    flush() {
+        let text = '';
+        try {
+            text = this.decoder.decode(new Uint8Array(), { stream: false });
+        } catch (_) {}
+
+        if (text) {
+            this.pendingBuffer += text;
+        }
+
+        if (!this.pendingBuffer) return '';
+        const remaining = this.pendingBuffer;
+        this.pendingBuffer = '';
+        return this.replacer(remaining);
+    }
+
+    /**
+     * Returns a native Node.js Transform stream instance for .pipe() / pipeline().
+     * @returns {Transform}
+     */
+    toNodeTransform() {
+        const self = this;
+        const transformStream = new Transform({
+            transform(chunk, encoding, callback) {
+                try {
+                    const out = self.feed(chunk);
+                    if (out) this.push(out);
+                    callback();
+                } catch (err) {
+                    callback(err);
+                }
+            },
+            flush(callback) {
+                try {
+                    const out = self.flush();
+                    if (out) this.push(out);
+                    callback();
+                } catch (err) {
+                    callback(err);
+                }
+            },
+            destroy(err, callback) {
+                self.reset();
+                callback(err);
+            }
+        });
+        transformStream.detokenizer = self;
+        return transformStream;
+    }
+
+    /**
+     * Wraps an async iterable (e.g. LLM streaming response) yielding restored chunks.
+     * @param {AsyncIterable<any>} asyncIterable
+     * @returns {AsyncGenerator<any>}
+     */
+    async* wrapStream(asyncIterable) {
+        for await (const chunk of asyncIterable) {
+            if (chunk === null || chunk === undefined) continue;
+            // Handle OpenAI chunk object
+            if (chunk.choices && Array.isArray(chunk.choices) && chunk.choices[0]?.delta?.content !== undefined) {
+                const delta = chunk.choices[0].delta.content;
+                if (typeof delta === 'string') {
+                    const restored = this.feed(delta);
+                    if (restored) {
+                        chunk.choices[0].delta.content = restored;
+                        yield chunk;
+                    }
+                } else {
+                    yield chunk;
+                }
+                continue;
+            }
+
+            let text = '';
+            if (typeof chunk === 'string') {
+                text = chunk;
+            } else if (typeof chunk?.text === 'string') {
+                text = chunk.text;
+            } else if (typeof chunk?.content === 'string') {
+                text = chunk.content;
+            } else if (chunk instanceof Uint8Array || (typeof Buffer !== 'undefined' && Buffer.isBuffer(chunk))) {
+                text = chunk;
+            } else {
+                text = String(chunk);
+            }
+
+            const emitted = this.feed(text);
+            if (emitted) yield emitted;
+        }
+
+        const finalChunk = this.flush();
+        if (finalChunk) yield finalChunk;
+    }
+}
+
+/**
+ * Creates a zero-latency streaming token restorer for LLM Server-Sent Events (SSE) and Web Streams.
+ * Solves the broken chunk boundary problem where tokens like [EMAIL_1] are split across multiple chunks.
+ * 
+ * Works with:
+ * - Vercel AI SDK (streamText / createDataStreamResponse)
+ * - OpenAI streaming (chat.completions.create({ stream: true }))
+ * - LangChain streaming
+ * - Native Web Streams (ReadableStream.pipeThrough)
+ * - Async generators (for await ... of)
+ * 
+ * @param {Record<string, string>} tokenMap - Volatile token mapping object.
+ * @param {object} [options] - Configuration options.
+ * @returns {TransformStream & { process: (chunk: string) => string, feed: (chunk: string) => string, flush: () => string, wrapStream: (asyncIterable: AsyncIterable<any>) => AsyncGenerator<any>, toNodeTransform: () => Transform, detokenizer: StreamingDetokenizer }}
+ */
+function createStreamTokenRestorer(tokenMap = {}, options = {}) {
+    const detok = new StreamingDetokenizer(tokenMap, options);
+
+    let stream;
+    if (typeof TransformStream !== 'undefined') {
+        stream = new TransformStream({
+            transform(chunk, controller) {
+                const out = detok.feed(chunk);
+                if (out) controller.enqueue(out);
+            },
+            flush(controller) {
+                const out = detok.flush();
+                if (out) controller.enqueue(out);
+            }
+        });
+    } else {
+        stream = {};
+    }
+
+    stream.process = (chunk) => detok.feed(chunk);
+    stream.feed = (chunk) => detok.feed(chunk);
+    stream.flush = () => detok.flush();
+    stream.wrapStream = (asyncIterable) => detok.wrapStream(asyncIterable);
+    stream.toNodeTransform = () => detok.toNodeTransform();
+    stream.detokenizer = detok;
+
+    return stream;
+}
+
+/**
+ * Creates a Node.js native Transform stream for backend streaming pipelines (stream.pipeline / .pipe()).
+ * @param {Record<string, string>} tokenMap - Volatile token mapping object.
+ * @param {object} [options] - Configuration options.
+ * @returns {Transform}
+ */
+function createNodeStreamTokenRestorer(tokenMap = {}, options = {}) {
+    const detok = new StreamingDetokenizer(tokenMap, options);
+    return detok.toNodeTransform();
+}
+
+/**
+ * Wraps an async iterable LLM stream (e.g. from Vercel AI SDK textStream or OpenAI stream)
+ * and yields de-tokenized text chunks in real-time, seamlessly stitching split tokens across chunks.
+ * 
+ * @param {AsyncIterable<string|object>} stream - The incoming LLM stream.
+ * @param {Record<string, string>} tokenMap - Volatile token map.
+ * @returns {AsyncGenerator<any>}
+ */
+async function* wrapAiStream(stream, tokenMap = {}) {
+    const detok = new StreamingDetokenizer(tokenMap);
+    yield* detok.wrapStream(stream);
+}
+
+/**
+ * Middleware wrapper for Next.js App Router Route Handlers (POST/PUT).
+ * Automatically sanitizes incoming prompt payloads in RAM (<1ms) before the handler runs,
+ * and attaches sanitized text, tokenMap, and helper restoration functions.
+ * 
+ * @param {Function} handler - The async Next.js route handler (req, context) => Response
+ * @param {object} [options] - Sanitization options (profile, detectSecrets, etc.)
+ * @returns {Function} Wrapped Next.js route handler
+ */
+function withPrivacyScrubber(handler, options = {}) {
+    return async function privacyScrubberHandler(req, context = {}) {
+        if (!req || typeof req.json !== 'function') {
+            return handler(req, context);
+        }
+
+        let rawBody;
+        try {
+            rawBody = await req.json();
+        } catch (_) {
+            return handler(req, context);
+        }
+
+        let scrubbedBody = rawBody;
+        let tokenMap = {};
+        let telemetry = null;
+
+        if (typeof rawBody === 'string') {
+            const res = sanitize(rawBody, options);
+            scrubbedBody = res.scrubbedText;
+            tokenMap = res.tokenMap;
+            telemetry = res.telemetry;
+        } else if (rawBody && typeof rawBody === 'object') {
+            const serialized = JSON.stringify(rawBody);
+            const res = sanitize(serialized, options);
+            try {
+                scrubbedBody = JSON.parse(res.scrubbedText);
+            } catch (_) {
+                scrubbedBody = rawBody;
+            }
+            tokenMap = res.tokenMap;
+            telemetry = res.telemetry;
+        }
+
+        const psContext = {
+            ...context,
+            rawBody,
+            scrubbedBody,
+            tokenMap,
+            telemetry,
+            restore: (text) => restore(text, tokenMap),
+            createStreamRestorer: () => createStreamTokenRestorer(tokenMap)
+        };
+
+        return handler(req, psContext);
+    };
+}
+
+/**
+ * Express.js / Connect middleware for automatic zero-trust PII sanitization.
+ * Sanitizes req.body in local RAM and attaches req.psTokenMap and req.restore(aiResponse).
+ * 
+ * @param {object} [options] - Sanitization options.
+ * @returns {Function} Express middleware (req, res, next)
+ */
+function createExpressMiddleware(options = {}) {
+    return function privacyScrubberExpress(req, res, next) {
+        if (req && req.body && typeof req.body === 'object') {
+            const serialized = JSON.stringify(req.body);
+            const { scrubbedText, tokenMap, telemetry } = sanitize(serialized, options);
+            req.rawBody = req.body;
+            try {
+                req.body = JSON.parse(scrubbedText);
+            } catch (_) {}
+            req.psTokenMap = tokenMap;
+            req.psTelemetry = telemetry;
+            req.restore = (aiResponse) => restore(aiResponse, tokenMap);
+            req.createStreamRestorer = () => createStreamTokenRestorer(tokenMap);
+        }
+        if (typeof next === 'function') next();
+    };
+}
+
+/**
+ * Generates an official Zero-Trust Compliance Audit Report.
+ * @param {Record<string, string>} sessionMap - Map of token bindings.
+ * @param {object} [options] - Options: companyName, department, format ('markdown'|'json'|'summary').
+ * @returns {object|string}
+ */
+function formatCefEvent(eventData = {}) {
+    const {
+        vendor = 'PrivacyScrubber',
+        product = 'ZTDS',
+        version = '2.2.5',
+        eventClassId = 'PII_REDACTION',
+        eventName = 'Zero-Trust PII Sanitization Executed',
+        riskLevel = 'LOW EXPOSURE',
+        tokensMasked = 0,
+        entities = {},
+        frameworks = ['ZTDS Standard'],
+        sessionHash = '',
+        source = 'local_ram',
+        action = 'redact_and_mask',
+        organization = '',
+        department = ''
+    } = eventData;
+
+    let severity = 1;
+    if (riskLevel.includes('CRITICAL')) severity = 9;
+    else if (riskLevel.includes('MODERATE')) severity = 6;
+    else if (riskLevel.includes('LOW')) severity = 3;
+    else severity = 0;
+
+    const entitiesStr = Object.entries(entities).map(([k, v]) => `${k}:${v}`).join(',') || 'none';
+    const frameworksStr = Array.isArray(frameworks) ? frameworks.join(',') : String(frameworks);
+    const safeMsg = `Sanitized ${tokensMasked} entity tokens in volatile RAM. 0 bytes network egress.`;
+
+    const extension = [
+        `src=${source}`,
+        `act=${action}`,
+        `cs1Label=RiskLevel cs1=${riskLevel.replace(/\s+/g, '_')}`,
+        `cn1Label=TokensMasked cn1=${tokensMasked}`,
+        `cs2Label=Frameworks cs2=${frameworksStr.replace(/\s+/g, '_')}`,
+        `cs3Label=Entities cs3=${entitiesStr}`,
+        sessionHash ? `cs4Label=SessionHash cs4=${sessionHash.substring(0, 16)}` : '',
+        organization ? `suser=${organization.replace(/\s+/g, '_')}` : '',
+        department ? `cs5Label=Department cs5=${department.replace(/\s+/g, '_')}` : '',
+        `msg=${safeMsg}`
+    ].filter(Boolean).join(' ');
+
+    return `CEF:0|${vendor}|${product}|${version}|${eventClassId}|${eventName}|${severity}|${extension}`;
+}
+
+function formatSyslogEvent(eventData = {}) {
+    const {
+        timestamp = new Date().toISOString(),
+        hostname = (typeof os !== 'undefined' && typeof os.hostname === 'function' ? os.hostname() : 'localhost'),
+        pid = (typeof process !== 'undefined' && process.pid ? process.pid : 1),
+        riskLevel = 'LOW EXPOSURE',
+        tokensMasked = 0,
+        frameworks = ['ZTDS Standard'],
+        sessionHash = '',
+        organization = ''
+    } = eventData;
+
+    let pri = 134; // local0.info
+    if (riskLevel.includes('CRITICAL')) pri = 132; // local0.warning
+    else if (riskLevel.includes('MODERATE')) pri = 133; // local0.notice
+
+    const frameworksStr = Array.isArray(frameworks) ? frameworks.join(';') : String(frameworks);
+    const hashPrefix = sessionHash.substring(0, 16) || 'none';
+    const orgStr = organization ? ` org="${organization.replace(/"/g, '')}"` : '';
+
+    const sd = `[ztds@49152 risk="${riskLevel}" tokens="${tokensMasked}" frameworks="${frameworksStr}" session="${hashPrefix}"${orgStr}]`;
+    const msg = `Zero-Trust Data Sanitization executed in RAM. ${tokensMasked} token(s) masked. 0 bytes network egress.`;
+
+    return `<${pri}>1 ${timestamp} ${hostname} privacyscrubber ${pid} ZTDS - ${sd} ${msg}`;
+}
+
+function formatJsonlEvent(eventData = {}) {
+    const {
+        timestamp = new Date().toISOString(),
+        version = '2.2.5',
+        protocol = 'ZTDS',
+        event = 'sanitization',
+        riskLevel = 'LOW EXPOSURE',
+        tokensMasked = 0,
+        entities = {},
+        frameworks = ['ZTDS Standard'],
+        sessionHash = '',
+        organization = '',
+        department = '',
+        executionMs = 0,
+        metadata = {}
+    } = eventData;
+
+    const record = {
+        timestamp,
+        version,
+        protocol,
+        event,
+        risk_level: riskLevel,
+        tokens_masked: tokensMasked,
+        entities,
+        frameworks,
+        session_hash: sessionHash,
+        zero_egress: true,
+        verification_mode: "100% Offline (In-Memory RAM)",
+        ...(organization && { organization }),
+        ...(department && { department }),
+        ...(executionMs && { execution_ms: executionMs }),
+        ...(Object.keys(metadata).length > 0 && { metadata })
+    };
+
+    return JSON.stringify(record);
+}
+
+function createAuditLogger(options = {}) {
+    const {
+        format = 'jsonl',
+        destination = null,
+        organization = 'PrivacyScrubber Enterprise Client',
+        department = 'SecOps'
+    } = options;
+
+    let fileHandle = null;
+    let streamHandle = null;
+    const buffer = [];
+
+    if (typeof destination === 'string' && destination.trim()) {
+        try {
+            const dir = path.dirname(destination);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fileHandle = destination;
+        } catch {}
+    } else if (destination && typeof destination.write === 'function') {
+        streamHandle = destination;
+    }
+
+    function formatEvent(eventData) {
+        const enriched = {
+            organization,
+            department,
+            timestamp: new Date().toISOString(),
+            ...eventData
+        };
+
+        if (format === 'cef') {
+            return formatCefEvent(enriched);
+        }
+        if (format === 'syslog') {
+            return formatSyslogEvent(enriched);
+        }
+        if (format === 'json') {
+            return JSON.stringify(enriched, null, 2);
+        }
+        return formatJsonlEvent(enriched);
+    }
+
+    function writeEntry(line) {
+        buffer.push(line);
+        if (fileHandle) {
+            try {
+                fs.appendFileSync(fileHandle, line + '\n', 'utf8');
+            } catch (e) {
+                console.error('[PrivacyScrubber AuditLogger] File write error:', e);
+            }
+        } else if (streamHandle) {
+            try {
+                streamHandle.write(line + '\n');
+            } catch (e) {
+                console.error('[PrivacyScrubber AuditLogger] Stream write error:', e);
+            }
+        }
+    }
+
+    function logSanitization(result, context = {}) {
+        if (!result) return '';
+        let tokenMap = {};
+        let telemetry = null;
+        let count = 0;
+        let execMs = 0;
+
+        if (result.tokenMap && typeof result.tokenMap === 'object') {
+            tokenMap = result.tokenMap;
+            telemetry = result.telemetry;
+            count = result.count !== undefined ? result.count : Object.keys(tokenMap).length;
+            execMs = result.executionMs || 0;
+        } else if (typeof result === 'object') {
+            tokenMap = result;
+            count = result.count !== undefined ? result.count : (result.tokensMasked !== undefined ? result.tokensMasked : Object.keys(tokenMap).length);
+        }
+
+        if (!telemetry) {
+            telemetry = buildAuditTelemetry(tokenMap);
+        }
+
+        let sessionHash = '';
+        try {
+            const cryptoMod = require('crypto');
+            sessionHash = cryptoMod.createHash('sha256').update(JSON.stringify(tokenMap) + Date.now()).digest('hex');
+        } catch {
+            sessionHash = 'ztds_' + Math.random().toString(16).substring(2, 10);
+        }
+
+        const eventData = {
+            event: 'pii_sanitization',
+            riskLevel: telemetry.riskLevel || 'CLEAN (ZERO PII)',
+            tokensMasked: count,
+            entities: telemetry.entities || {},
+            frameworks: telemetry.frameworksList || ['ZTDS Standard'],
+            sessionHash,
+            executionMs: execMs,
+            metadata: context.metadata || {}
+        };
+
+        const formatted = formatEvent(eventData);
+        writeEntry(formatted);
+        return formatted;
+    }
+
+    function logEvent(eventData) {
+        const formatted = formatEvent(eventData);
+        writeEntry(formatted);
+        return formatted;
+    }
+
+    function getEntries() {
+        return [...buffer];
+    }
+
+    function clear() {
+        buffer.length = 0;
+    }
+
+    return {
+        formatEvent,
+        logSanitization,
+        logEvent,
+        log: logEvent,
+        getEntries,
+        getBuffer: getEntries,
+        clear,
+        clearBuffer: clear,
+        format,
+        destination
+    };
+}
+
+function generateAuditReport(sessionMap = {}, options = {}) {
+    const { companyName = 'PrivacyScrubber Client', department = 'SecOps / Compliance', format = 'markdown' } = options;
+    const telemetry = buildAuditTelemetry(sessionMap);
+    
+    let sessionHash = '';
+    try {
+        const cryptoMod = require('crypto');
+        sessionHash = cryptoMod.createHash('sha256').update(JSON.stringify(sessionMap) + Date.now().toString()).digest('hex');
+    } catch {
+        sessionHash = Array.from(crypto.getRandomValues(new Uint8Array(16))).map(b => b.toString(16).padStart(2, '0')).join('');
+    }
+
+    const timestamp = new Date().toISOString();
+    const entitySummary = Object.entries(telemetry.entities).map(([t, count]) => `[${t}]: ${count}`).join(', ') || 'None (Clean)';
+
+    if (format === 'cef') {
+        return formatCefEvent({
+            organization: companyName,
+            department: department,
+            timestamp,
+            sessionHash,
+            riskLevel: telemetry.riskLevel,
+            tokensMasked: telemetry.totalCount,
+            entities: telemetry.entities,
+            frameworks: telemetry.frameworksList
+        });
+    }
+
+    if (format === 'syslog') {
+        return formatSyslogEvent({
+            organization: companyName,
+            department: department,
+            timestamp,
+            sessionHash,
+            riskLevel: telemetry.riskLevel,
+            tokensMasked: telemetry.totalCount,
+            entities: telemetry.entities,
+            frameworks: telemetry.frameworksList
+        });
+    }
+
+    if (format === 'jsonl') {
+        return formatJsonlEvent({
+            organization: companyName,
+            department: department,
+            timestamp,
+            sessionHash,
+            riskLevel: telemetry.riskLevel,
+            tokensMasked: telemetry.totalCount,
+            entities: telemetry.entities,
+            frameworks: telemetry.frameworksList
+        });
+    }
+
+    if (format === 'json') {
+        return {
+            protocol: "Zero-Trust Data Sanitization (ZTDS)",
+            certificateId: `ZTDS-CERT-${sessionHash.substring(0, 16).toUpperCase()}`,
+            organization: companyName,
+            department: department,
+            timestamp: timestamp,
+            sessionHash: sessionHash,
+            verificationMode: "100% Offline (In-Memory RAM)",
+            complianceStatus: "VERIFIED PASS",
+            riskLevel: telemetry.riskLevel,
+            frameworksEnforced: telemetry.frameworksList,
+            totalMaskedTokens: telemetry.totalCount,
+            entitiesBreakdown: telemetry.entities,
+            zeroEgressVerified: true,
+            verificationUrl: `https://privacyscrubber.com/features/audit-receipt/#verify?hash=${sessionHash.substring(0, 16)}`
+        };
+    }
+
+    if (format === 'summary') {
+        return `[PrivacyScrubber Compliance Certificate] ID: ZTDS-${sessionHash.substring(0, 8).toUpperCase()} | Organization: ${companyName} | Masked Tokens: ${telemetry.totalCount} | Risk: ${telemetry.riskLevel} | Frameworks: ${telemetry.frameworksList.join(', ')} | Status: PASS (100% Air-Gapped)`;
+    }
+
+    return `# 🛡️ Zero-Trust Data Sanitization Compliance Certificate
+**Certificate ID:** \`ZTDS-CERT-${sessionHash.substring(0, 16).toUpperCase()}\`  
+**Organization:** ${companyName} (${department})  
+**Timestamp:** ${timestamp}  
+**Verification Mode:** 100% Local In-Memory Processing (Air-Gapped)  
+**Status:** **VERIFIED PASS** (Zero Network Egress)
+
+---
+
+### 📊 Sanitization Metrics & Risk Assessment
+* **Overall Risk Rating:** **${telemetry.riskLevel}**
+* **Total Sensitive Entities Masked:** \`${telemetry.totalCount}\`
+* **Entity Breakdown:** ${entitySummary}
+* **Network Data Transmitted:** \`0.00 KB (Zero-Trust Local RAM)\`
+
+### 📜 Regulatory Frameworks Enforced
+${telemetry.frameworksList.map(f => `- **${f}**`).join('\n')}
+
+### 🔒 CISO Compliance Declaration
+1. **EU AI Act (Art. 50) & GDPR (Art. 25 & 32):** Data minimization and local pseudonymization enforced prior to model interaction.
+2. **HIPAA Safe Harbor (§164.514) / SOC 2 Type II:** All direct and indirect identifiers sanitized locally without cloud processor liability.
+3. **Cryptographic Verification:** Tamper-evident session verification hash: \`${sessionHash}\`
+
+*Certified Offline by PrivacyScrubber Core SDK*  
+*Verify at: https://privacyscrubber.com/features/audit-receipt/*`;
+}
+
+/**
+ * Creates a Node.js Transform stream that sanitizes incoming text chunks line-by-line in volatile RAM.
+ * Zero external network egress. Zero memory bloat. Ideal for streaming server logs, CSVs, or HTTP responses.
+ * 
+ * @param {object} [options={}] - Stream configuration or PrivacyScrubberEngine options.
+ * @param {PrivacyScrubberEngine} [options.engine] - Optional pre-configured PrivacyScrubberEngine instance.
+ * @param {string} [options.profile='General'] - Compliance detection profile.
+ * @param {string} [options.licenseKey] - Optional license key.
+ * @param {boolean} [options.detectSecrets=false] - Auto-detect cloud credentials and API keys.
+ * @param {Array} [options.customRules=[]] - Custom regex rules.
+ * @returns {Transform & { getSessionMap: () => Record<string, string>, getTelemetry: () => object, engine: PrivacyScrubberEngine }}
+ */
+function createSanitizeStream(options = {}) {
+    const engine = options.engine || new PrivacyScrubberEngine(options);
+    const persistSession = options.persistSession !== false;
+    const maxSessionTokens = options.maxSessionTokens || 10000;
+    let tail = '';
+
+    const stream = new Transform({
+        transform(chunk, encoding, callback) {
+            try {
+                const str = tail + (Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk));
+                const lines = str.split('\n');
+                tail = lines.pop() || '';
+
+                for (let i = 0; i < lines.length; i++) {
+                    const sanitized = engine.sanitize(lines[i], {
+                        ...options,
+                        persistSession,
+                        maxSessionTokens,
+                        generateReceipt: false
+                    });
+                    this.push(sanitized.scrubbedText + '\n');
+                }
+                callback();
+            } catch (err) {
+                callback(err);
+            }
+        },
+        flush(callback) {
+            try {
+                if (tail.length > 0) {
+                    const sanitized = engine.sanitize(tail, {
+                        ...options,
+                        persistSession,
+                        maxSessionTokens,
+                        generateReceipt: false
+                    });
+                    this.push(sanitized.scrubbedText);
+                    tail = '';
+                }
+                callback();
+            } catch (err) {
+                callback(err);
+            }
+        },
+        destroy(err, callback) {
+            tail = '';
+            callback(err);
+        }
+    });
+
+    stream.engine = engine;
+    stream.getSessionMap = () => ({ ...engine.sessionMap });
+    stream.getTelemetry = () => buildAuditTelemetry(engine.sessionMap);
+
+    return stream;
+}
+
+/**
+ * Restores masked tokens in AI-generated code or text locally in volatile RAM,
+ * and writes the authentic content directly to the destination file on disk.
+ * 
+ * @param {string} filePath - Target file destination.
+ * @param {string} content - Code/text containing placeholder tokens (e.g. [API_KEY_1]).
+ * @param {object} [options={}] - Options: tokenMap, engine, createBackup (default: true).
+ * @returns {{ success: boolean, filePath: string, restoredCount: number, backupCreated: boolean, backupPath?: string }}
+ */
+function applyPatch(filePath, content, options = {}) {
+    if (!filePath || typeof filePath !== 'string') {
+        throw new Error('[PrivacyScrubber] Missing required parameter: filePath must be a string.');
+    }
+    if (content === undefined || content === null || typeof content !== 'string') {
+        throw new Error('[PrivacyScrubber] Missing required parameter: content must be a string.');
+    }
+
+    const {
+        tokenMap = null,
+        engine = null,
+        createBackup = true
+    } = options;
+
+    const activeTokenMap = tokenMap || (engine && engine.sessionMap) || {};
+    const resolvedPath = path.resolve(process.cwd(), filePath);
+    const restored = unscrub(content, activeTokenMap);
+
+    let backupCreated = false;
+    let backupPath;
+
+    if (createBackup && fs.existsSync(resolvedPath)) {
+        backupPath = `${resolvedPath}.bak`;
+        fs.copyFileSync(resolvedPath, backupPath);
+        backupCreated = true;
+    }
+
+    const parentDir = path.dirname(resolvedPath);
+    if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+    }
+
+    fs.writeFileSync(resolvedPath, restored.restoredText, 'utf8');
+
+    return {
+        success: true,
+        filePath: resolvedPath,
+        restoredCount: restored.restoredCount || 0,
+        backupCreated,
+        backupPath
+    };
+}
+
+/**
+ * Alias for applyPatch.
+ */
+function restoreToFile(filePath, content, tokenMapOrOptions = {}, options = {}) {
+    if (tokenMapOrOptions && typeof tokenMapOrOptions === 'object' && !tokenMapOrOptions.sessionMap && !tokenMapOrOptions.tokenMap) {
+        return applyPatch(filePath, content, { ...options, tokenMap: tokenMapOrOptions });
+    }
+    return applyPatch(filePath, content, typeof tokenMapOrOptions === 'object' ? tokenMapOrOptions : options);
+}
+
+/**
+ * Creates CISO-grade Zero-Trust Agentic Guard tools for AI agents & LLM frameworks.
+ * Compatible with Vercel AI SDK, OpenAI function calling, LangChain, and AutoGen.
+ * Intercepts terminal commands, file reads, and code writes, masking secrets into volatile RAM.
+ * 
+ * @param {PrivacyScrubberEngine|object} [engineOrOptions={}] - PrivacyScrubberEngine or config options.
+ * @param {object} [toolConfig={}] - Default configuration: cwd, profile.
+ * @returns {object} Object containing guardExec, guardReadFile, guardApplyPatch, guardGitDiff, getDefinitions, and engine.
+ */
+function createGuardedTools(engineOrOptions = {}, toolConfig = {}) {
+    const engine = (engineOrOptions instanceof PrivacyScrubberEngine)
+        ? engineOrOptions
+        : new PrivacyScrubberEngine(engineOrOptions);
+
+    const baseCwd = toolConfig.cwd || process.cwd();
+    const defaultProfile = toolConfig.profile || engine.defaultProfile || 'Dev';
+
+    const tools = {
+        guardExec: {
+            name: 'guard_exec',
+            description: 'Executes a shell command locally, intercepts stdout/stderr line-by-line, sanitizes credentials and PII into RAM tokens, and returns clean text to model context.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    command: { type: 'string', description: 'Shell command to execute.' },
+                    cwd: { type: 'string', description: 'Working directory.' },
+                    profile: { type: 'string', description: 'Detection profile (default: Dev).' },
+                    timeoutMs: { type: 'number', description: 'Execution timeout in milliseconds (default: 15000).' }
+                },
+                required: ['command']
+            },
+            execute: async ({ command, cwd, profile = defaultProfile, timeoutMs = 15000 } = {}) => {
+                if (!command || typeof command !== 'string') {
+                    throw new Error('[guard_exec] Missing or invalid parameter: command must be a string.');
+                }
+                const execCwd = cwd ? path.resolve(baseCwd, cwd) : baseCwd;
+                let stdout = '';
+                let stderr = '';
+                let exitCode = 0;
+
+                try {
+                    stdout = execSync(command, {
+                        cwd: execCwd,
+                        timeout: Math.min(Math.max(timeoutMs, 1000), 60000),
+                        maxBuffer: 10 * 1024 * 1024,
+                        encoding: 'utf8',
+                        stdio: ['pipe', 'pipe', 'pipe']
+                    });
+                } catch (err) {
+                    stdout = err.stdout ? err.stdout.toString() : '';
+                    stderr = err.stderr ? err.stderr.toString() : (err.message || '');
+                    exitCode = typeof err.status === 'number' ? err.status : 1;
+                }
+
+                const resCommand = engine.sanitize(command, { profile, detectSecrets: true, persistSession: true, generateReceipt: false });
+                const resStdout = engine.sanitize(stdout, { profile, detectSecrets: true, persistSession: true, generateReceipt: false });
+                const resStderr = engine.sanitize(stderr, { profile, detectSecrets: true, persistSession: true, generateReceipt: false });
+
+                const newTokens = { ...resCommand.tokenMap, ...resStdout.tokenMap, ...resStderr.tokenMap };
+                const telemetry = buildAuditTelemetry(newTokens);
+                const receipt = formatAuditReceipt(telemetry);
+
+                const responseText = `[Zero-Trust Agentic Guard: Exec]\n` +
+                    `Command: ${resCommand.scrubbedText}\n` +
+                    `Exit Code: ${exitCode}\n` +
+                    `Tokens Redacted: ${Object.keys(newTokens).length}\n\n` +
+                    (resStdout.scrubbedText ? `--- STDOUT ---\n${resStdout.scrubbedText}\n\n` : '') +
+                    (resStderr.scrubbedText ? `--- STDERR ---\n${resStderr.scrubbedText}\n\n` : '') +
+                    receipt;
+
+                return {
+                    command: resCommand.scrubbedText,
+                    stdout: resStdout.scrubbedText,
+                    stderr: resStderr.scrubbedText,
+                    exitCode,
+                    tokenCount: Object.keys(newTokens).length,
+                    telemetry,
+                    receipt,
+                    responseText
+                };
+            }
+        },
+
+        guardReadFile: {
+            name: 'guard_read_file',
+            description: 'Reads local file contents, tokenizing sensitive credentials and PII in volatile RAM before returning text to model context.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    filePath: { type: 'string', description: 'Path to target file.' },
+                    maxLines: { type: 'number', description: 'Maximum lines to read (default: 500).' },
+                    profile: { type: 'string', description: 'Detection profile (default: Dev).' }
+                },
+                required: ['filePath']
+            },
+            execute: async ({ filePath, maxLines = 500, profile = defaultProfile } = {}) => {
+                if (!filePath || typeof filePath !== 'string') {
+                    throw new Error('[guard_read_file] Missing or invalid parameter: filePath must be a string.');
+                }
+                const resolved = path.resolve(baseCwd, filePath);
+                if (!fs.existsSync(resolved)) {
+                    throw new Error(`[guard_read_file] File not found: ${resolved}`);
+                }
+                const stat = fs.statSync(resolved);
+                if (stat.isDirectory()) {
+                    throw new Error(`[guard_read_file] Path is a directory, not a file: ${resolved}`);
+                }
+
+                const raw = fs.readFileSync(resolved, 'utf8');
+                const lines = raw.split(/\r?\n/);
+                const capped = lines.slice(0, maxLines).join('\n');
+                const wasTruncated = lines.length > maxLines;
+
+                const res = engine.sanitize(capped, { profile, detectSecrets: true, persistSession: true, generateReceipt: false });
+                const telemetry = buildAuditTelemetry(res.tokenMap);
+                const receipt = formatAuditReceipt(telemetry);
+
+                const responseText = `[Zero-Trust Agentic Guard: File Read: ${path.basename(resolved)}]\n` +
+                    `Path: ${resolved}\n` +
+                    `Total Lines: ${lines.length}${wasTruncated ? ` (Capped to ${maxLines} lines)` : ''}\n` +
+                    `Tokens Redacted: ${res.count}\n\n` +
+                    `--- SANITIZED CONTENT ---\n` +
+                    res.scrubbedText + '\n\n' +
+                    receipt;
+
+                return {
+                    filePath: resolved,
+                    content: res.scrubbedText,
+                    totalLines: lines.length,
+                    wasTruncated,
+                    tokenCount: res.count,
+                    telemetry,
+                    receipt,
+                    responseText
+                };
+            }
+        },
+
+        guardApplyPatch: {
+            name: 'guard_apply_patch',
+            description: 'Restores authentic secrets locally from volatile RAM session map and writes real content directly to target file with automatic .bak backup.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    filePath: { type: 'string', description: 'Destination file path.' },
+                    content: { type: 'string', description: 'Content containing token placeholders (e.g. [API_KEY_1]).' },
+                    createBackup: { type: 'boolean', description: 'Whether to create .bak backup if file exists (default: true).' }
+                },
+                required: ['filePath', 'content']
+            },
+            execute: async ({ filePath, content, createBackup = true } = {}) => {
+                const patchResult = applyPatch(filePath, content, {
+                    tokenMap: engine.sessionMap,
+                    createBackup
+                });
+
+                const responseText = `[Zero-Trust Agentic Guard: Patch Applied]\n` +
+                    `Destination: ${patchResult.filePath}\n` +
+                    `Tokens Restored Locally: ${patchResult.restoredCount}\n` +
+                    `Backup Created: ${patchResult.backupCreated ? `${patchResult.filePath}.bak` : 'No'}\n` +
+                    `Status: File written with 100% authentic local values. Remote LLM received zero secrets.`;
+
+                return {
+                    ...patchResult,
+                    responseText
+                };
+            }
+        },
+
+        guardGitDiff: {
+            name: 'guard_git_diff',
+            description: 'Inspects staged or unstaged git diff changes with credentials and PII masked into volatile RAM tokens.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    staged: { type: 'boolean', description: 'Whether to review staged changes (--cached).' },
+                    cwd: { type: 'string', description: 'Repository directory.' },
+                    profile: { type: 'string', description: 'Detection profile (default: Dev).' }
+                },
+                required: []
+            },
+            execute: async ({ staged = false, cwd, profile = defaultProfile } = {}) => {
+                const repoCwd = cwd ? path.resolve(baseCwd, cwd) : baseCwd;
+                const gitCmd = staged ? 'git diff --cached' : 'git diff';
+                let diffOutput = '';
+
+                try {
+                    diffOutput = execSync(gitCmd, { cwd: repoCwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+                } catch (err) {
+                    if (err.code === 'ENOBUFS' && err.stdout) {
+                        diffOutput = err.stdout.toString('utf8');
+                    } else {
+                        throw new Error(`[guard_git_diff] Git command failed: ${err.message}`);
+                    }
+                }
+
+                if (!diffOutput.trim()) {
+                    return {
+                        diff: '',
+                        isStaged: !!staged,
+                        tokenCount: 0,
+                        responseText: `[Zero-Trust Agentic Guard: Git Diff]\nNo changes detected (${staged ? 'staged' : 'unstaged'}).`
+                    };
+                }
+
+                const res = engine.sanitize(diffOutput, { profile, detectSecrets: true, persistSession: true, generateReceipt: false });
+                const telemetry = buildAuditTelemetry(res.tokenMap);
+                const receipt = formatAuditReceipt(telemetry);
+
+                const responseText = `[Zero-Trust Agentic Guard: Git Diff (${staged ? 'Staged' : 'Unstaged'})]\n` +
+                    `Tokens Redacted: ${res.count}\n\n` +
+                    `--- SANITIZED DIFF ---\n` +
+                    res.scrubbedText + '\n\n' +
+                    receipt;
+
+                return {
+                    diff: res.scrubbedText,
+                    isStaged: !!staged,
+                    tokenCount: res.count,
+                    telemetry,
+                    receipt,
+                    responseText
+                };
+            }
+        }
+    };
+
+    tools.getDefinitions = () => [
+        { type: 'function', function: { name: tools.guardExec.name, description: tools.guardExec.description, parameters: tools.guardExec.parameters } },
+        { type: 'function', function: { name: tools.guardReadFile.name, description: tools.guardReadFile.description, parameters: tools.guardReadFile.parameters } },
+        { type: 'function', function: { name: tools.guardApplyPatch.name, description: tools.guardApplyPatch.description, parameters: tools.guardApplyPatch.parameters } },
+        { type: 'function', function: { name: tools.guardGitDiff.name, description: tools.guardGitDiff.description, parameters: tools.guardGitDiff.parameters } }
+    ];
+
+    tools.engine = engine;
+    return tools;
+}
+
+// Low-level backwards-compatible exports
+const scrubText = scrubberPkg.scrubText;
+const unscrubText = scrubberPkg.unscrubText;
+
+// Vision & Multimodal exports
+const {
+    stripExifMetadata,
+    redactImageBoundingBoxes,
+    generateSvgRedactionOverlay
+} = require('./vision.cjs');
+
+const _defaultExport = {
+    sanitize,
+    sanitizeObject,
+    scrub,
+    clean,
+    restore,
+    restoreObject,
+    unscrub,
+    desanitize,
+    validateLicense,
+    validateLicenseKey,
+    buildAuditTelemetry,
+    buildCisoAuditTelemetry,
+    formatAuditReceipt,
+    generateAuditReport,
+    formatCefEvent,
+    formatSyslogEvent,
+    formatJsonlEvent,
+    createAuditLogger,
+    generateProcurementMemo,
+    PrivacyScrubberEngine,
+    PrivacyScrubberLicenseError,
+    wrapOpenAI,
+    wrapAiModel,
+    wrapAiSdk,
+    createLangChainTransform,
+    createDocumentTransformer,
+    createLangChainDocumentTransformer,
+    createLlamaIndexTransform,
+    createVectorIngestionGuard,
+    StreamingDetokenizer,
+    createStreamTokenRestorer,
+    createNodeStreamTokenRestorer,
+    buildStreamReplacer,
+    wrapAiStream,
+    withPrivacyScrubber,
+    createExpressMiddleware,
+    createSanitizeStream,
+    applyPatch,
+    restoreToFile,
+    createGuardedTools,
+    scrubText,
+    unscrubText,
+    DEVOPS_SECRETS_DETECTOR,
+    stripExifMetadata,
+    redactImageBoundingBoxes,
+    generateSvgRedactionOverlay
+};
+
+
+module.exports = _defaultExport;
+module.exports.default = _defaultExport;
+for (const [key, val] of Object.entries(_defaultExport)) {
+    module.exports[key] = val;
+}