shroud-privacy 2.0.0

package/dist/audit.js

@@ -0,0 +1,127 @@
+/**
+ * Tamper-evident audit log for PII detection events (in-memory only).
+ *
+ * Logs what was detected (category, count, timestamp) WITHOUT storing real values.
+ * Uses HMAC chaining for tamper evidence -- each log entry includes a hash of
+ * the previous entry, so any modification/deletion is detectable.
+ */
+import { createHash, createHmac, randomBytes } from "node:crypto";
+export class AuditLogger {
+    _secret;
+    _sessionId;
+    _maxEntries;
+    _lastHash;
+    _entries;
+    _stats;
+    constructor(secretKey, maxEntries = 200) {
+        this._secret = Buffer.from(secretKey, "utf-8");
+        this._sessionId = createHash("sha256")
+            .update(`${secretKey}:${Date.now()}`)
+            .digest("hex")
+            .slice(0, 12);
+        this._maxEntries = maxEntries;
+        this._lastHash = "0".repeat(64); // Genesis hash
+        this._entries = [];
+        this._stats = {
+            totalObfuscationEvents: 0,
+            totalDeobfuscationEvents: 0,
+            totalEntities: 0,
+            totalReplacements: 0,
+            byCategory: {},
+        };
+    }
+    /** Generate a unique request ID. */
+    static generateRequestId() {
+        return randomBytes(8).toString("hex");
+    }
+    /** Log an obfuscation event (no real values stored). */
+    logObfuscation(entities, textLength, requestId, processingTimeMs) {
+        if (entities.length === 0)
+            return;
+        // Aggregate by category
+        const categories = {};
+        for (const entity of entities) {
+            const cat = entity.category;
+            categories[cat] = (categories[cat] ?? 0) + 1;
+        }
+        this._writeEntry("obfuscation", categories, entities.length, textLength, requestId, processingTimeMs);
+        // Update running stats
+        this._stats.totalObfuscationEvents += 1;
+        this._stats.totalEntities += entities.length;
+        for (const [cat, count] of Object.entries(categories)) {
+            this._stats.byCategory[cat] = (this._stats.byCategory[cat] ?? 0) + count;
+        }
+    }
+    /** Log a deobfuscation event. */
+    logDeobfuscation(replacementsMade, requestId, processingTimeMs) {
+        if (replacementsMade <= 0)
+            return;
+        this._writeEntry("deobfuscation", {}, replacementsMade, 0, requestId, processingTimeMs);
+        // Update running stats
+        this._stats.totalDeobfuscationEvents += 1;
+        this._stats.totalReplacements += replacementsMade;
+    }
+    _writeEntry(eventType, categories, totalEntities, textLength, requestId, processingTimeMs) {
+        const ts = Date.now();
+        const tsIso = new Date(ts).toISOString();
+        // Compute chain hash
+        const sortedCategories = JSON.stringify(categories, Object.keys(categories).sort());
+        const payload = `${this._lastHash}:${ts}:${eventType}:${sortedCategories}`;
+        const chainHash = createHmac("sha256", this._secret)
+            .update(payload)
+            .digest("hex");
+        const entry = {
+            timestamp: ts,
+            timestampIso: tsIso,
+            eventType,
+            sessionId: this._sessionId,
+            requestId: requestId ?? AuditLogger.generateRequestId(),
+            categories,
+            totalEntities,
+            textLength,
+            processingTimeMs: Math.round((processingTimeMs ?? 0) * 100) / 100,
+            chainHash,
+        };
+        this._lastHash = chainHash;
+        // Ring buffer: drop oldest if at capacity
+        if (this._entries.length >= this._maxEntries) {
+            this._entries.shift();
+        }
+        this._entries.push(entry);
+    }
+    /** Return aggregate statistics (safe to expose). */
+    getStats() {
+        return {
+            sessionId: this._sessionId,
+            totalEvents: this._stats.totalObfuscationEvents +
+                this._stats.totalDeobfuscationEvents,
+            totalObfuscationEvents: this._stats.totalObfuscationEvents,
+            totalDeobfuscationEvents: this._stats.totalDeobfuscationEvents,
+            totalEntitiesScrubbed: this._stats.totalEntities,
+            totalReplacementsRestored: this._stats.totalReplacements,
+            byCategory: { ...this._stats.byCategory },
+        };
+    }
+    /**
+     * Verify the integrity of the audit log chain.
+     * Returns { valid, entriesChecked }.
+     */
+    verifyChain() {
+        let prevHash = "0".repeat(64);
+        let count = 0;
+        for (const entry of this._entries) {
+            count += 1;
+            // Recompute expected hash
+            const sortedCategories = JSON.stringify(entry.categories, Object.keys(entry.categories).sort());
+            const payload = `${prevHash}:${entry.timestamp}:${entry.eventType}:${sortedCategories}`;
+            const expected = createHmac("sha256", this._secret)
+                .update(payload)
+                .digest("hex");
+            if (entry.chainHash !== expected) {
+                return { valid: false, entriesChecked: count };
+            }
+            prevHash = entry.chainHash;
+        }
+        return { valid: true, entriesChecked: count };
+    }
+}

