@privacyscrubber/sdk 2.4.5 → 2.4.6

package/README.md

@@ -109,6 +109,55 @@ const completion = await openai.chat.completions.create({
 console.log(completion.choices[0].message.content);
 ```
 
+#### 1b. Google Gemini SDK Wrapper (`wrapGemini` / `wrapGoogleGenAI`)
+
+Supports both the official `@google/genai` SDK (`ai.models.generateContent`, `ai.models.generateContentStream`) and `@google/generative-ai` (`model.generateContent`, `getGenerativeModel`):
+
+```javascript
+import { GoogleGenAI } from '@google/genai';
+import { wrapGemini } from '@privacyscrubber/sdk';
+
+const ai = wrapGemini(new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }), {
+    profile: 'General'
+});
+
+const response = await ai.models.generateContent({
+    model: 'gemini-2.5-flash',
+    contents: 'Summarize onboarding notes for Sarah Connor (sarah.connor@cyberdyne.io).'
+});
+
+// Response .text and candidates[].content.parts[].text are automatically restored in RAM:
+console.log(response.text);
+```
+
+#### 1c. Universal HTTP & SSE `fetch` Interceptor (`createPrivacyFetch`)
+
+Drop-in `fetch` wrapper for **OpenAI, Anthropic, OpenRouter, Groq, DeepSeek, Mistral, Together, Ollama**, or Cloudflare AI Gateway. Scrubs outbound JSON request payloads (`messages`, `prompt`, `input`, `system`, `contents`) in local RAM and transparently detokenizes both standard JSON responses and `text/event-stream` Server-Sent Events (SSE) streams:
+
+```javascript
+import OpenAI from 'openai';
+import { createPrivacyFetch } from '@privacyscrubber/sdk';
+
+const client = new OpenAI({
+    baseURL: 'https://openrouter.ai/api/v1',
+    apiKey: process.env.OPENROUTER_API_KEY,
+    fetch: createPrivacyFetch({ profile: 'Dev', detectSecrets: true })
+});
+```
+
+#### 1d. OpenAI Agents SDK Guardrails (`createOpenAIAgentGuardrails`)
+
+Plug-and-play `inputGuardrail` and `outputGuardrail` descriptors compatible with `@openai/agents`, complete with optional `tripwireTriggered` enforcement for critical secrets or strict zero-PII boundaries:
+
+```javascript
+import { createOpenAIAgentGuardrails } from '@privacyscrubber/sdk';
+
+const { inputGuardrail, outputGuardrail, sanitizeInput, restoreOutput } = createOpenAIAgentGuardrails({
+    profile: 'Dev',
+    tripwireOnCritical: true // Triggers agent tripwire if raw keys/SSN are detected
+});
+```
+
 ---
 
 ### 2. Direct In-Memory Sanitization & Restoration
@@ -166,7 +215,7 @@ const { scrubbedText, tokenMap } = sanitize(rawCrmPayload, {
 
 ### 3. Vercel AI SDK Integration (`@privacyscrubber/sdk/vercel-ai`)
 
-Dedicated zero-dependency submodule for Next.js App Router and Node.js applications built with the Vercel AI SDK (`ai`):
+Dedicated zero-dependency submodule for Next.js App Router and Node.js applications built with the Vercel AI SDK (`ai` v4, v5, and v6 — compatible with `LanguageModelV1` `textDelta` as well as `LanguageModelV2`/`LanguageModelV3` `delta` and `reasoning-delta` streams, `result.content` arrays, and `tool-result` output sanitization):
 
 ```bash
 npm install @privacyscrubber/sdk

package/browser.js

@@ -307,7 +307,14 @@ export function sanitize(text, options = {}) {
         wasTruncated = true;
     }
 
