shroud-privacy 2.3.1 → 2.5.0

package/README.md

@@ -17,7 +17,7 @@
   <a href="CHANGELOG.md">Changelog</a>
 </p>
 
-> Apache 2.0 &middot; Zero runtime dependencies &middot; Anthropic + OpenAI + Google supported &middot; Prompt-caching friendly &middot; Works with [OpenClaw](https://openclaw.ai) or any agent via [APP](#agent-privacy-protocol-app)
+> Apache 2.0 &middot; Zero runtime dependencies &middot; Anthropic + OpenAI + Google supported &middot; Prompt-caching friendly &middot; Works with [OpenClaw](https://openclaw.ai), [Hermes Agent](https://github.com/nousresearch/hermes-agent), or any agent via [APP](#agent-privacy-protocol-app)
 
 ---
 
@@ -32,7 +32,7 @@ Frontier LLMs are transformative for infrastructure operations — network troub
 - **Customer PII** — emails, phone numbers, national IDs, credit cards, physical addresses
 - **Internal URLs** — wiki pages, Jira tickets, admin portals, API endpoints
 
-Shroud sits between your agent and the LLM. It detects all of the above (100+ entity types), replaces each with a deterministic format-preserving fake, and reverses the mapping on the way back. The LLM reasons over realistic-looking data. Your real infrastructure stays private.
+Shroud sits between your agent and the LLM. It detects all of the above (130+ entity types), replaces each with a deterministic format-preserving fake, and reverses the mapping on the way back. The LLM reasons over realistic-looking data. Your real infrastructure stays private.
 
 ### Who needs this
 
@@ -56,7 +56,7 @@ Shroud does not guarantee compliance — regex-based detection has limitations (
 
 ## What it does
 
-1. **Detects** 100+ entity types: emails, IPs, phones, API keys, hostnames, SNMP communities, BGP ASNs, credit cards, SSNs, file paths, URLs, person/org/location names, VLANs, route-maps, ACLs, OSPF IDs, IBANs, JWTs, PEM certs, GPS coordinates, ICS/SCADA identifiers, vendor-specific secrets (Cisco, Juniper, Palo Alto, Check Point, Fortinet, F5, Arista), and custom regex patterns.
+1. **Detects** 130+ entity types: emails, IPs, phones, API keys, hostnames, SNMP communities, BGP ASNs, credit cards, SSNs, file paths, URLs, person/org/location names, VLANs, route-maps, ACLs, OSPF IDs, IBANs, JWTs, PEM certs, GPS coordinates, ICS/SCADA identifiers, dates of birth, medical record numbers (MRN/NPI/DEA), bank accounts (routing/sort code/SWIFT), tax IDs (EIN/UTR), passport numbers, driver's licenses, court case/docket/patent numbers, cryptocurrency addresses (Ethereum/Bitcoin), AWS ARNs, vendor-specific secrets (Cisco, Juniper, Palo Alto, Check Point, Fortinet, F5, Arista), and custom regex patterns.
 2. **Replaces** each value with a deterministic fake (same input + key = same fake every time). Fakes are format-preserving: IPv4 stays in CGNAT range (`100.64.0.0/10`), IPv6 uses ULA range (`fd00::/8`), emails keep `@domain` structure, credit cards pass Luhn, etc.
 3. **Passes through public URLs** — external URLs (arxiv.org, docs.stripe.com, etc.) are not obfuscated. Shroud resolves FQDNs via DNS: public IPs pass through, RFC 1918 / NXDOMAIN / internal IPs are obfuscated. Well-known platforms (GitHub, YouTube, Wikipedia, etc.) are always passed through.
 4. **Deobfuscates** LLM responses and tool parameters so the user sees real values and tools receive real arguments.
@@ -102,6 +102,23 @@ openclaw plugins install shroud-privacy
 
 Configure in `~/.openclaw/openclaw.json` under `plugins.entries."shroud-privacy".config`. No OpenClaw file modifications needed — Shroud uses runtime interception only.
 
+### Hermes Agent
+
+```bash
+hermes plugins install wkeything/shroud
+```
+
+That's it. The plugin auto-builds on first session start (requires Node.js). All LLM traffic is obfuscated transparently — no Hermes configuration changes needed.
+
+Per-tool field scoping is enabled by default, reducing false positives on structural fields (IDs, hashes, timestamps). Works with all Hermes-supported providers (OpenRouter, Anthropic, OpenAI, z.ai, local models).
+
+**Config-as-code** is supported — edit `~/.shroud/shroud.config.json` to customize detection rules, field scoping, and confidence thresholds. Changes hot-reload within 2 seconds, no restart needed. The config file is shared with OpenClaw — edits apply to both platforms.
+
+Verify after a conversation:
+```bash
+cat ~/.hermes/shroud-stats.json | python3 -m json.tool
+```
+
 ### Any agent (via APP)
 
 The **Agent Privacy Protocol** (APP) lets any AI agent add privacy and infrastructure protection — no OpenClaw required. Shroud ships with an APP server and a Python client.
@@ -230,9 +247,37 @@ Out of the box, Shroud:
 | `redactionLevel` | `"full"` \| `"masked"` \| `"stats"` | `"full"` | Output mode: fake values, partial masking, or category placeholders |
 | `dryRun` | boolean | `false` | Detect entities but don't replace (testing mode) |
 | `maxStoreMappings` | number | `0` | Max mapping store size with LRU eviction (0 = unlimited) |
+| `fieldScoping` | object | — | Per-tool field scoping and per-agent category exemptions (see below) |
 
 > **Env var overrides:** `SHROUD_SECRET_KEY` and `SHROUD_PERSISTENT_SALT` override their respective config keys (priority: env var > plugin config > default).
 
+### Per-tool field scoping
+
+By default Shroud scans every string field in every message. This catches everything but produces false positives — file paths agents need, config values, UUIDs matching credit card patterns.
+
+Field scoping narrows what gets scanned. Add a `fieldScoping` block to `shroud.config.json`:
+
+```jsonc
+{
+  "fieldScoping": {
+    "toolFields": {
+      "Read":     { "scanFields": ["content", "text"] },
+      "Bash":     { "scanFields": ["output", "stdout", "stderr"] },
+      "gmail_*":  { "scanFields": ["subject", "body", "snippet", "from", "to"] },
+      "github_*": { "scanFields": ["title", "body", "description", "comment"] }
+    },
+    "neverScanFields": ["id", "created_at", "updated_at", "sha", "hash", "ref", "type", "status"],
+    "defaultScanFields": []
+  }
+}
+```
+
+**`toolFields`** maps tool name patterns (wildcards `*` `?` supported) to the fields that should be scanned in their results. Unmatched tools fall back to `defaultScanFields` — set it to `[]` to scan everything for unknown tools (safe default).
+
+**`neverScanFields`** lists structural fields that never contain user-generated content. These are skipped regardless of tool.
+
+Hot-reloadable. No config = scan everything (backward compatible).
+
 ### Detection rules as code (hot-reload)
 
 Shroud auto-generates a JSONC config file on first run containing every built-in detection rule:
@@ -409,7 +454,7 @@ shroud-stats --test "Contact john@acme.com"   # test detection
 
 ## Entity categories
 
-`person_name`, `email`, `phone`, `ip_address`, `api_key`, `url`, `org_name`, `location`, `file_path`, `credit_card`, `ssn`, `mac_address`, `hostname`, `snmp_community`, `bgp_asn`, `network_credential`, `vlan_id`, `interface_desc`, `route_map`, `ospf_id`, `acl_name`, `iban`, `national_id`, `jwt`, `ics_identifier`, `gps_coordinate`, `certificate`, `custom`
+`person_name`, `email`, `phone`, `ip_address`, `api_key`, `url`, `org_name`, `location`, `file_path`, `credit_card`, `ssn`, `mac_address`, `hostname`, `snmp_community`, `bgp_asn`, `network_credential`, `vlan_id`, `interface_desc`, `route_map`, `ospf_id`, `acl_name`, `iban`, `national_id`, `jwt`, `ics_identifier`, `gps_coordinate`, `certificate`, `date_of_birth`, `medical_record_number`, `bank_account_number`, `tax_id`, `passport_number`, `drivers_license`, `case_number`, `cryptocurrency_address`, `aws_arn`, `custom`
 
 ---
 

package/dist/config-manager.js

@@ -154,6 +154,19 @@ export class ConfigManager {
             "  // Edit rules here. Changes hot-reload within 2 seconds (no restart needed).",
             "  // Priority: env vars > this file > plugin config > defaults.",
             "  //",
+            "  // Per-tool field scoping — controls which fields get scanned for PII.",
+            "  // Reduces false positives from structural fields (IDs, hashes, timestamps).",
+            '  "fieldScoping": {',
+            '    "toolFields": {',
+            '      "Read":     { "scanFields": ["content", "text"] },',
+            '      "read":     { "scanFields": ["content", "text"] },',
+            '      "Bash":     { "scanFields": ["output", "stdout", "stderr"] },',
+            '      "exec":     { "scanFields": ["output", "stdout", "stderr"] }',
+            "    },",
+            '    "neverScanFields": ["id", "created_at", "updated_at", "sha", "hash", "ref", "type", "status", "state", "mode"],',
+            '    "defaultScanFields": []',
+            "  },",
+            "  //",
             "  // Rule format:",
             '  //   "rule_name": {',
             '  //     "pattern": "regex string",     // override or define the detection regex',

package/dist/config.js

@@ -82,6 +82,31 @@ export function resolveConfig(pluginConfig) {
         dryRun: typeof raw.dryRun === "boolean" ? raw.dryRun : false,
         // LRU store eviction (0 = unlimited)
         maxStoreMappings: typeof raw.maxStoreMappings === "number" ? raw.maxStoreMappings : 0,
+        // Field scoping (optional, backward compatible)
+        fieldScoping: (() => {
+            const fs = raw.fieldScoping;
+            if (!fs || typeof fs !== "object")
+                return undefined;
+            const fsc = fs;
+            const toolFields = {};
+            if (fsc.toolFields && typeof fsc.toolFields === "object") {
+                for (const [pattern, rule] of Object.entries(fsc.toolFields)) {
+                    if (rule && typeof rule === "object" && Array.isArray(rule.scanFields)) {
+                        toolFields[pattern] = { scanFields: rule.scanFields.filter((f) => typeof f === "string") };
+                    }
+                }
+            }
+            return {
+                toolFields,
+                neverScanFields: Array.isArray(fsc.neverScanFields)
+                    ? fsc.neverScanFields.filter((f) => typeof f === "string")
+                    : [],
+                defaultScanFields: Array.isArray(fsc.defaultScanFields)
+                    ? fsc.defaultScanFields.filter((f) => typeof f === "string")
+                    : [],
+                useContractExemptions: typeof fsc.useContractExemptions === "boolean" ? fsc.useContractExemptions : false,
+            };
+        })(),
     };
     return config;
 }

package/dist/detectors/regex.js

@@ -1179,6 +1179,251 @@ export const BUILTIN_PATTERNS = [
         category: Category.ACL_NAME,
         confidence: 0.85,
     },
+    // ===================================================================
+    // Healthcare — HIPAA-relevant identifiers
+    // ===================================================================
+    // --- Date of birth (context-triggered) ---
+    {
+        // "DOB: 03/15/1987" or "DOB 1987-03-15" or "date of birth: 03/15/1987"
+        name: "dob_keyword",
+        pattern: /(?:DOB|date\s+of\s+birth|birthdate|born\s+on|birth\s+date|geburtsdatum)\s*[:=]?\s*(\d{1,2}[\/\-.]\d{1,2}[\/\-.]\d{2,4})/gi,
+        category: Category.DATE_OF_BIRTH,
+        confidence: 0.9,
+    },
+    {
+        // ISO date after DOB keyword: "DOB: 1987-03-15"
+        name: "dob_iso",
+        pattern: /(?:DOB|date\s+of\s+birth|birthdate|birth\s+date)\s*[:=]?\s*(\d{4}-\d{2}-\d{2})/gi,
+        category: Category.DATE_OF_BIRTH,
+        confidence: 0.9,
+    },
+    {
+        // Written month: "born on March 15, 1987" or "DOB: January 3, 1990"
+        name: "dob_written",
+        pattern: /(?:DOB|date\s+of\s+birth|birthdate|born\s+on|birth\s+date)\s*[:=]?\s*((?:January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{1,2},?\s+\d{4})/gi,
+        category: Category.DATE_OF_BIRTH,
+        confidence: 0.9,
+    },
+    // --- Medical record number (MRN) ---
+    {
+        // "MRN: 12345678" or "medical record number: ABC-123456"
+        name: "mrn_keyword",
+        pattern: /(?:MRN|medical\s*record\s*(?:number|no|#)?|patient\s*(?:id|number|#))\s*[:=#]?\s*([A-Z0-9][\w\-]{3,19})/gi,
+        category: Category.MEDICAL_RECORD_NUMBER,
+        confidence: 0.9,
+    },
+    {
+        // US NPI (National Provider Identifier): 10-digit number with "NPI" context
+        name: "npi_number",
+        pattern: /(?:NPI|national\s*provider)\s*[:=#]?\s*(\d{10})\b/gi,
+        category: Category.MEDICAL_RECORD_NUMBER,
+        confidence: 0.95,
+    },
+    {
+        // US DEA number: 2 letters + 7 digits (e.g., "AB1234567")
+        name: "dea_number",
+        pattern: /(?:DEA|drug\s*enforcement)\s*[:=#]?\s*([A-Z][A-Z9]\d{7})\b/gi,
+        category: Category.MEDICAL_RECORD_NUMBER,
+        confidence: 0.95,
+    },
+    {
+        // Health insurance policy/member/subscriber ID
+        name: "health_insurance_id",
+        pattern: /(?:(?:health\s*)?(?:insurance|policy|member|subscriber|group)\s*(?:id|number|no|#))\s*[:=#]?\s*([A-Z0-9][\w\-]{3,19})/gi,
+        category: Category.MEDICAL_RECORD_NUMBER,
+        confidence: 0.85,
+    },
+    // ===================================================================
+    // Finance — bank accounts, routing numbers, tax IDs
+    // ===================================================================
+    // --- Bank account numbers (context-triggered) ---
+    {
+        // US routing number (ABA/transit): 9 digits with context
+        name: "us_routing_number",
+        pattern: /(?:routing|ABA|transit)\s*(?:number|no|#)?\s*[:=#]?\s*(\d{9})\b/gi,
+        category: Category.BANK_ACCOUNT_NUMBER,
+        confidence: 0.9,
+    },
+    {
+        // Bank account number with context keyword
+        name: "bank_account_keyword",
+        pattern: /(?:(?:bank\s*)?account|acct)\s*(?:number|no|#)\s*[:=#]?\s*(\d{4,17})\b/gi,
+        category: Category.BANK_ACCOUNT_NUMBER,
+        confidence: 0.85,
+    },
+    {
+        // UK sort code: XX-XX-XX with context
+        name: "uk_sort_code",
+        pattern: /(?:sort\s*code)\s*[:=#]?\s*(\d{2}-\d{2}-\d{2})\b/gi,
+        category: Category.BANK_ACCOUNT_NUMBER,
+        confidence: 0.9,
+    },
+    {
+        // SWIFT/BIC code: 8 or 11 alphanumeric characters (e.g., DEUTDEFF, BOFAUS3NXXX)
+        name: "swift_bic",
+        pattern: /(?:SWIFT|BIC|SWIFT\/BIC)\s*[:=#]?\s*([A-Z]{4}[A-Z]{2}[A-Z0-9]{2}(?:[A-Z0-9]{3})?)\b/gi,
+        category: Category.BANK_ACCOUNT_NUMBER,
+        confidence: 0.9,
+    },
+    {
+        // Standalone SWIFT/BIC pattern (distinctive 8/11-char format)
+        name: "swift_bic_standalone",
+        pattern: /\b([A-Z]{4}(?:AT|DE|CH|GB|US|FR|IT|ES|NL|BE|AU|CA|JP|CN|IN|BR|MX|ZA|SE|NO|DK|FI|IE|PT|CZ|PL|HU|RO|BG|HR|SK|SI|LT|LV|EE|MT|CY|LU|GR)[A-Z0-9]{2}(?:[A-Z0-9]{3})?)\b/g,
+        category: Category.BANK_ACCOUNT_NUMBER,
+        confidence: 0.85,
+    },
+    // --- Tax IDs ---
+    {
+        // US EIN (Employer Identification Number): XX-XXXXXXX with context
+        name: "us_ein",
+        pattern: /(?:EIN|employer\s*(?:identification|id)\s*(?:number|no|#)?|tax\s*(?:id|identification)\s*(?:number|no|#)?)\s*[:=#]?\s*(\d{2}-\d{7})\b/gi,
+        category: Category.TAX_ID,
+        confidence: 0.9,
+    },
+    {
+        // TIN/tax number generic context-triggered
+        name: "tax_id_generic",
+        pattern: /(?:TIN|tax\s*(?:id|number|identification)|taxpayer\s*(?:id|number))\s*[:=#]?\s*(\d[\d\-]{5,12})\b/gi,
+        category: Category.TAX_ID,
+        confidence: 0.85,
+    },
+    {
+        // UK UTR (Unique Taxpayer Reference): 10 digits with context
+        name: "uk_utr",
+        pattern: /(?:UTR|unique\s*taxpayer\s*(?:reference|ref))\s*[:=#]?\s*(\d{10})\b/gi,
+        category: Category.TAX_ID,
+        confidence: 0.9,
+    },
+    // ===================================================================
+    // Legal / Identity Documents
+    // ===================================================================
+    // --- Passport numbers (context-triggered) ---
+    {
+        // Generic context: "passport no: P12345678" or "passport number: 123456789"
+        name: "passport_keyword",
+        pattern: /(?:passport)\s*(?:number|no|#)?\s*[:=#]?\s*([A-Z0-9]{6,12})\b/gi,
+        category: Category.PASSPORT_NUMBER,
+        confidence: 0.9,
+    },
+    {
+        // German Reisepass: "Reisepass: C01X00T47"
+        name: "passport_de",
+        pattern: /(?:Reisepass|Personalausweis)\s*(?:Nr|number|no|#)?\.?\s*[:=#]?\s*([CFGHJKLMNPRTVWXYZ0-9]{9})\b/gi,
+        category: Category.PASSPORT_NUMBER,
+        confidence: 0.9,
+    },
+    {
+        // Travel document context: "travel document: XX1234567"
+        name: "travel_document",
+        pattern: /(?:travel\s*document)\s*(?:number|no|#)?\s*[:=#]?\s*([A-Z0-9]{6,12})\b/gi,
+        category: Category.PASSPORT_NUMBER,
+        confidence: 0.85,
+    },
+    // --- Driver's license (context-triggered) ---
+    {
+        // Generic: "driver's license: A1234567" or "DL: 12345678"
+        name: "drivers_license_keyword",
+        pattern: /(?:driver'?s?\s*licen[sc]e|DL|driving\s*licen[sc]e|F[üu]hrerschein)\s*(?:number|no|#|Nr)?\.?\s*[:=#]?\s*([A-Z0-9][\w\-]{3,19})\b/gi,
+        category: Category.DRIVERS_LICENSE,
+        confidence: 0.9,
+    },
+    {
+        // US California format: letter + 7 digits with context
+        name: "dl_california",
+        pattern: /(?:driver'?s?\s*licen[sc]e|DL)\s*(?:number|no|#)?\s*[:=#]?\s*([A-Z]\d{7})\b/gi,
+        category: Category.DRIVERS_LICENSE,
+        confidence: 0.9,
+    },
+    {
+        // License plate / vehicle registration (context-triggered, requires : or = separator)
+        name: "license_plate",
+        pattern: /(?:licen[sc]e\s*plate|registration\s*(?:number|no|#|plate)|vehicle\s*(?:plate|reg|registration)|Kennzeichen|plaque)\s*[:=#]\s*([A-Z][A-Z0-9\-]{1,11}[A-Z0-9])\b/gi,
+        category: Category.DRIVERS_LICENSE,
+        confidence: 0.85,
+    },
+    // --- Court case / docket numbers ---
+    {
+        // US federal court: "1:23-cv-01234" or "2:24-cr-00567"
+        name: "us_federal_case",
+        pattern: /\b(\d{1,2}:\d{2}-[a-z]{2}-\d{3,6})\b/g,
+        category: Category.CASE_NUMBER,
+        confidence: 0.95,
+    },
+    {
+        // Generic case/docket number with context keyword
+        name: "case_number_keyword",
+        pattern: /(?:case|docket|cause|filing)\s*(?:number|no|#)?\s*[:=#]?\s*([A-Z0-9][\w\-\/]{3,24})\b/gi,
+        category: Category.CASE_NUMBER,
+        confidence: 0.85,
+    },
+    {
+        // Patent number: "US12345678" or "EP1234567" or "WO2024123456"
+        name: "patent_number",
+        pattern: /\b((?:US|EP|WO|JP|CN|KR|AU|CA)\s?\d{4,12}(?:\s?[AB]\d?)?)\b/g,
+        category: Category.CASE_NUMBER,
+        confidence: 0.85,
+    },
+    {
+        // Aktenzeichen (German file reference): "Az.: 1 BvR 123/45" or "Az. 12 O 456/23"
+        name: "aktenzeichen",
+        pattern: /(?:Az\.?|Aktenzeichen)\s*[:=]?\s*(\d{1,3}\s+[A-Z][a-z]*\s+\d{1,5}\/\d{2,4})\b/gi,
+        category: Category.CASE_NUMBER,
+        confidence: 0.9,
+    },
+    // ===================================================================
+    // Cloud / Crypto
+    // ===================================================================
+    // --- Cryptocurrency addresses (standalone — distinctive formats) ---
+    {
+        // Ethereum address: 0x + 40 hex chars
+        name: "crypto_ethereum",
+        pattern: /\b(0x[0-9a-fA-F]{40})\b/g,
+        category: Category.CRYPTOCURRENCY_ADDRESS,
+        confidence: 0.95,
+    },
+    {
+        // Bitcoin P2PKH: starts with 1, 25-34 base58 chars
+        name: "crypto_bitcoin_p2pkh",
+        pattern: /\b(1[a-km-zA-HJ-NP-Z1-9]{25,34})\b/g,
+        category: Category.CRYPTOCURRENCY_ADDRESS,
+        confidence: 0.9,
+    },
+    {
+        // Bitcoin P2SH: starts with 3, 25-34 base58 chars
+        name: "crypto_bitcoin_p2sh",
+        pattern: /\b(3[a-km-zA-HJ-NP-Z1-9]{25,34})\b/g,
+        category: Category.CRYPTOCURRENCY_ADDRESS,
+        confidence: 0.9,
+    },
+    {
+        // Bitcoin Bech32: bc1 + 39-59 lowercase alphanum
+        name: "crypto_bitcoin_bech32",
+        pattern: /\b(bc1[a-z0-9]{39,59})\b/g,
+        category: Category.CRYPTOCURRENCY_ADDRESS,
+        confidence: 0.95,
+    },
+    {
+        // Crypto wallet/address with context keyword
+        name: "crypto_wallet_keyword",
+        pattern: /(?:wallet|crypto|bitcoin|ethereum|eth|btc)\s*(?:address|addr|id)?\s*[:=#]?\s*([a-zA-Z0-9]{26,64})\b/gi,
+        category: Category.CRYPTOCURRENCY_ADDRESS,
+        confidence: 0.85,
+    },
+    // --- AWS ARN (standalone — distinctive format) ---
+    {
+        // Full ARN: arn:aws:service:region:account-id:resource (account may be empty for S3)
+        name: "aws_arn",
+        pattern: /\b(arn:aws[a-z\-]*:[a-z0-9\-]+:[a-z0-9\-]*:\d{0,12}:[^\s"']{1,128})\b/g,
+        category: Category.AWS_ARN,
+        confidence: 0.95,
+    },
+    {
+        // AWS account ID with context: 12-digit number after "account" keyword
+        name: "aws_account_id",
+        pattern: /(?:(?:aws|amazon)\s*)?account\s*(?:id|#|number)?\s*[:=#]?\s*(\d{12})\b/gi,
+        category: Category.AWS_ARN,
+        confidence: 0.85,
+    },
 ];
 /**
  * Tracks occupied text spans and answers overlap queries in O(log n)

package/dist/field-scope.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-tool field scoping and per-agent category exemptions for obfuscation.
+ *
+ * Reduces false positives by only scanning relevant fields per tool and
+ * exempting entity categories that the agent's contract allows.
+ */
+import type { FieldScopingConfig, ScopeDecision } from "./types.js";
+export declare class FieldScopeResolver {
+    private readonly toolPatterns;
+    private readonly neverScanFields;
+    private readonly defaultScanFields;
+    private readonly useContractExemptions;
+    private readonly enabled;
+    constructor(config?: FieldScopingConfig);
+    /** Resolve which fields to scan for a given tool name. */
+    resolveToolScope(toolName: string): ScopeDecision;
+    /**
+     * Resolve which entity categories are exempt from obfuscation for an agent.
+     * Uses the agent contract's allowedDataClasses — those categories are data
+     * the agent is trusted to handle, so obfuscating them is counterproductive.
+     */
+    resolveAgentExemptions(agentLabel: string, role: string): Set<string>;
+    /** Check if a field should be scanned given the resolved scope. */
+    shouldScanField(fieldName: string, scope: ScopeDecision): boolean;
+}

package/dist/field-scope.js

@@ -0,0 +1,92 @@
+/**
+ * Per-tool field scoping and per-agent category exemptions for obfuscation.
+ *
+ * Reduces false positives by only scanning relevant fields per tool and
+ * exempting entity categories that the agent's contract allows.
+ */
+/** Simple wildcard matching (supports * and ?). */
+function wildcardMatch(value, pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`, "i").test(value);
+}
+export class FieldScopeResolver {
+    toolPatterns;
+    neverScanFields;
+    defaultScanFields;
+    useContractExemptions;
+    enabled;
+    constructor(config) {
+        if (!config) {
+            this.enabled = false;
+            this.toolPatterns = [];
+            this.neverScanFields = new Set();
+            this.defaultScanFields = new Set();
+            this.useContractExemptions = false;
+            return;
+        }
+        this.enabled = true;
+        this.neverScanFields = new Set(config.neverScanFields ?? []);
+        this.defaultScanFields = new Set(config.defaultScanFields ?? []);
+        this.useContractExemptions = config.useContractExemptions ?? false;
+        this.toolPatterns = [];
+        for (const [pattern, rule] of Object.entries(config.toolFields ?? {})) {
+            this.toolPatterns.push({ pattern, scanFields: new Set(rule.scanFields) });
+        }
+    }
+    /** Resolve which fields to scan for a given tool name. */
+    resolveToolScope(toolName) {
+        if (!this.enabled) {
+            return { mode: "all", scanFields: new Set(), neverScanFields: new Set() };
+        }
+        // Find first matching tool pattern
+        for (const { pattern, scanFields } of this.toolPatterns) {
+            if (wildcardMatch(toolName, pattern)) {
+                return {
+                    mode: "selected",
+                    scanFields,
+                    neverScanFields: this.neverScanFields,
+                };
+            }
+        }
+        // No match — use default
+        if (this.defaultScanFields.size > 0) {
+            return {
+                mode: "selected",
+                scanFields: this.defaultScanFields,
+                neverScanFields: this.neverScanFields,
+            };
+        }
+        // Empty defaultScanFields = scan everything (backward compatible)
+        return { mode: "all", scanFields: new Set(), neverScanFields: this.neverScanFields };
+    }
+    /**
+     * Resolve which entity categories are exempt from obfuscation for an agent.
+     * Uses the agent contract's allowedDataClasses — those categories are data
+     * the agent is trusted to handle, so obfuscating them is counterproductive.
+     */
+    resolveAgentExemptions(agentLabel, role) {
+        if (!this.enabled || !this.useContractExemptions) {
+            return new Set();
+        }
+        // contracts.ts only exists on feature/transformer — graceful fallback
+        try {
+            const { resolveAgentContract } = require("./contracts.js");
+            const contract = resolveAgentContract(agentLabel, role);
+            return new Set(contract.allowedDataClasses);
+        }
+        catch {
+            return new Set();
+        }
+    }
+    /** Check if a field should be scanned given the resolved scope. */
+    shouldScanField(fieldName, scope) {
+        if (scope.neverScanFields.has(fieldName))
+            return false;
+        if (scope.mode === "all")
+            return true;
+        return scope.scanFields.has(fieldName);
+    }
+}

package/dist/generators/codes.d.ts

@@ -14,7 +14,72 @@ export declare class CodeGenerator implements BaseGenerator {
     _fakeSsn(seed: number): string;
     _fakePhone(seed: number, original: string): string;
     _fakeIban(seed: number, original: string): string;
+    /**
+     * Format-aware national ID generator.
+     * Preserves structure per detected sub-type rather than generic zero-padding.
+     */
     _fakeNationalId(seed: number, original: string): string;
     _fakeJwt(seed: number): string;
+    /**
+     * GPS coordinate generator — distributes across plausible world locations
+     * instead of clustering near null island (0,0).
+     */
     _fakeGps(seed: number): string;
+    /**
+     * ICS/SCADA identifier — format-aware per sub-type.
+     * Preserves structure for OPC UA endpoints, Modbus addresses, BACnet IDs, etc.
+     */
+    _fakeIcsId(seed: number, original: string): string;
+    /**
+     * Certificate generator — produces structurally valid PEM-like blocks
+     * instead of [REDACTED-CERT-XXXX] placeholders.
+     */
+    _fakeCertificate(seed: number, original: string): string;
+    /**
+     * Format-preserving fake date of birth.
+     * Shifts the date by a deterministic offset (30-300 days) derived from seed,
+     * preserving the original format (MM/DD/YYYY, YYYY-MM-DD, DD.MM.YYYY, written month).
+     */
+    _fakeDob(seed: number, original: string): string;
+    /**
+     * Fake medical record / provider ID.
+     * Preserves format structure (letter+digits, pure digits, with dashes).
+     */
+    _fakeMedicalId(seed: number, original: string): string;
+    /**
+     * Fake bank account / routing number.
+     * Preserves format (digit count, dashes, sort code format).
+     */
+    _fakeBankAccount(seed: number, original: string): string;
+    /**
+     * Fake tax ID / EIN.
+     * Preserves format (XX-XXXXXXX for EIN, pure digits for others).
+     */
+    _fakeTaxId(seed: number, original: string): string;
+    /**
+     * Fake passport number.
+     * Preserves format: letter prefix + digit count, or pure alphanumeric.
+     */
+    _fakePassport(seed: number, original: string): string;
+    /**
+     * Fake driver's license / license plate.
+     * Preserves format structure (letter/digit positions, dashes, spaces).
+     */
+    _fakeDriversLicense(seed: number, original: string): string;
+    /**
+     * Fake case / docket / patent number.
+     * Preserves format: digit:digit-letters-digits, or prefix + digits.
+     */
+    _fakeCaseNumber(seed: number, original: string): string;
+    /**
+     * Fake cryptocurrency address.
+     * Preserves format: Ethereum (0x + 40 hex), Bitcoin P2PKH/P2SH (base58),
+     * Bitcoin Bech32 (bc1 + lowercase alphanum).
+     */
+    _fakeCryptoAddress(seed: number, original: string): string;
+    /**
+     * Fake AWS ARN.
+     * Preserves service and resource type, replaces account ID and resource name.
+     */
+    _fakeAwsArn(seed: number, original: string): string;
 }