shroud-privacy 2.0.0

package/dist/redaction.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Redaction level formatter.
+ *
+ * Three modes:
+ * - full:   fake values (current behavior, default)
+ * - masked: partial masking (first 2 + *** + last 2)
+ * - stats:  category placeholders like [HOSTNAME-1]
+ */
+import { Category } from "./types.js";
+export type RedactionLevel = "full" | "masked" | "stats";
+export declare class RedactionFormatter {
+    private _counters;
+    /**
+     * Format a replacement value according to the redaction level.
+     *
+     * @param real     The real sensitive value
+     * @param fake     The generated fake value (used in 'full' mode)
+     * @param category The entity category
+     * @param level    The redaction level
+     */
+    format(real: string, fake: string, category: Category, level: RedactionLevel): string;
+    /** Reset counters (call between requests if needed). */
+    resetCounters(): void;
+    private _mask;
+    private _placeholder;
+}

package/dist/redaction.js

@@ -0,0 +1,76 @@
+/**
+ * Redaction level formatter.
+ *
+ * Three modes:
+ * - full:   fake values (current behavior, default)
+ * - masked: partial masking (first 2 + *** + last 2)
+ * - stats:  category placeholders like [HOSTNAME-1]
+ */
+import { Category } from "./types.js";
+export class RedactionFormatter {
+    _counters = new Map();
+    /**
+     * Format a replacement value according to the redaction level.
+     *
+     * @param real     The real sensitive value
+     * @param fake     The generated fake value (used in 'full' mode)
+     * @param category The entity category
+     * @param level    The redaction level
+     */
+    format(real, fake, category, level) {
+        switch (level) {
+            case "full":
+                return fake;
+            case "masked":
+                return this._mask(real, category);
+            case "stats":
+                return this._placeholder(category);
+        }
+    }
+    /** Reset counters (call between requests if needed). */
+    resetCounters() {
+        this._counters.clear();
+    }
+    _mask(value, category) {
+        const len = value.length;
+        // Short values get fully masked
+        if (len <= 4) {
+            return "***";
+        }
+        // Category-aware masking
+        switch (category) {
+            case Category.EMAIL: {
+                const at = value.indexOf("@");
+                if (at > 0) {
+                    return value[0] + "***@***" + value.slice(value.lastIndexOf("."));
+                }
+                break;
+            }
+            case Category.PHONE:
+                // Show last 4 digits
+                return "***" + value.slice(-4);
+            case Category.CREDIT_CARD:
+                // Show last 4 digits
+                return "****-****-****-" + value.slice(-4);
+            case Category.SSN:
+                return "***-**-" + value.slice(-4);
+            case Category.IP_ADDRESS:
+                // Mask last two octets
+                if (value.includes(".")) {
+                    const parts = value.split(".");
+                    return parts[0] + "." + parts[1] + ".*.*";
+                }
+                break;
+        }
+        // Default: show first 2 and last 2
+        if (len <= 6) {
+            return value[0] + "***" + value[len - 1];
+        }
+        return value.slice(0, 2) + "***" + value.slice(-2);
+    }
+    _placeholder(category) {
+        const count = (this._counters.get(category) ?? 0) + 1;
+        this._counters.set(category, count);
+        return `[${category.toUpperCase()}-${count}]`;
+    }
+}

package/dist/store.d.ts

@@ -0,0 +1,40 @@
+/** Mapping store interface and in-memory implementation. */
+import { Category } from "./types.js";
+/** Abstract store interface for real↔fake mappings. */
+export interface MappingStore {
+    put(real: string, fake: string, category: Category): void;
+    getFake(real: string): string | undefined;
+    getReal(fake: string): string | undefined;
+    getCategory(real: string): Category | undefined;
+    allMappings(): Map<string, string>;
+    size(): number;
+    clear(): void;
+}
+/** Serialized form of a mapping store — used for session export/import. */
+export interface SerializedStore {
+    mappings: [string, string, string][];
+    salt: string;
+    tenantId?: string;
+    exportedAt: string;
+}
+export declare class MemoryStore implements MappingStore {
+    private _realToFake;
+    private _fakeToReal;
+    private _categories;
+    /** Insertion-order list for LRU eviction (oldest first). */
+    private _insertionOrder;
+    /** Max store size (0 = unlimited). QW10. */
+    private _maxSize;
+    constructor(maxSize?: number);
+    put(real: string, fake: string, category: Category): void;
+    getFake(real: string): string | undefined;
+    getReal(fake: string): string | undefined;
+    getCategory(real: string): Category | undefined;
+    allMappings(): Map<string, string>;
+    size(): number;
+    clear(): void;
+    /** Export all mappings for session handoff. */
+    export(salt: string, tenantId?: string): SerializedStore;
+    /** Import mappings from a session export. */
+    import(data: SerializedStore): void;
+}