-    const activeRules = [...customRules];
+    const nestedQuantifierRegex = /\([^)]*(\+|\*|\{\d+,?\d*\})\)[+*]|\([^)]*(\+|\*|\{\d+,?\d*\})\)\{\d+,?\d*\}|\([^)]*\|[^)]*\)(?:[+*]|\{\d+,?\d*\})/;
+    const safeCustomRules = (Array.isArray(customRules) ? customRules : []).filter(r => {
+        const pat = typeof r === 'string' ? r : (r && (r.pattern || (r.regex && r.regex.source)));
+        if (!pat || typeof pat !== 'string' || pat.length > 500) return false;
+        if (nestedQuantifierRegex.test(pat)) return false;
+        return true;
+    });
+    const activeRules = [...safeCustomRules];
     if (profile.toLowerCase() === 'dev' || detectSecrets === true) {
         DEVOPS_SECRETS_DETECTOR.forEach(rule => {
             activeRules.push({
@@ -448,6 +455,21 @@ export function sanitizeObject(obj, options = {}) {
 
     const mergedSessionMap = { ...(options.existingSessionMap || {}) };
     let totalCount = 0;
+    const seen = new WeakMap();
+
+    function isNonPlainObject(val) {
+        return (
+            val instanceof Date ||
+            val instanceof RegExp ||
+            val instanceof Error ||
+            val instanceof Promise ||
+            val instanceof WeakMap ||
+            val instanceof WeakSet ||
+            (typeof URL !== 'undefined' && val instanceof URL) ||
+            ArrayBuffer.isView(val) ||
+            (typeof ArrayBuffer !== 'undefined' && val instanceof ArrayBuffer)
+        );
+    }
 
     function traverseAndSanitize(val) {
         if (val === null || val === undefined) return val;
@@ -462,20 +484,42 @@ export function sanitizeObject(obj, options = {}) {
             totalCount += res.count;
             return res.scrubbedText;
         }
+        if (typeof val !== 'object') return val;
+        if (isNonPlainObject(val)) return val;
+        if (seen.has(val)) return seen.get(val);
+
         if (Array.isArray(val)) {
-            return val.map(item => traverseAndSanitize(item));
+            const outArr = [];
+            seen.set(val, outArr);
+            for (let i = 0; i < val.length; i++) {
+                outArr.push(traverseAndSanitize(val[i]));
+            }
+            return outArr;
         }
-        if (val instanceof Date || val instanceof RegExp) {
-            return val;
+        if (val instanceof Map) {
+            const outMap = new Map();
+            seen.set(val, outMap);
+            for (const [k, v] of val.entries()) {
+                outMap.set(k, traverseAndSanitize(v));
+            }
+            return outMap;
         }
-        if (typeof val === 'object') {
-            const out = {};
-            for (const [k, v] of Object.entries(val)) {
-                out[k] = traverseAndSanitize(v);
+        if (val instanceof Set) {
+            const outSet = new Set();
+            seen.set(val, outSet);
+            for (const item of val.values()) {
+                outSet.add(traverseAndSanitize(item));
             }
-            return out;
+            return outSet;
         }
-        return val;
+
+        const out = {};
+        seen.set(val, out);
+        for (const [k, v] of Object.entries(val)) {
+            if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;
+            out[k] = traverseAndSanitize(v);
+        }
+        return out;
     }
 
     const sanitizedResult = traverseAndSanitize(obj);
@@ -498,23 +542,62 @@ export function sanitizeObject(obj, options = {}) {
     };
 }
 
-export function restoreObject(obj, tokenMap = {}) {
+export function restoreObject(obj, tokenMap = {}, _seen = null) {
     if (obj === null || obj === undefined) return obj;
     if (typeof obj === 'string') {
         const res = restore(obj, tokenMap);
         return res.restoredText;
     }
+    if (typeof obj !== 'object') return obj;
+    if (
+        obj instanceof Date ||
+        obj instanceof RegExp ||
+        obj instanceof Error ||
+        obj instanceof Promise ||
+        obj instanceof WeakMap ||
+        obj instanceof WeakSet ||
+        (typeof URL !== 'undefined' && obj instanceof URL) ||
+        ArrayBuffer.isView(obj) ||
+        (typeof ArrayBuffer !== 'undefined' && obj instanceof ArrayBuffer)
+    ) {
+        return obj;
+    }
+
+    const seen = _seen || new WeakMap();
+    if (seen.has(obj)) return seen.get(obj);
+
     if (Array.isArray(obj)) {
-        return obj.map(item => restoreObject(item, tokenMap));
+        const outArr = [];
+        seen.set(obj, outArr);
+        for (let i = 0; i < obj.length; i++) {
+            outArr.push(restoreObject(obj[i], tokenMap, seen));
+        }
+        return outArr;
     }
-    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);
+    if (obj instanceof Map) {
+        const outMap = new Map();
+        seen.set(obj, outMap);
+        for (const [k, v] of obj.entries()) {
+            outMap.set(k, restoreObject(v, tokenMap, seen));
         }
-        return out;
+        return outMap;
     }
-    return obj;
+    if (obj instanceof Set) {
+        const outSet = new Set();
+        seen.set(obj, outSet);
+        for (const item of obj.values()) {
+            outSet.add(restoreObject(item, tokenMap, seen));
+        }
+        return outSet;
+    }
+
+    const out = {};
+    seen.set(obj, out);
+    for (const [k, v] of Object.entries(obj)) {
+        if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;
+        out[k] = restoreObject(v, tokenMap, seen);
+    }
+    return out;
 }
 
 /**
@@ -546,12 +629,16 @@ export class PrivacyScrubberEngine {
                 .forEach(v => mergedIgnoreList.add(v));
         }
 
+        const effectiveExistingMap = options.persistSession !== false
+            ? { ...this.sessionMap, ...(options.existingSessionMap || {}) }
+            : (options.existingSessionMap || {});
+
         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 || {}),
+            existingSessionMap: effectiveExistingMap,
             generateReceipt: options.generateReceipt !== undefined ? options.generateReceipt : this.generateReceipt,
             throwOnLimit: options.throwOnLimit !== undefined ? options.throwOnLimit : true,
             detectSecrets: options.detectSecrets !== undefined ? options.detectSecrets : false,
@@ -1116,6 +1203,295 @@ export function generateAuditReport(sessionMap = {}, options = {}) {
     return formatPsr2Report({ format: format === 'summary' ? 'summary' : 'markdown', receipt, telemetry, company_name: companyName, department, utmMedium: 'markdown' });
 }
 
+export function wrapGemini(geminiClientOrModel, options = {}) {
+    if (!geminiClientOrModel || typeof geminiClientOrModel !== 'object') {
+        throw new Error('[PrivacyScrubber] Invalid Gemini client or model passed to wrapGemini.');
+    }
+    const engine = options.engine || new PrivacyScrubberEngine(options);
+    const sharedSessionMap = {};
+
+    function sanitizeGeminiContentNode(node, sessionTokenMap) {
+        if (node === null || node === undefined) return node;
+        if (typeof node === 'string') {
+            const res = engine.sanitize(node, { existingSessionMap: sessionTokenMap });
+            Object.assign(sessionTokenMap, res.tokenMap);
+            return res.scrubbedText;
+        }
+        if (Array.isArray(node)) {
+            return node.map(item => sanitizeGeminiContentNode(item, sessionTokenMap));
+        }
+        if (typeof node === 'object') {
+            const copy = { ...node };
+            if (typeof copy.text === 'string') {
+                const res = engine.sanitize(copy.text, { existingSessionMap: sessionTokenMap });
+                Object.assign(sessionTokenMap, res.tokenMap);
+                copy.text = res.scrubbedText;
+            }
+            if (Array.isArray(copy.parts)) {
+                copy.parts = copy.parts.map(p => sanitizeGeminiContentNode(p, sessionTokenMap));
+            }
+            if (copy.contents !== undefined) {
+                copy.contents = sanitizeGeminiContentNode(copy.contents, sessionTokenMap);
+            }
+            if (copy.systemInstruction !== undefined) {
+                copy.systemInstruction = sanitizeGeminiContentNode(copy.systemInstruction, sessionTokenMap);
+            }
+            if (copy.config && typeof copy.config === 'object') {
+                copy.config = { ...copy.config };
+                if (copy.config.systemInstruction !== undefined) {
+                    copy.config.systemInstruction = sanitizeGeminiContentNode(copy.config.systemInstruction, sessionTokenMap);
+                }
+            }
+            return copy;
+        }
+        return node;
+    }
+
+    function restoreGeminiResponseObject(respObj, sessionTokenMap, detok = null) {
+        if (!respObj || typeof respObj !== 'object') return respObj;
+        const restoreFn = (str) => detok ? detok.feed(str) : engine.restore(str, sessionTokenMap).restoredText;
+        let combinedText = '';
+        if (Array.isArray(respObj.candidates)) {
+            respObj.candidates = respObj.candidates.map(cand => {
+                if (!cand || typeof cand !== 'object') return cand;
+                const candCopy = { ...cand };
+                if (candCopy.content && Array.isArray(candCopy.content.parts)) {
+                    candCopy.content = {
+                        ...candCopy.content,
+                        parts: candCopy.content.parts.map(part => {
+                            if (part && typeof part.text === 'string') {
+                                const restoredText = restoreFn(part.text);
+                                combinedText += restoredText;
+                                return { ...part, text: restoredText };
+                            }
+                            return part;
+                        })
+                    };
+                }
+                return candCopy;
+            });
+        }
+        if (typeof respObj.text === 'function') {
+            const origTextFn = respObj.text.bind(respObj);
+            respObj.text = () => {
+                if (combinedText) return combinedText;
+                const raw = origTextFn();
+                return typeof raw === 'string' ? restoreFn(raw) : raw;
+            };
+        } else if (typeof respObj.text === 'string') {
+            respObj.text = combinedText || restoreFn(respObj.text);
+        } else if (combinedText) {
+            respObj.text = combinedText;
+        }
+        if (respObj.response && typeof respObj.response === 'object') {
+            restoreGeminiResponseObject(respObj.response, sessionTokenMap, detok);
+        }
+        return respObj;
+    }
+
+    function wrapTargetObject(target) {
+        if (typeof target.generateContent === 'function') {
+            const origGen = target.generateContent.bind(target);
+            target.generateContent = async function(req, ...rest) {
+                const sessionTokenMap = { ...sharedSessionMap };
+                const sanitizedReq = sanitizeGeminiContentNode(req, sessionTokenMap);
+                Object.assign(sharedSessionMap, sessionTokenMap);
+                const res = await origGen(sanitizedReq, ...rest);
+                return restoreGeminiResponseObject(res, sessionTokenMap);
+            };
+        }
+        if (typeof target.generateContentStream === 'function') {
+            const origStream = target.generateContentStream.bind(target);
+            target.generateContentStream = async function(req, ...rest) {
+                const sessionTokenMap = { ...sharedSessionMap };
+                const sanitizedReq = sanitizeGeminiContentNode(req, sessionTokenMap);
+                Object.assign(sharedSessionMap, sessionTokenMap);
+                const streamRes = await origStream(sanitizedReq, ...rest);
+                const detok = new StreamingDetokenizer(sessionTokenMap);
+                async function* wrapAsyncChunks(iterable) {
+                    let lastChunk = null;
+                    for await (const chunk of iterable) {
+                        if (!chunk) continue;
+                        lastChunk = chunk;
+                        const cloned = { ...chunk };
+                        restoreGeminiResponseObject(cloned, sessionTokenMap, detok);
+                        yield cloned;
+                    }
+                    const tail = detok.flush();
+                    if (tail && lastChunk) {
+                        yield { ...lastChunk, candidates: [{ content: { role: 'model', parts: [{ text: tail }] } }], text: tail };
+                    }
+                }
+                if (streamRes && typeof streamRes[Symbol.asyncIterator] === 'function') {
+                    return wrapAsyncChunks(streamRes);
+                }
+                if (streamRes && streamRes.stream && typeof streamRes.stream[Symbol.asyncIterator] === 'function') {
+                    return { ...streamRes, stream: wrapAsyncChunks(streamRes.stream) };
+                }
+                return streamRes;
+            };
+        }
+    }
+
+    if (geminiClientOrModel.models && typeof geminiClientOrModel.models === 'object') {
+        wrapTargetObject(geminiClientOrModel.models);
+    }
+    if (typeof geminiClientOrModel.generateContent === 'function' || typeof geminiClientOrModel.generateContentStream === 'function') {
+        wrapTargetObject(geminiClientOrModel);
+    }
+    geminiClientOrModel._ztdsEngine = engine;
+    return geminiClientOrModel;
+}
+
+export const wrapGoogleGenAI = wrapGemini;
+
+export function createPrivacyFetch(options = {}) {
+    const engine = options.engine || new PrivacyScrubberEngine(options);
+    const baseFetch = options.fetch || (typeof globalThis !== 'undefined' && globalThis.fetch);
+    const sanitizeInputs = options.sanitizeInputs !== false;
+    const sanitizeOutputs = options.sanitizeOutputs !== false;
+
+    const PROMPT_KEYS = new Set([
+        'messages', 'prompt', 'input', 'contents', 'system',
+        'systemInstruction', 'system_instruction', 'instructions', 'text', 'content'
+    ]);
+    const SAFE_SKIP_KEYS = new Set([
+        'model', 'role', 'type', 'id', 'object', 'finish_reason', 'stop_reason',
+        'encoding_format', 'response_format', 'tool_choice', 'stream'
+    ]);
+
+    function sanitizeJsonNode(node, sessionTokenMap) {
+        if (node === null || node === undefined) return node;
+        if (typeof node === 'string') {
+            if (!node.trim()) return node;
+            const res = engine.sanitize(node, { existingSessionMap: sessionTokenMap });
+            Object.assign(sessionTokenMap, res.tokenMap);
+            return res.scrubbedText;
+        }
+        if (Array.isArray(node)) {
+            return node.map(item => sanitizeJsonNode(item, sessionTokenMap));
+        }
+        if (typeof node === 'object') {
+            const out = {};
+            for (const [k, v] of Object.entries(node)) {
+                if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;
+                if (SAFE_SKIP_KEYS.has(k)) {
+                    out[k] = v;
+                } else if (PROMPT_KEYS.has(k) || typeof v === 'object') {
+                    out[k] = sanitizeJsonNode(v, sessionTokenMap);
+                } else {
+                    out[k] = v;
+                }
+            }
+            return out;
+        }
+        return node;
+    }
+
+    const privacyFetch = async function(input, init = {}) {
+        if (typeof baseFetch !== 'function') {
+            throw new Error('[PrivacyScrubber] No global fetch implementation found; pass { fetch } to createPrivacyFetch.');
+        }
+        const sessionTokenMap = { ...engine.sessionMap };
+        let modifiedInit = init ? { ...init } : {};
+        if (sanitizeInputs && modifiedInit && typeof modifiedInit.body === 'string') {
+            const trimmed = modifiedInit.body.trim();
+            if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+                try {
+                    const parsed = JSON.parse(modifiedInit.body);
+                    modifiedInit.body = JSON.stringify(sanitizeJsonNode(parsed, sessionTokenMap));
+                } catch (_) {}
+            }
+        }
+        const response = await baseFetch(input, modifiedInit);
+        if (!sanitizeOutputs || !response || Object.keys(sessionTokenMap).length === 0) {
+            return response;
+        }
+        const contentType = (response.headers && typeof response.headers.get === 'function')
+            ? (response.headers.get('content-type') || '').toLowerCase()
+            : '';
+        if (contentType.includes('application/json') || typeof response.json === 'function') {
+            try {
+                const rawText = typeof response.text === 'function'
+                    ? await response.text()
+                    : JSON.stringify(await response.json());
+                const restoredObj = restoreObject(JSON.parse(rawText), sessionTokenMap);
+                const restoredText = JSON.stringify(restoredObj);
+                if (typeof Response !== 'undefined') {
+                    const headers = new Headers(response.headers || {});
+                    headers.delete('content-length');
+                    return new Response(restoredText, { status: response.status, statusText: response.statusText, headers });
+                }
+                return { ...response, text: async () => restoredText, json: async () => restoredObj };
+            } catch (_) {
+                return response;
+            }
+        }
+        return response;
+    };
+    privacyFetch.engine = engine;
+    return privacyFetch;
+}
+
+export function createOpenAIAgentGuardrails(options = {}) {
+    const engine = options.engine || new PrivacyScrubberEngine(options);
+    const tripwireOnCritical = options.tripwireOnCritical === true;
+    const tripwireOnAnyPii = options.tripwireOnAnyPii === true;
+
+    const inputGuardrail = {
+        name: options.inputGuardrailName || 'PrivacyScrubber ZTDS Input Guardrail',
+        async execute({ input, context } = {}) {
+            const sessionTokenMap = { ...engine.sessionMap };
+            let scrubbedInput = input;
+            let count = 0;
+            if (typeof input === 'string') {
+                const res = engine.sanitize(input, { existingSessionMap: sessionTokenMap });
+                Object.assign(sessionTokenMap, res.tokenMap);
+                scrubbedInput = res.scrubbedText;
+                count = res.count;
+            }
+            Object.assign(engine.sessionMap, sessionTokenMap);
+            if (context && typeof context === 'object') {
+                context.ztdsTokenMap = engine.sessionMap;
+                context.ztdsScrubbedInput = scrubbedInput;
+            }
+            const telemetry = buildAuditTelemetry(sessionTokenMap);
+            const isCritical = telemetry.riskLevel && telemetry.riskLevel.includes('CRITICAL');
+            const tripwireTriggered = Boolean((tripwireOnAnyPii && count > 0) || (tripwireOnCritical && count > 0 && isCritical));
+            return {
+                tripwireTriggered,
+                outputInfo: { scrubbedInput, tokenMap: { ...sessionTokenMap }, tokenCount: count, riskLevel: telemetry.riskLevel, telemetry }
+            };
+        }
+    };
+
+    const outputGuardrail = {
+        name: options.outputGuardrailName || 'PrivacyScrubber ZTDS Output Guardrail',
+        async execute({ agentOutput, context } = {}) {
+            const activeMap = (context && context.ztdsTokenMap) || engine.sessionMap || {};
+            let restoredOutput = agentOutput;
+            let restoredCount = 0;
+            if (typeof agentOutput === 'string') {
+                const res = engine.restore(agentOutput, activeMap);
+                restoredOutput = res.restoredText;
+                restoredCount = res.restoredCount;
+            } else if (agentOutput && typeof agentOutput === 'object') {
+                restoredOutput = restoreObject(agentOutput, activeMap);
+                if (options.mutateInPlace !== false) Object.assign(agentOutput, restoredOutput);
+            }
+            return { tripwireTriggered: false, outputInfo: { restoredOutput, restoredCount } };
+        }
+    };
+
+    return {
+        inputGuardrail,
+        outputGuardrail,
+        inputGuardrails: [inputGuardrail],
+        outputGuardrails: [outputGuardrail],
+        engine
+    };
+}
+
 // Vision & Multimodal exports
 export {
     stripExifMetadata,
@@ -1153,6 +1529,10 @@ export default {
     createStreamTokenRestorer,
     buildStreamReplacer,
     wrapAiStream,
+    wrapGemini,
+    wrapGoogleGenAI,
+    createPrivacyFetch,
+    createOpenAIAgentGuardrails,
     scrubText,
     unscrubText,
     DEVOPS_SECRETS_DETECTOR,