package/dist/canary.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Canary token injection for detecting LLM data leakage.
+ *
+ * Injects unique, trackable tokens into obfuscated prompts. These tokens
+ * serve no semantic purpose but can be monitored for leakage -- if a canary
+ * appears in another user's output or in a training data audit, it proves
+ * your data was exposed.
+ */
+export interface CanaryToken {
+    token: string;
+    sessionId: string;
+    timestamp: number;
+    messageIndex: number;
+}
+export declare class CanaryInjector {
+    private readonly _prefix;
+    private readonly _secret;
+    private _sessionId;
+    private _messageCounter;
+    private _tokens;
+    constructor(prefix: string, secretKey: string);
+    get sessionId(): string;
+    /** Inject a canary token into text. Returns modified text. */
+    inject(text: string): string;
+    /** Return all canary tokens injected in this session. */
+    getTokens(): CanaryToken[];
+    /** Check if any known canary tokens appear in given text. */
+    checkLeak(text: string): CanaryToken[];
+    /** Reset for a new session. */
+    reset(): void;
+}

package/dist/canary.js

@@ -0,0 +1,73 @@
+/**
+ * Canary token injection for detecting LLM data leakage.
+ *
+ * Injects unique, trackable tokens into obfuscated prompts. These tokens
+ * serve no semantic purpose but can be monitored for leakage -- if a canary
+ * appears in another user's output or in a training data audit, it proves
+ * your data was exposed.
+ */
+import { createHash } from "node:crypto";
+export class CanaryInjector {
+    _prefix;
+    _secret;
+    _sessionId;
+    _messageCounter;
+    _tokens;
+    constructor(prefix, secretKey) {
+        this._prefix = prefix;
+        this._secret = secretKey;
+        this._sessionId = createHash("sha256")
+            .update(`${secretKey}:${Date.now()}`)
+            .digest("hex")
+            .slice(0, 12);
+        this._messageCounter = 0;
+        this._tokens = [];
+    }
+    get sessionId() {
+        return this._sessionId;
+    }
+    /** Inject a canary token into text. Returns modified text. */
+    inject(text) {
+        this._messageCounter += 1;
+        const ts = Date.now();
+        // Generate unique token
+        const raw = `${this._sessionId}:${this._messageCounter}:${ts}`;
+        const tokenHash = createHash("sha256")
+            .update(this._secret + raw)
+            .digest("hex")
+            .slice(0, 16);
+        const token = `${this._prefix}-${tokenHash}`;
+        const canary = {
+            token,
+            sessionId: this._sessionId,
+            timestamp: ts,
+            messageIndex: this._messageCounter,
+        };
+        this._tokens.push(canary);
+        // Inject as a non-semantic comment at the end of the text
+        return `${text}\n<!-- ${token} -->`;
+    }
+    /** Return all canary tokens injected in this session. */
+    getTokens() {
+        return [...this._tokens];
+    }
+    /** Check if any known canary tokens appear in given text. */
+    checkLeak(text) {
+        const leaked = [];
+        for (const canary of this._tokens) {
+            if (text.includes(canary.token)) {
+                leaked.push(canary);
+            }
+        }
+        return leaked;
+    }
+    /** Reset for a new session. */
+    reset() {
+        this._sessionId = createHash("sha256")
+            .update(`${this._secret}:${Date.now()}`)
+            .digest("hex")
+            .slice(0, 12);
+        this._messageCounter = 0;
+        this._tokens = [];
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Configuration resolver for the Shroud plugin.
+ *
+ * Merges plugin config with environment variables and provides defaults.
+ */
+import { ShroudConfig } from "./types.js";
+/**
+ * Resolve a fully populated ShroudConfig from optional plugin config
+ * and environment variables.
+ *
+ * Priority: env vars > pluginConfig > defaults.
+ */
+export declare function resolveConfig(pluginConfig?: unknown): ShroudConfig;
+/** Validation issue severity. */
+export type ConfigSeverity = "error" | "warning" | "info";
+/** A single config validation issue. */
+export interface ConfigIssue {
+    severity: ConfigSeverity;
+    field: string;
+    message: string;
+}
+/**
+ * Validate a resolved ShroudConfig and return actionable issues.
+ *
+ * Does NOT throw — callers decide how to handle warnings vs errors.
+ */
+export declare function validateConfig(config: ShroudConfig): ConfigIssue[];

package/dist/config.js

@@ -0,0 +1,123 @@
+/**
+ * Configuration resolver for the Shroud plugin.
+ *
+ * Merges plugin config with environment variables and provides defaults.
+ */
+import { randomBytes } from "node:crypto";
+/**
+ * Resolve a fully populated ShroudConfig from optional plugin config
+ * and environment variables.
+ *
+ * Priority: env vars > pluginConfig > defaults.
+ */
+export function resolveConfig(pluginConfig) {
+    const raw = pluginConfig != null && typeof pluginConfig === "object"
+        ? pluginConfig
+        : {};
+    // Env var overrides
+    const envSecretKey = process.env.SHROUD_SECRET_KEY;
+    const envSalt = process.env.SHROUD_PERSISTENT_SALT;
+    let secretKey = envSecretKey ??
+        (typeof raw.secretKey === "string" ? raw.secretKey : "");
+    // Auto-generate if missing
+    if (!secretKey) {
+        secretKey = randomBytes(32).toString("hex");
+    }
+    // Warn if too short (but don't throw -- let the plugin still load)
+    if (secretKey.length < 16) {
+        console.warn("[shroud] WARNING: secretKey is shorter than 16 characters. " +
+            "This weakens mapping security. Set SHROUD_SECRET_KEY or pass a longer key.");
+    }
+    const persistentSalt = envSalt ??
+        (typeof raw.persistentSalt === "string" ? raw.persistentSalt : "");
+    // Validate redactionLevel
+    const redactionRaw = raw.redactionLevel;
+    const validLevels = ["full", "masked", "stats"];
+    const redactionLevel = typeof redactionRaw === "string" && validLevels.includes(redactionRaw)
+        ? redactionRaw
+        : "full";
+    const config = {
+        secretKey,
+        persistentSalt,
+        minConfidence: typeof raw.minConfidence === "number" ? raw.minConfidence : 0.0,
+        allowlist: Array.isArray(raw.allowlist)
+            ? raw.allowlist
+            : [],
+        denylist: Array.isArray(raw.denylist)
+            ? raw.denylist
+            : [],
+        canaryEnabled: typeof raw.canaryEnabled === "boolean" ? raw.canaryEnabled : false,
+        canaryPrefix: typeof raw.canaryPrefix === "string"
+            ? raw.canaryPrefix
+            : "SHROUD-CANARY",
+        auditEnabled: typeof raw.auditEnabled === "boolean" ? raw.auditEnabled : false,
+        logMappings: typeof raw.logMappings === "boolean" ? raw.logMappings : false,
+        customPatterns: Array.isArray(raw.customPatterns)
+            ? raw.customPatterns
+            : [],
+        // Verbose audit logging
+        verboseLogging: typeof raw.verboseLogging === "boolean" ? raw.verboseLogging : false,
+        auditLogFormat: raw.auditLogFormat === "json" ? "json" : "human",
+        auditIncludeProofHashes: typeof raw.auditIncludeProofHashes === "boolean"
+            ? raw.auditIncludeProofHashes
+            : false,
+        auditHashSalt: typeof raw.auditHashSalt === "string" ? raw.auditHashSalt : "",
+        auditHashTruncate: typeof raw.auditHashTruncate === "number" ? raw.auditHashTruncate : 12,
+        auditMaxFakesSample: typeof raw.auditMaxFakesSample === "number"
+            ? raw.auditMaxFakesSample
+            : 0,
+        detectorOverrides: raw.detectorOverrides != null && typeof raw.detectorOverrides === "object"
+            ? raw.detectorOverrides
+            : {},
+        // Tool chain depth
+        maxToolDepth: typeof raw.maxToolDepth === "number" ? raw.maxToolDepth : 10,
+        // Redaction level
+        redactionLevel,
+        // Dry-run mode
+        dryRun: typeof raw.dryRun === "boolean" ? raw.dryRun : false,
+        // LRU store eviction (0 = unlimited)
+        maxStoreMappings: typeof raw.maxStoreMappings === "number" ? raw.maxStoreMappings : 0,
+    };
+    return config;
+}
+/**
+ * Validate a resolved ShroudConfig and return actionable issues.
+ *
+ * Does NOT throw — callers decide how to handle warnings vs errors.
+ */
+export function validateConfig(config) {
+    const issues = [];
+    // Secret key checks
+    if (config.secretKey.length < 16) {
+        issues.push({ severity: "error", field: "secretKey", message: "secretKey is shorter than 16 chars — mappings are weak. Set SHROUD_SECRET_KEY." });
+    }
+    else if (config.secretKey.length < 32) {
+        issues.push({ severity: "warning", field: "secretKey", message: "secretKey is shorter than 32 chars — consider a longer key for production." });
+    }
+    // minConfidence range
+    if (config.minConfidence < 0 || config.minConfidence > 1) {
+        issues.push({ severity: "error", field: "minConfidence", message: `minConfidence=${config.minConfidence} is outside [0,1]. Set to a value between 0 and 1.` });
+    }
+    // maxStoreMappings negative
+    if (config.maxStoreMappings < 0) {
+        issues.push({ severity: "error", field: "maxStoreMappings", message: "maxStoreMappings must be >= 0 (0 = unlimited)." });
+    }
+    // dryRun informational
+    if (config.dryRun) {
+        issues.push({ severity: "info", field: "dryRun", message: "Dry-run mode is active — entities are detected but text is NOT obfuscated." });
+    }
+    // Custom patterns with invalid regex
+    for (const cp of config.customPatterns) {
+        try {
+            new RegExp(cp.pattern);
+        }
+        catch {
+            issues.push({ severity: "error", field: "customPatterns", message: `Custom pattern "${cp.name}" has invalid regex: ${cp.pattern}` });
+        }
+    }
+    // Detector overrides referencing unknown rules (info-level since we can't check at config time)
+    if (Object.keys(config.detectorOverrides).length > 0) {
+        issues.push({ severity: "info", field: "detectorOverrides", message: `${Object.keys(config.detectorOverrides).length} detector override(s) configured.` });
+    }
+    return issues;
+}

package/dist/detectors/base.d.ts

@@ -0,0 +1,8 @@
+/** Base detector interface. */
+import { DetectedEntity } from "../types.js";
+export interface BaseDetector {
+    readonly name: string;
+    detect(text: string): DetectedEntity[];
+    /** Optional reset for stateful detectors. */
+    reset?(): void;
+}

package/dist/detectors/base.js

@@ -0,0 +1,2 @@
+/** Base detector interface. */
+export {};

package/dist/detectors/code.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Code-aware detector that finds sensitive data inside string literals and comments.
+ *
+ * Scans source code for string literals and comments across common languages,
+ * then runs the standard regex detector on the extracted text to find PII
+ * that would otherwise be missed by scanning raw code.
+ */
+import { DetectedEntity } from "../types.js";
+import { BaseDetector } from "./base.js";
+import { RegexDetector } from "./regex.js";
+/**
+ * Detects sensitive data embedded in source code strings and comments.
+ *
+ * Extracts string literals and comments from code, then runs PII detection
+ * on the extracted text. Entity positions are mapped back to the original
+ * source positions.
+ */
+export declare class CodeDetector implements BaseDetector {
+    readonly name = "code";
+    private _inner;
+    constructor(inner?: RegexDetector);
+    detect(text: string): DetectedEntity[];
+    /** Extract string literals and comments from code. */
+    private _extractSpans;
+}

package/dist/detectors/code.js

@@ -0,0 +1,144 @@
+/**
+ * Code-aware detector that finds sensitive data inside string literals and comments.
+ *
+ * Scans source code for string literals and comments across common languages,
+ * then runs the standard regex detector on the extracted text to find PII
+ * that would otherwise be missed by scanning raw code.
+ */
+import { RegexDetector } from "./regex.js";
+/** Language-agnostic patterns for extracting strings and comments. */
+const SPAN_PATTERNS = [
+    // Triple-quoted strings (Python, etc.)
+    /"""[\s\S]*?"""/g,
+    /'''[\s\S]*?'''/g,
+    // Double-quoted strings
+    /"(?:[^"\\]|\\.)*"/g,
+    // Single-quoted strings
+    /'(?:[^'\\]|\\.)*'/g,
+    // Backtick strings (JS/Go/etc.)
+    /`(?:[^`\\]|\\.)*`/g,
+    // Line comments (C-style, Python, Ruby, Shell)
+    /\/\/[^\n]*/g,
+    /#[^\n]*/g,
+    // Block comments
+    /\/\*[\s\S]*?\*\//g,
+];
+/** Patterns that are purely code constructs with no data (skip these). */
+const CODE_NOISE = new RegExp("^[\\s\"'`#/\\*]*" +
+    "(?:import |from |require\\(|use |include |" +
+    "package |module |class |def |func |fn |" +
+    "return |const |let |var |type |interface )" +
+    "[^@]*$");
+const CODE_INDICATORS = [
+    "def ", "class ", "function ", "import ", "from ", "require(",
+    "const ", "let ", "var ", "func ", "fn ", "pub ", "private ",
+    "return ", "if (", "for (", "while (", "package ", "module ",
+    "#!/", "# -*- coding", "use strict", "pragma ",
+    "SELECT ", "INSERT ", "CREATE TABLE",
+];
+/** Heuristic: does this text look like source code? */
+function looksLikeCode(text) {
+    const lines = text.split("\n");
+    if (lines.length < 3) {
+        return false;
+    }
+    let score = 0;
+    for (const indicator of CODE_INDICATORS) {
+        if (text.includes(indicator)) {
+            score++;
+        }
+    }
+    // Also check for common syntax patterns
+    if (/[{};]\s*$/m.test(text)) {
+        score++;
+    }
+    if (/^\s*(def|class|func|fn)\s+\w+/m.test(text)) {
+        score++;
+    }
+    return score >= 2;
+}
+/**
+ * Detects sensitive data embedded in source code strings and comments.
+ *
+ * Extracts string literals and comments from code, then runs PII detection
+ * on the extracted text. Entity positions are mapped back to the original
+ * source positions.
+ */
+export class CodeDetector {
+    name = "code";
+    _inner;
+    constructor(inner) {
+        this._inner = inner ?? new RegexDetector();
+    }
+    detect(text) {
+        // Only run if the text looks like code
+        if (!looksLikeCode(text)) {
+            return [];
+        }
+        const spans = this._extractSpans(text);
+        const entities = [];
+        const seenSpans = new Set();
+        for (const span of spans) {
+            const innerText = span.text;
+            const innerOffset = span.start;
+            // Skip spans that look like pure code constructs
+            if (CODE_NOISE.test(innerText)) {
+                continue;
+            }
+            // Run PII detection on the inner text
+            const innerEntities = this._inner.detect(innerText);
+            for (const entity of innerEntities) {
+                // Map positions back to original text
+                const absStart = innerOffset + entity.start;
+                const absEnd = innerOffset + entity.end;
+                const spanKey = `${absStart}:${absEnd}`;
+                if (seenSpans.has(spanKey)) {
+                    continue;
+                }
+                seenSpans.add(spanKey);
+                entities.push({
+                    value: entity.value,
+                    start: absStart,
+                    end: absEnd,
+                    category: entity.category,
+                    confidence: entity.confidence * 0.9, // Slightly lower since it's inside code
+                    detector: `code:${entity.detector}`,
+                });
+            }
+        }
+        entities.sort((a, b) => a.start - b.start);
+        return entities;
+    }
+    /** Extract string literals and comments from code. */
+    _extractSpans(text) {
+        const spans = [];
+        const covered = new Set();
+        for (const pattern of SPAN_PATTERNS) {
+            pattern.lastIndex = 0;
+            for (const match of text.matchAll(pattern)) {
+                const start = match.index;
+                const end = start + match[0].length;
+                // Skip if overlapping with already-found span
+                let overlaps = false;
+                for (let i = start; i < end; i++) {
+                    if (covered.has(i)) {
+                        overlaps = true;
+                        break;
+                    }
+                }
+                if (overlaps) {
+                    continue;
+                }
+                for (let i = start; i < end; i++) {
+                    covered.add(i);
+                }
+                const kind = match[0].startsWith("/") || match[0].startsWith("#")
+                    ? "comment"
+                    : "string";
+                spans.push({ text: match[0], start, end, kind });
+            }
+        }
+        spans.sort((a, b) => a.start - b.start);
+        return spans;
+    }
+}

package/dist/detectors/context.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Context-aware detection enhancements.
+ *
+ * Wraps another detector and applies post-detection intelligence:
+ * 1. Context-aware confidence boosting (config keyword density)
+ * 3. Proximity-based PII clustering (nearby entities boost each other)
+ * 4. Config-block hostname extraction (hostname X -> detect bare X)
+ * 9. Learned entity propagation (cross-invocation memory)
+ * 10. Confidence decay by frequency (common words lose confidence)
+ */
+import { DetectedEntity } from "../types.js";
+import { BaseDetector } from "./base.js";
+export declare class ContextDetector implements BaseDetector {
+    readonly name = "context";
+    private _inner;
+    /** Feature 9: Learned entities from previous invocations. */
+    private _learnedEntities;
+    constructor(inner: BaseDetector);
+    detect(text: string): DetectedEntity[];
+    /** Reset learned entities (called on Obfuscator.reset()). */
+    reset(): void;
+    /** Get count of learned entities. */
+    get learnedCount(): number;
+    private _boostFromContext;
+    private _splitBlocks;
+    private _boostByProximity;
+    private _extractAndPropagateHostnames;
+    private _injectLearnedEntities;
+    private _learnEntities;
+    private _decayCommonWords;
+}