@privacyscrubber/sdk 2.1.0 → 2.2.1

package/index.js

@@ -10,6 +10,10 @@
 
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { Transform } from 'stream';
 
 import './polyfill.js';
 import './ps-license-manager.js';
@@ -160,7 +164,8 @@ export function buildAuditTelemetry(currentTokenMap = {}) {
  */
 export function formatAuditReceipt(telemetry) {
     if (!telemetry || telemetry.totalCount === 0) {
-        return "> 🛡️ **PrivacyScrubber Audit Receipt**: CLEAN (ZERO PII DETECTED)\n";
+        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}`)
@@ -171,22 +176,42 @@ export function formatAuditReceipt(telemetry) {
     return `> 🛡️ **PrivacyScrubber Audit Receipt**\n` +
            `> * **Risk Level:** ${icon} ${telemetry.riskLevel}\n` +
            `> * **Compliance Enforced:** ${telemetry.frameworksList.join(', ')}\n` +
-           `> * **Tokens Masked:** ${telemetry.totalCount} (${entitiesList})\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
+ */
+export function _resetCommunityNoticeForTesting() {
+    communityNoticeLogged = false;
 }
 
 /**
- * Primary High-Level Function: Sanitize / Scrub text of PII and secrets.
+ * Sanitizes input text, masking detected PII & secrets with reversible tokens.
  * 
- * @param {string} text - Raw input text containing potential PII/secrets.
- * @param {object} [options={}] - Configuration options.
- * @param {string} [options.profile='General'] - PII Profile (General, Dev, Medical, Financial, Legal, HR, etc.).
+ * @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} [options.customRules=[]] - Custom regex rules array.
- * @param {Record<string, string>} [options.tokenLabelMap={}] - Custom label overrides.
- * @param {Record<string, string>} [options.existingSessionMap={}] - Session map to maintain consistency across turns.
- * @param {boolean} [options.generateReceipt=true] - Whether to generate Markdown audit receipt.
+ * @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 {boolean} [options.detectSecrets=false] - Auto-inject DevOps & Cloud secrets detection rules.
+ * @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>,
@@ -226,6 +251,8 @@ export function sanitize(text, options = {}) {
     const isPro = licenseCheck.valid;
     const tier = isPro ? licenseCheck.tier : 'FREE';
 
+    emitCommunityNoticeIfNeeded(isPro);
+
     const isSpecialized = profile && profile.toLowerCase() !== 'general';
     const limit = isPro ? Infinity : (isSpecialized ? 5000 : 15000);
 
@@ -302,6 +329,18 @@ export function sanitize(text, options = {}) {
  */
 export 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.
+ */
+export 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.
  * 
@@ -486,6 +525,198 @@ export function createLangChainTransform(options = {}) {
     };
 }
 
+/**
+ * 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, flush: () => string, wrapStream: (asyncIterable: AsyncIterable<string>) => AsyncGenerator<string> }}
+ */
+export function createStreamTokenRestorer(tokenMap = {}, options = {}) {
+    let pendingBuffer = '';
+    const map = tokenMap && typeof tokenMap === 'object' ? tokenMap : {};
+
+    function directRestore(text) {
+        if (!text) return '';
+        let result = text;
+        for (const token in map) {
+            if (result.includes(token)) {
+                result = result.split(token).join(map[token]);
+            }
+        }
+        return result;
+    }
+
+    function processChunk(chunk) {
+        if (!chunk || typeof chunk !== 'string') return '';
+        pendingBuffer += chunk;
+
+        // Check if there is an unclosed potential token bracket at the tail of the buffer.
+        // Token format: [TYPE_INDEX] or [CUSTOM_NAME] e.g. [EMAIL_1], [NAME_2], [SECRET_1]
+        const lastOpenIdx = pendingBuffer.lastIndexOf('[');
+        const lastCloseIdx = pendingBuffer.lastIndexOf(']');
+
+        if (lastOpenIdx !== -1 && lastOpenIdx > lastCloseIdx) {
+            const partial = pendingBuffer.slice(lastOpenIdx);
+            if (/^\[[A-Za-z0-9_]*$/.test(partial) && partial.length <= 64) {
+                const safeToEmit = pendingBuffer.slice(0, lastOpenIdx);
+                pendingBuffer = partial;
+                if (safeToEmit) {
+                    return directRestore(safeToEmit);
+                }
+                return '';
+            }
+        }
+
+        const textToRestore = pendingBuffer;
+        pendingBuffer = '';
+        return directRestore(textToRestore);
+    }
+
+    function flushBuffer() {
+        if (!pendingBuffer) return '';
+        const remaining = pendingBuffer;
+        pendingBuffer = '';
+        return directRestore(remaining);
+    }
+
+    async function* wrapStream(asyncIterable) {
+        for await (const chunk of asyncIterable) {
+            const text = typeof chunk === 'string' ? chunk : (chunk?.text || chunk?.content || '');
+            const emitted = processChunk(text);
+            if (emitted) yield emitted;
+        }
+        const finalChunk = flushBuffer();
+        if (finalChunk) yield finalChunk;
+    }
+
+    let stream;
+    if (typeof TransformStream !== 'undefined') {
+        stream = new TransformStream({
+            transform(chunk, controller) {
+                const text = typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
+                const out = processChunk(text);
+                if (out) controller.enqueue(out);
+            },
+            flush(controller) {
+                const out = flushBuffer();
+                if (out) controller.enqueue(out);
+            }
+        });
+    } else {
+        stream = {};
+    }
+
+    stream.process = processChunk;
+    stream.flush = flushBuffer;
+    stream.wrapStream = wrapStream;
+
+    return stream;
+}
+
+/**
+ * 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<string>}
+ */
+export async function* wrapAiStream(stream, tokenMap = {}) {
+    const restorer = createStreamTokenRestorer(tokenMap);
+    yield* restorer.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
+ */
+export 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)
+ */
+export 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.
@@ -557,6 +788,359 @@ ${telemetry.frameworksList.map(f => `- **${f}**`).join('\n')}
 *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 }}
+ */
+export function createSanitizeStream(options = {}) {
+    const engine = options.engine || new PrivacyScrubberEngine(options);
+    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], { persistSession: true, generateReceipt: false });
+                    this.push(sanitized.scrubbedText + '\n');
+                }
+                callback();
+            } catch (err) {
+                callback(err);
+            }
+        },
+        flush(callback) {
+            try {
+                if (tail.length > 0) {
+                    const sanitized = engine.sanitize(tail, { persistSession: true, generateReceipt: false });
+                    this.push(sanitized.scrubbedText);
+                    tail = '';
+                }
+                callback();
+            } catch (err) {
+                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 }}
+ */
+export 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.
+ */
+export 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.
+ */
+export 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
 export const scrubText = scrubberPkg.scrubText;
 export const unscrubText = scrubberPkg.unscrubText;
@@ -564,6 +1148,7 @@ export const unscrubText = scrubberPkg.unscrubText;
 export default {
     sanitize,
     scrub,
+    clean,
     restore,
     unscrub,
     validateLicense,
@@ -575,6 +1160,14 @@ export default {
     PrivacyScrubberLicenseError,
     wrapOpenAI,
     createLangChainTransform,
+    createStreamTokenRestorer,
+    wrapAiStream,
+    withPrivacyScrubber,
+    createExpressMiddleware,
+    createSanitizeStream,
+    applyPatch,
+    restoreToFile,
+    createGuardedTools,
     scrubText,
     unscrubText,
     DEVOPS_SECRETS_DETECTOR