package/dist/store.js

@@ -0,0 +1,79 @@
+/** Mapping store interface and in-memory implementation. */
+import { Category } from "./types.js";
+export class MemoryStore {
+    _realToFake = new Map();
+    _fakeToReal = new Map();
+    _categories = new Map();
+    /** Insertion-order list for LRU eviction (oldest first). */
+    _insertionOrder = [];
+    /** Max store size (0 = unlimited). QW10. */
+    _maxSize;
+    constructor(maxSize = 0) {
+        this._maxSize = maxSize;
+    }
+    put(real, fake, category) {
+        // If already present, update in place (no eviction needed)
+        if (this._realToFake.has(real)) {
+            this._realToFake.set(real, fake);
+            this._fakeToReal.set(fake, real);
+            this._categories.set(real, category);
+            return;
+        }
+        // QW10: Evict oldest entries if at capacity
+        if (this._maxSize > 0) {
+            while (this._insertionOrder.length >= this._maxSize) {
+                const oldest = this._insertionOrder.shift();
+                const oldFake = this._realToFake.get(oldest);
+                this._realToFake.delete(oldest);
+                if (oldFake !== undefined)
+                    this._fakeToReal.delete(oldFake);
+                this._categories.delete(oldest);
+            }
+        }
+        this._realToFake.set(real, fake);
+        this._fakeToReal.set(fake, real);
+        this._categories.set(real, category);
+        this._insertionOrder.push(real);
+    }
+    getFake(real) {
+        return this._realToFake.get(real);
+    }
+    getReal(fake) {
+        return this._fakeToReal.get(fake);
+    }
+    getCategory(real) {
+        return this._categories.get(real);
+    }
+    allMappings() {
+        return new Map(this._realToFake);
+    }
+    size() {
+        return this._realToFake.size;
+    }
+    clear() {
+        this._realToFake.clear();
+        this._fakeToReal.clear();
+        this._categories.clear();
+        this._insertionOrder = [];
+    }
+    /** Export all mappings for session handoff. */
+    export(salt, tenantId) {
+        const mappings = [];
+        for (const [real, fake] of this._realToFake) {
+            const cat = this._categories.get(real) ?? Category.CUSTOM;
+            mappings.push([real, fake, cat]);
+        }
+        return {
+            mappings,
+            salt,
+            tenantId,
+            exportedAt: new Date().toISOString(),
+        };
+    }
+    /** Import mappings from a session export. */
+    import(data) {
+        for (const [real, fake, cat] of data.mappings) {
+            this.put(real, fake, cat);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+/** Core types for the Shroud OpenClaw plugin. */
+import type { RedactionLevel } from "./redaction.js";
+/** Categories of sensitive information. */
+export declare enum Category {
+    PERSON_NAME = "person_name",
+    EMAIL = "email",
+    PHONE = "phone",
+    IP_ADDRESS = "ip_address",
+    API_KEY = "api_key",
+    URL = "url",
+    ORG_NAME = "org_name",
+    LOCATION = "location",
+    FILE_PATH = "file_path",
+    CREDIT_CARD = "credit_card",
+    SSN = "ssn",
+    MAC_ADDRESS = "mac_address",
+    HOSTNAME = "hostname",
+    SNMP_COMMUNITY = "snmp_community",
+    BGP_ASN = "bgp_asn",
+    NETWORK_CREDENTIAL = "network_credential",
+    VLAN_ID = "vlan_id",
+    INTERFACE_DESC = "interface_desc",
+    ROUTE_MAP = "route_map",
+    OSPF_ID = "ospf_id",
+    ACL_NAME = "acl_name",
+    IBAN = "iban",
+    NATIONAL_ID = "national_id",
+    JWT = "jwt",
+    ICS_IDENTIFIER = "ics_identifier",
+    GPS_COORDINATE = "gps_coordinate",
+    CERTIFICATE = "certificate",
+    CUSTOM = "custom"
+}
+/** A detected sensitive entity in text. */
+export interface DetectedEntity {
+    value: string;
+    start: number;
+    end: number;
+    category: Category;
+    confidence: number;
+    detector: string;
+}
+/** Result of obfuscating text. */
+export interface ObfuscationResult {
+    original: string;
+    obfuscated: string;
+    entities: DetectedEntity[];
+    mappingsUsed: Record<string, string>;
+    /** Filtering stats — how many entities were skipped and why. */
+    filterStats?: FilterStats;
+}
+/** Breakdown of skipped/filtered entities during obfuscation. */
+export interface FilterStats {
+    /** Total entities detected before filtering. */
+    totalDetected: number;
+    /** Entities that passed filtering and were replaced (or would be in dryRun). */
+    replaced: number;
+    /** Entities skipped because confidence < minConfidence. */
+    belowThreshold: number;
+    /** Entities skipped by allowlist. */
+    allowlisted: number;
+    /** Entities skipped because they are doc/example values. */
+    docExamples: number;
+    /** Entities skipped because they are already-known fakes. */
+    alreadyObfuscated: number;
+}
+/** Configuration for the Shroud plugin. */
+export interface ShroudConfig {
+    secretKey: string;
+    persistentSalt: string;
+    minConfidence: number;
+    allowlist: string[];
+    denylist: string[];
+    canaryEnabled: boolean;
+    canaryPrefix: string;
+    auditEnabled: boolean;
+    logMappings: boolean;
+    customPatterns: Array<{
+        name: string;
+        pattern: string;
+        category?: string;
+    }>;
+    verboseLogging: boolean;
+    auditLogFormat: "human" | "json";
+    auditIncludeProofHashes: boolean;
+    auditHashSalt: string;
+    auditHashTruncate: number;
+    auditMaxFakesSample: number;
+    detectorOverrides: Record<string, {
+        enabled?: boolean;
+        confidence?: number;
+    }>;
+    /** Tool chain depth awareness — max depth before warning. */
+    maxToolDepth: number;
+    /** Redaction levels — 'full' | 'masked' | 'stats'. */
+    redactionLevel: RedactionLevel;
+    /** Dry-run mode: detect entities but don't replace them. */
+    dryRun: boolean;
+    /** Max mapping store size; oldest entries evicted when exceeded. 0 = unlimited. */
+    maxStoreMappings: number;
+}

package/dist/types.js

@@ -0,0 +1,35 @@
+/** Core types for the Shroud OpenClaw plugin. */
+/** Categories of sensitive information. */
+export var Category;
+(function (Category) {
+    Category["PERSON_NAME"] = "person_name";
+    Category["EMAIL"] = "email";
+    Category["PHONE"] = "phone";
+    Category["IP_ADDRESS"] = "ip_address";
+    Category["API_KEY"] = "api_key";
+    Category["URL"] = "url";
+    Category["ORG_NAME"] = "org_name";
+    Category["LOCATION"] = "location";
+    Category["FILE_PATH"] = "file_path";
+    Category["CREDIT_CARD"] = "credit_card";
+    Category["SSN"] = "ssn";
+    Category["MAC_ADDRESS"] = "mac_address";
+    Category["HOSTNAME"] = "hostname";
+    Category["SNMP_COMMUNITY"] = "snmp_community";
+    Category["BGP_ASN"] = "bgp_asn";
+    Category["NETWORK_CREDENTIAL"] = "network_credential";
+    // Network infrastructure identifiers
+    Category["VLAN_ID"] = "vlan_id";
+    Category["INTERFACE_DESC"] = "interface_desc";
+    Category["ROUTE_MAP"] = "route_map";
+    Category["OSPF_ID"] = "ospf_id";
+    Category["ACL_NAME"] = "acl_name";
+    // Regulated / enterprise categories
+    Category["IBAN"] = "iban";
+    Category["NATIONAL_ID"] = "national_id";
+    Category["JWT"] = "jwt";
+    Category["ICS_IDENTIFIER"] = "ics_identifier";
+    Category["GPS_COORDINATE"] = "gps_coordinate";
+    Category["CERTIFICATE"] = "certificate";
+    Category["CUSTOM"] = "custom";
+})(Category || (Category = {}));