deepdebug-local-agent 1.1.0 → 1.2.0

package/src/dlp/rules.js

@@ -0,0 +1,97 @@
+/**
+ * DLP ruleset (versioned). Each rule: { id, class, re, group?, validate? }.
+ *  - id:       stable identifier, used as the metric label and in the placeholder.
+ *  - class:    coarse family, used by LOCAL_AGENT_DLP_BLOCK_CLASSES.
+ *  - re:       global regex (the engine resets lastIndex; never share state).
+ *  - group:    capture group to redact; default is the whole match.
+ *  - validate: optional predicate on the redactable text; false = not a hit.
+ *
+ * Order matters: specific rules run before generic ones, so a Stripe key is
+ * reported as stripe_key and not as a generic secret assignment.
+ * Bump RULESET_VERSION on every change to the list or to a pattern.
+ *
+ * Reimplemented from public token formats; no third-party rule files copied.
+ */
+import {
+    looksLikeLiteralSecret, looksLikeOpaqueKey, realEmail, plausiblePhone,
+    plausibleCard, ibanValid, ptNifValid,
+} from './validators.js';
+
+export const RULESET_VERSION = '2026.10.28-1';
+
+export const RULE_CLASSES = Object.freeze([
+    'private-key', 'cloud-credential', 'vcs-token', 'payment-key', 'saas-token', 'token',
+    'credential', 'connection-string', 'url-credential', 'pii-email', 'pii-phone', 'pii-id',
+    'pii-financial', 'high-entropy',
+]);
+
+const r = (id, cls, re, extra = {}) => Object.freeze({ id, class: cls, re, ...extra });
+
+export const RULES = Object.freeze([
+    // Private keys first: they span lines and may contain other-looking text.
+    r('pem_private_key', 'private-key',
+        /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----|$)/g),
+
+    // Cloud
+    r('aws_access_key_id', 'cloud-credential', /\b(?:AKIA|ASIA|AGPA|AIDA|AROA|ANPA|ANVA|AIPA)[A-Z0-9]{16}\b/g),
+    r('aws_secret_access_key', 'cloud-credential',
+        /\baws[_-]?secret[_-]?(?:access[_-]?)?key["']?\s*[:=]\s*["']?([A-Za-z0-9/+=]{40})\b/gi, { group: 1 }),
+    r('gcp_api_key', 'cloud-credential', /\bAIza[0-9A-Za-z_-]{35}\b/g),
+    r('gcp_oauth_token', 'cloud-credential', /\bya29\.[0-9A-Za-z_-]{20,}/g),
+    r('gcp_oauth_client_secret', 'cloud-credential', /\bGOCSPX-[A-Za-z0-9_-]{20,}/g),
+    r('azure_storage_account_key', 'cloud-credential', /\bAccountKey=([A-Za-z0-9+/]{40,}={0,2})/g, { group: 1 }),
+    r('digitalocean_token', 'cloud-credential', /\bdo[opr]_v1_[a-f0-9]{64}\b/g),
+
+    // VCS / package registries
+    r('github_token', 'vcs-token', /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g),
+    r('github_fine_grained_pat', 'vcs-token', /\bgithub_pat_[A-Za-z0-9_]{22,}\b/g),
+    r('gitlab_pat', 'vcs-token', /\bglpat-[A-Za-z0-9_-]{20,}/g),
+    r('npm_token', 'vcs-token', /\bnpm_[A-Za-z0-9]{36}\b/g),
+    r('pypi_token', 'vcs-token', /\bpypi-AgEIcHlwaS5vcmc[A-Za-z0-9_-]{50,}/g),
+
+    // Payments / SaaS
+    r('stripe_key', 'payment-key', /\b[sr]k_(?:live|test)_[0-9A-Za-z]{16,}\b/g),
+    r('stripe_webhook_secret', 'payment-key', /\bwhsec_[A-Za-z0-9]{16,}\b/g),
+    r('shopify_token', 'saas-token', /\bshp(?:at|ca|pa|ss)_[a-f0-9]{32}\b/g),
+    r('slack_token', 'saas-token', /\bxox[abprs]-[A-Za-z0-9-]{10,}/g),
+    r('slack_webhook', 'saas-token', /https:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]+/g),
+    r('discord_webhook', 'saas-token', /https:\/\/(?:discord|discordapp)\.com\/api\/webhooks\/\d+\/[\w-]+/g),
+    r('sendgrid_key', 'saas-token', /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/g),
+    r('twilio_api_key', 'saas-token', /\bSK[0-9a-f]{32}\b/g),
+    r('mailgun_key', 'saas-token', /\bkey-[0-9a-f]{32}\b/g),
+    r('huggingface_token', 'saas-token', /\bhf_[A-Za-z0-9]{34,}\b/g),
+    r('telegram_bot_token', 'saas-token', /\b\d{8,10}:AA[A-Za-z0-9_-]{33}\b/g),
+    r('anthropic_key', 'saas-token', /\bsk-ant-[A-Za-z0-9_-]{20,}/g),
+    r('openai_key', 'saas-token', /\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}/g, { validate: (v) => /\d/.test(v) }),
+
+    // Generic tokens
+    r('jwt', 'token', /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g),
+    r('bearer_token', 'token', /\bBearer\s+([A-Za-z0-9._~+/-]{20,}=*)/g, { group: 1 }),
+    r('basic_auth_header', 'token', /\bAuthorization:\s*Basic\s+([A-Za-z0-9+/]{12,}={0,2})/gi, { group: 1 }),
+
+    // Connection strings and URL credentials (before the generic assignment rule)
+    r('db_connection_string', 'connection-string',
+        /\b(?:postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|redis|rediss|amqps?|mssql|sqlserver|cockroachdb):\/\/[^\s"'`<>]+/gi,
+        { validate: (v) => /:\/\/[^/\s]*@/.test(v) }),
+    r('jdbc_password', 'connection-string', /\bjdbc:[a-z0-9]+:[^\s"'`]*?[?&;](?:password|pwd)=([^\s&;"'`]+)/gi, { group: 1 }),
+    r('ado_connection_password', 'connection-string', /(?:^|;)\s*(?:Password|Pwd)\s*=\s*([^;\r\n"']{3,})/gim, { group: 1 }),
+    r('url_credentials', 'url-credential', /\b[a-z][a-z0-9+.-]{0,20}:\/\/([^\s:@/"'`<>]+:[^\s@/"'`<>]+)@/gi, { group: 1, validate: (v) => !/[${}<>]/.test(v) }),
+
+    // Generic "name = literal" assignments
+    r('generic_secret_assignment', 'credential',
+        /\b(?:[A-Za-z0-9_-]{0,40}?(?:password|passwd|pwd|secret|api[_-]?key|apikey|access[_-]?token|auth[_-]?token|client[_-]?secret|private[_-]?key|token))["']?\s*(?::|=|=>)\s*["']?([^\s"'`,;]{8,})/gi,
+        { group: 1, validate: looksLikeLiteralSecret }),
+
+    // PII
+    r('email', 'pii-email', /[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(?:\.[A-Za-z0-9-]{1,63}){0,6}\.[A-Za-z]{2,24}(?![A-Za-z0-9_~./-]|:[A-Za-z0-9_~./-])/g, { validate: realEmail }),
+    r('iban', 'pii-financial', /\b[A-Z]{2}\d{2}(?: ?[A-Z0-9]{4}){2,7}(?: ?[A-Z0-9]{1,3})?\b/g, { validate: ibanValid }),
+    r('credit_card', 'pii-financial', /(?<![\d.-])\d{4}(?:[ -]?\d{4}){2}[ -]?\d{1,7}(?![\d-])/g, { validate: plausibleCard }),
+    r('pt_nif', 'pii-id',
+        /\b(?:NIF|NIPC|contribuinte|VAT)\b\s*(?:n[.ºo°]*\s*)?[:=#-]?\s*(?:PT)?(\d{9})\b/gi, { group: 1, validate: ptNifValid }),
+    r('phone_international', 'pii-phone', /(?<![\w.+])(?:\+|00)\d{1,3}(?:[ .-]?\(?\d{1,4}\)?){2,5}(?![\w])/g,
+        { validate: plausiblePhone }),
+
+    // Last: opaque high-entropy blobs
+    r('high_entropy_blob', 'high-entropy', /(?<![A-Za-z0-9+/_=-])[A-Za-z0-9+/_=-]{40,}(?![A-Za-z0-9+/_=-])/g,
+        { validate: looksLikeOpaqueKey }),
+]);

package/src/dlp/validators.js

@@ -0,0 +1,123 @@
+/**
+ * DLP validators: pure helpers that cut false positives after a regex matched.
+ * No I/O, no state.
+ */
+
+/** Shannon entropy in bits per character. */
+export function shannonEntropy(s) {
+    if (!s) return 0;
+    const freq = new Map();
+    for (const ch of s) freq.set(ch, (freq.get(ch) || 0) + 1);
+    let h = 0;
+    for (const n of freq.values()) {
+        const p = n / s.length;
+        h -= p * Math.log2(p);
+    }
+    return h;
+}
+
+/** Luhn checksum over a digit string. */
+export function luhnValid(digits) {
+    if (!/^\d{13,19}$/.test(digits)) return false;
+    let sum = 0;
+    let alt = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let d = digits.charCodeAt(i) - 48;
+        if (alt) {
+            d *= 2;
+            if (d > 9) d -= 9;
+        }
+        sum += d;
+        alt = !alt;
+    }
+    return sum % 10 === 0;
+}
+
+/** ISO 13616 mod-97 check for an IBAN (spaces allowed). */
+export function ibanValid(raw) {
+    const s = raw.replace(/\s+/g, '').toUpperCase();
+    if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(s)) return false;
+    const rearranged = s.slice(4) + s.slice(0, 4);
+    let rem = 0;
+    for (const ch of rearranged) {
+        const v = ch >= 'A' && ch <= 'Z' ? String(ch.charCodeAt(0) - 55) : ch;
+        for (const c of v) rem = (rem * 10 + (c.charCodeAt(0) - 48)) % 97;
+    }
+    return rem === 1;
+}
+
+/** Portuguese NIF/NIPC checksum (9 digits, mod 11). */
+export function ptNifValid(digits) {
+    if (!/^\d{9}$/.test(digits)) return false;
+    const okPrefix = '1235689'.includes(digits[0]) || /^(?:45|70|71|72|74|75|77|79)/.test(digits);
+    if (!okPrefix) return false;
+    let sum = 0;
+    for (let i = 0; i < 8; i++) sum += (digits.charCodeAt(i) - 48) * (9 - i);
+    const check = 11 - (sum % 11);
+    const expected = check >= 10 ? 0 : check;
+    return expected === digits.charCodeAt(8) - 48;
+}
+
+const PLACEHOLDER_PREFIX = /^(?:\$|\{|<|%|\[|\(|process\.env|os\.getenv|env\[|getenv|config\.|settings\.|this\.|self\.|args\.|params\.|req\.|request\.|\.\.\.)/i;
+const PLACEHOLDER_WORDS = /^(?:\*+|x{3,}|null|undefined|none|true|false|string|required|optional|redacted|changeme|change_me|your[-_ ].*|example.*|placeholder.*|dummy.*|secret|password|token|apikey|api_key)$/i;
+
+/**
+ * Decide whether the value assigned to a secret-looking name is a literal
+ * credential or just code (identifier, call, template, placeholder).
+ */
+export function looksLikeLiteralSecret(value) {
+    const v = value.replace(/^["'`]+|["'`]+$/g, '');
+    if (v.length < 8) return false;
+    if (PLACEHOLDER_PREFIX.test(v) || PLACEHOLDER_WORDS.test(v)) return false;
+    if (v.includes('REDACTED') || v.includes('***')) return false;
+    if (/[()]/.test(v)) return false;             // function call / expression
+    if (/^[A-Za-z_][A-Za-z0-9_.]*$/.test(v) && !/\d/.test(v)) {
+        // plain identifier or dotted path (getPassword, config.password): code, not a secret
+        return false;
+    }
+    if (/^[a-z]+(?:[-_][a-z]+)+$/.test(v)) return false; // kebab/snake names (secret ids, flags), not values
+    const hasDigit = /\d/.test(v);
+    const hasSymbol = /[!@#$%^&*+/=~\-]/.test(v);
+    if (hasDigit || hasSymbol) return true;
+    return v.length >= 16 && shannonEntropy(v) >= 3.5;
+}
+
+/** High-entropy blob heuristic (opaque keys); excludes hashes, UUIDs and paths. */
+export function looksLikeOpaqueKey(token) {
+    if (token.length < 40) return false;
+    if (/^sha\d+-/i.test(token)) return false;                 // npm/SRI integrity hashes
+    if (/^[0-9a-f]+$/i.test(token)) return false;              // hex digests / git SHAs
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(token)) return false; // UUID
+    if (token.startsWith('/') || token.includes('//')) return false; // path / URL remnants
+    // Standard base64 never has - or _, URL-safe never has /: a mix means a path or URL fragment.
+    if (token.includes('/') && /[-_]/.test(token)) return false;
+    if (!/[a-z]/.test(token) || !/[A-Z]/.test(token) || !/\d/.test(token)) return false;
+    return shannonEntropy(token) >= 4.5;
+}
+
+const NON_MAIL_TLDS = new Set(['png', 'jpg', 'jpeg', 'gif', 'svg', 'webp', 'ico', 'css', 'js', 'ts', 'json', 'map', 'woff', 'woff2', 'ttf', 'eot', 'html', 'md']);
+const DOC_DOMAINS = /(?:^|\.)(?:example\.(?:com|org|net)|test|invalid|localhost|local)$/i;
+
+/** E-mail: reject asset names (logo@2x.png) and reserved documentation domains. */
+export function realEmail(addr) {
+    const at = addr.lastIndexOf('@');
+    const domain = addr.slice(at + 1);
+    const tld = domain.slice(domain.lastIndexOf('.') + 1).toLowerCase();
+    if (NON_MAIL_TLDS.has(tld)) return false;
+    if (DOC_DOMAINS.test(domain)) return false;
+    return true;
+}
+
+/** International phone: leading +, 9 to 15 digits overall. */
+export function plausiblePhone(raw) {
+    const digits = raw.replace(/\D/g, '');
+    return digits.length >= 9 && digits.length <= 15;
+}
+
+/** Card number candidates: Luhn + plausible leading digit, separators ignored. */
+export function plausibleCard(raw) {
+    const digits = raw.replace(/[ -]/g, '');
+    if (!/^[2-6]/.test(digits)) return false;
+    if (/^(\d)\1+$/.test(digits)) return false;
+    return luhnValid(digits);
+}

package/src/siblings/incident-forwarder.js

@@ -25,6 +25,7 @@
  */
 import { logger as defaultLogger } from './logger.js';
 import { BurstSuppressor } from './burst-suppressor.js';
+import { protectEgress } from '../dlp/index.js';
 
 const SIX_KEYS = ['adapter', 'errorCode', 'file', 'message', 'source', 'timestamp'];
 
@@ -293,7 +294,8 @@ export class IncidentForwarder {
         return {
             tenantId: this.tenantId || undefined,
             service: evt.source,
-            message: evt.message,
+            // DLP (LOCAL_AGENT_DLP_MODE, default off = unchanged): log excerpts leave the customer network here.
+            message: protectEgress(evt.message, { source: 'incident-forwarder', log: (o, m) => this.logger.info(o, m) }).text,
             severity: 'error',
             environment: 'production',
             detectedBy: 'local-agent-adapter',

package/test/dlp/engine.test.js

@@ -0,0 +1,173 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { maskSensitive, maskDeep, normalizeMode, rulesetHash } from '../../src/dlp/engine.js';
+import { RULES, RULESET_VERSION } from '../../src/dlp/rules.js';
+import { POSITIVES, NEGATIVES, validPtNif } from './fixtures.js';
+
+describe('ruleset', () => {
+    test('has at least 30 distinct rules with unique ids and valid regexes', () => {
+        const ids = RULES.map((r) => r.id);
+        assert.ok(ids.length >= 30, `only ${ids.length} rules`);
+        assert.equal(new Set(ids).size, ids.length);
+        for (const r of RULES) assert.ok(r.re.flags.includes('g'), r.id);
+    });
+    test('hash is stable and changes with the rules', () => {
+        assert.equal(rulesetHash(), rulesetHash());
+        assert.match(rulesetHash(), /^[0-9a-f]{64}$/);
+        assert.notEqual(rulesetHash(RULES.slice(1)), rulesetHash());
+        assert.match(RULESET_VERSION, /^\d{4}\.\d{2}\.\d{2}-\d+$/);
+    });
+    test('every rule is exercised by the positive corpus', () => {
+        const covered = new Set(POSITIVES.map(([id]) => id));
+        for (const r of RULES) assert.ok(covered.has(r.id), `no positive fixture for ${r.id}`);
+    });
+});
+
+describe('positives: zero leaks in enforce', () => {
+    for (const [ruleId, sample, secret] of POSITIVES) {
+        test(`${ruleId}: ${sample.slice(0, 24).replace(/\n/g, ' ')}`, () => {
+            const res = maskSensitive(sample, { mode: 'enforce' });
+            assert.ok(res.redactions[ruleId] >= 1, `expected ${ruleId}, got ${JSON.stringify(res.redactions)}`);
+            assert.match(res.text, new RegExp(`\\[REDACTED:${ruleId}\\]`));
+            if (secret) assert.ok(!res.text.includes(secret), 'secret still present');
+            assert.ok(!res.blocked);
+            // idempotent: masking masked text finds nothing new
+            assert.equal(maskSensitive(res.text, { mode: 'enforce' }).total, 0);
+        });
+    }
+});
+
+describe('false positives', () => {
+    for (const text of NEGATIVES) {
+        test(`unchanged: ${text.slice(0, 50)}`, () => {
+            const res = maskSensitive(text, { mode: 'enforce' });
+            assert.equal(res.text, text, JSON.stringify(res.redactions));
+            assert.equal(res.total, 0);
+        });
+    }
+    test('false-positive rate on the negative corpus is 0 %', () => {
+        const hits = NEGATIVES.filter((t) => maskSensitive(t, { mode: 'enforce' }).total > 0);
+        assert.equal(hits.length, 0);
+    });
+    test('valid NIF only with context', () => {
+        const nif = validPtNif('12345678');
+        assert.equal(maskSensitive(`ref ${nif}`, { mode: 'enforce' }).text, `ref ${nif}`);
+        assert.match(maskSensitive(`NIF ${nif}`, { mode: 'enforce' }).text, /NIF \[REDACTED:pt_nif\]/);
+    });
+});
+
+describe('modes', () => {
+    const sample = POSITIVES.find(([id]) => id === 'github_token')[1];
+    test('off: untouched and nothing scanned', () => {
+        const res = maskSensitive(sample, { mode: 'off' });
+        assert.equal(res.text, sample);
+        assert.equal(res.total, 0);
+    });
+    test('unknown or missing mode behaves as off', () => {
+        assert.equal(normalizeMode('ENFORCE '), 'enforce');
+        assert.equal(normalizeMode('yes'), 'off');
+        assert.equal(normalizeMode(undefined), 'off');
+        assert.equal(maskSensitive(sample, {}).text, sample);
+    });
+    test('warn: text untouched, counts reported', () => {
+        const res = maskSensitive(sample, { mode: 'warn' });
+        assert.equal(res.text, sample);
+        assert.equal(res.redactions.github_token, 1);
+    });
+    test('enforce + blockClasses withholds the whole text', () => {
+        const res = maskSensitive(`before ${sample} after`, { mode: 'enforce', blockClasses: ['vcs-token'] });
+        assert.equal(res.text, '[BLOCKED:vcs-token]');
+        assert.equal(res.blocked, true);
+        const warn = maskSensitive(sample, { mode: 'warn', blockClasses: ['vcs-token'] });
+        assert.equal(warn.blocked, true);
+        assert.equal(warn.text, sample);
+    });
+    test('non-matching block class does not block', () => {
+        const res = maskSensitive(sample, { mode: 'enforce', blockClasses: ['private-key'] });
+        assert.equal(res.blocked, false);
+        assert.match(res.text, /REDACTED:github_token/);
+    });
+    test('enforce fails closed above maxBytes, warn does not alter', () => {
+        const big = 'a'.repeat(100);
+        assert.equal(maskSensitive(big, { mode: 'enforce', maxBytes: 50 }).text, '[REDACTED:dlp_oversize]');
+        assert.equal(maskSensitive(big, { mode: 'warn', maxBytes: 50 }).text, big);
+    });
+    test('non-string and empty input pass through', () => {
+        assert.equal(maskSensitive('', { mode: 'enforce' }).text, '');
+        assert.equal(maskSensitive(undefined, { mode: 'enforce' }).text, undefined);
+    });
+});
+
+describe('report never contains the value', () => {
+    test('JSON of the report has no secret material', () => {
+        const [, sample] = POSITIVES.find(([id]) => id === 'stripe_key');
+        const res = maskSensitive(sample, { mode: 'enforce' });
+        const { text, ...report } = res;
+        assert.ok(!JSON.stringify(report).includes('live_'));
+    });
+});
+
+describe('multiple hits and context', () => {
+    test('masks several secrets and keeps surrounding text', () => {
+        const gh = POSITIVES.find(([id]) => id === 'github_token')[1];
+        const mail = 'maria@acme-corp.pt';
+        const res = maskSensitive(`a ${gh} b ${mail} c ${gh}`, { mode: 'enforce' });
+        assert.equal(res.text, 'a [REDACTED:github_token] b [REDACTED:email] c [REDACTED:github_token]');
+        assert.deepEqual(res.redactions, { github_token: 2, email: 1 });
+    });
+    test('assignment keeps the key name, masks only the value', () => {
+        const res = maskSensitive('DB_PASSWORD=Sup3rS3cretValue', { mode: 'enforce' });
+        assert.equal(res.text, 'DB_PASSWORD=[REDACTED:generic_secret_assignment]');
+    });
+    test('URL credentials keep scheme and host', () => {
+        const res = maskSensitive('https://deploy:hunter2hunter2@git.example.com/o/r.git', { mode: 'enforce' });
+        assert.equal(res.text, 'https://[REDACTED:url_credentials]@git.example.com/o/r.git');
+    });
+    test('multi-line stack trace with one secret', () => {
+        const gh = POSITIVES.find(([id]) => id === 'github_token')[1];
+        const trace = `Error: boom\n  at a (x.js:1:1)\n  token=${gh}\n  at b (y.js:2:2)`;
+        const res = maskSensitive(trace, { mode: 'enforce' });
+        assert.ok(res.text.startsWith('Error: boom\n  at a (x.js:1:1)\n'));
+        assert.ok(res.text.endsWith('\n  at b (y.js:2:2)'));
+        assert.ok(!res.text.includes(gh));
+    });
+});
+
+describe('performance guard', () => {
+    test('1 MB of pathological input is scanned in bounded time', () => {
+        for (const chunk of ['a'.repeat(1_000_000), 'a.'.repeat(500_000), '1 '.repeat(500_000), 'x@'.repeat(300_000)]) {
+            const t = Date.now();
+            maskSensitive(chunk, { mode: 'enforce' });
+            assert.ok(Date.now() - t < 5000, `slow: ${Date.now() - t} ms`);
+        }
+    });
+});
+
+describe('maskDeep', () => {
+    const gh = POSITIVES.find(([id]) => id === 'github_token')[1];
+    test('enforce masks nested strings, keeps keys and non-strings', () => {
+        const input = { a: gh, n: 5, ok: true, nested: [{ m: `x ${gh}` }, null], [gh]: 'k' };
+        const res = maskDeep(input, { mode: 'enforce' });
+        assert.equal(res.value.a, '[REDACTED:github_token]');
+        assert.equal(res.value.n, 5);
+        assert.equal(res.value.nested[0].m, 'x [REDACTED:github_token]');
+        assert.equal(res.value.nested[1], null);
+        assert.equal(res.total, 2);
+        assert.equal(input.a, gh, 'input not mutated');
+    });
+    test('warn returns the original value but reports counts; off returns it untouched', () => {
+        const input = { a: gh };
+        const warn = maskDeep(input, { mode: 'warn' });
+        assert.equal(warn.value, input);
+        assert.equal(warn.total, 1);
+        const off = maskDeep(input, { mode: 'off' });
+        assert.equal(off.value, input);
+        assert.equal(off.total, 0);
+    });
+    test('circular structures do not hang', () => {
+        const o = { s: gh };
+        o.self = o;
+        const res = maskDeep(o, { mode: 'enforce' });
+        assert.equal(res.value.self, '[circular]');
+    });
+});

package/test/dlp/fixtures.js

@@ -0,0 +1,126 @@
+// Synthetic secrets only. Prefixes are split so no scanner (GitHub push protection,
+// trufflehog, our own DLP) flags this file; they are joined at runtime.
+import { createHash } from 'node:crypto';
+// Deterministic pseudo-random text (sha256 stream), so fixtures are stable but look random.
+const rnd = (alphabet, n, seed) => {
+    let out = '';
+    for (let i = 0; out.length < n; i++) {
+        const h = createHash('sha256').update(`${seed}:${i}`).digest();
+        for (const byte of h) { out += alphabet[byte % alphabet.length]; if (out.length === n) break; }
+    }
+    return out;
+};
+const AZ = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const AZ09 = AZ + '0123456789';
+const ALNUM = AZ09 + 'abcdefghijklmnopqrstuvwxyz';
+const HEX = '0123456789abcdef';
+const B64U = ALNUM + '-_';
+const B64 = ALNUM + '+/';
+
+/** [ruleId, sample text containing exactly one secret, the secret substring] */
+export const POSITIVES = [
+    ['pem_private_key', `key:\n${'-----BEGIN RSA PRIV' + 'ATE KEY-----'}\nMIIEowIBAAKCAQEAsynthetic${rnd(B64, 60, 1)}\n${'-----END RSA PRIV' + 'ATE KEY-----'}\nafter`, 'MIIEowIBAAKCAQEAsynthetic'],
+    ['pem_private_key', `${'-----BEGIN OPENSSH PRIV' + 'ATE KEY-----'}\nb3BlbnNzaC1rZXktdjEAAAAA${rnd(B64, 40, 2)}\n${'-----END OPENSSH PRIV' + 'ATE KEY-----'}`, 'b3BlbnNzaC1rZXktdjEAAAAA'],
+    ['pem_private_key', `${'-----BEGIN PRIV' + 'ATE KEY-----'}\ntruncated${rnd(B64, 30, 3)}`, 'truncated'],
+    ['aws_access_key_id', `id=${'AKI' + 'A'}${rnd(AZ09, 16, 4)} region=eu`, 'AKIA'],
+    ['aws_access_key_id', `temp ${'AS' + 'IA'}${rnd(AZ09, 16, 5)}`, 'ASIA'],
+    ['aws_secret_access_key', `aws_secret_access_key = "${rnd(B64, 40, 6)}"`, null],
+    ['gcp_api_key', `url?key=${'AI' + 'za'}${rnd(B64U, 35, 7)}&x=1`, 'AIza'],
+    ['gcp_oauth_token', `tok ${'ya' + '29.'}${rnd(B64U, 40, 8)}`, 'ya29.'],
+    ['gcp_oauth_client_secret', `secret ${'GOC' + 'SPX-'}${rnd(B64U, 28, 9)}`, 'GOCSPX-'],
+    ['azure_storage_account_key', `DefaultEndpointsProtocol=https;AccountName=acme;AccountKey=${rnd(B64, 86, 10)}==;EndpointSuffix=core.windows.net`, null],
+    ['digitalocean_token', `${'do' + 'p_v1_'}${rnd(HEX, 64, 11)}`, 'dop_v1_'],
+    ['github_token', `${'gh' + 'p_'}${rnd(ALNUM, 36, 12)}`, 'ghp_'],
+    ['github_fine_grained_pat', `${'github' + '_pat_'}${rnd(ALNUM, 40, 13)}`, 'github_pat_'],
+    ['gitlab_pat', `${'gl' + 'pat-'}${rnd(B64U, 22, 14)}`, 'glpat-'],
+    ['npm_token', `//registry.npmjs.org/:_authToken=${'np' + 'm_'}${rnd(ALNUM, 36, 15)}`, null],
+    ['pypi_token', `${'py' + 'pi-AgEIcHlwaS5vcmc'}${rnd(B64U, 60, 16)}`, 'pypi-'],
+    ['stripe_key', `${'sk_' + 'live_'}${rnd(ALNUM, 24, 17)}`, 'sk_live_'],
+    ['stripe_key', `${'rk_' + 'test_'}${rnd(ALNUM, 24, 18)}`, 'rk_test_'],
+    ['stripe_webhook_secret', `${'wh' + 'sec_'}${rnd(ALNUM, 32, 19)}`, 'whsec_'],
+    ['shopify_token', `${'shp' + 'at_'}${rnd(HEX, 32, 20)}`, 'shpat_'],
+    ['slack_token', `${'xo' + 'xb-'}1234567890-${rnd(ALNUM, 24, 21)}`, 'xoxb-'],
+    ['slack_webhook', `${'https://hooks.' + 'slack.com/services/'}T${rnd(AZ09, 8, 22)}/B${rnd(AZ09, 8, 23)}/${rnd(ALNUM, 24, 24)}`, 'hooks.slack.com'],
+    ['discord_webhook', `${'https://discord' + '.com/api/webhooks/'}123456789012345678/${rnd(B64U, 40, 25)}`, 'discord.com/api'],
+    ['sendgrid_key', `${'S' + 'G.'}${rnd(B64U, 22, 26)}.${rnd(B64U, 43, 27)}`, 'SG.'],
+    ['twilio_api_key', `${'S' + 'K'}${rnd(HEX, 32, 28)}`, null],
+    ['mailgun_key', `${'ke' + 'y-'}${rnd(HEX, 32, 29)}`, 'key-'],
+    ['huggingface_token', `${'h' + 'f_'}${rnd(ALNUM, 36, 30)}`, 'hf_'],
+    ['telegram_bot_token', `bot 123456789:${'A' + 'A'}${rnd(B64U, 33, 31)}`, null],
+    ['anthropic_key', `${'sk-' + 'ant-api03-'}${rnd(B64U, 40, 32)}`, 'sk-ant-'],
+    ['openai_key', `${'sk' + '-proj-'}${rnd(ALNUM, 40, 33)}9`, 'sk-proj-'],
+    ['jwt', `token ${'ey' + 'J'}hbGciOiJIUzI1NiJ9.${'ey' + 'J'}zdWIiOiIxMjM0NTY3ODkwIn0.${rnd(B64U, 43, 34)}`, null],
+    ['bearer_token', `Authorization: Bearer ${rnd(B64U, 32, 35)}`, null],
+    ['basic_auth_header', `Authorization: Basic ${Buffer.from('svc:' + rnd(ALNUM, 12, 36)).toString('base64')}`, null],
+    ['db_connection_string', `DATABASE_URL=${'postgres' + 'ql'}://app:${rnd(ALNUM, 14, 37)}@db.internal:5432/app`, null],
+    ['db_connection_string', `${'mongodb+' + 'srv'}://user:${rnd(ALNUM, 12, 38)}@cluster0.example.mongodb.net/db`, null],
+    ['db_connection_string', `${'red' + 'is'}://:${rnd(ALNUM, 16, 39)}@cache.internal:6379`, null],
+    ['jdbc_password', `jdbc:postgresql://db:5432/app?user=app&password=${rnd(ALNUM, 12, 40)}&ssl=true`, null],
+    ['ado_connection_password', `Server=tcp:db,1433;Database=app;User Id=sa;Password=${rnd(ALNUM, 12, 41)}1!;Encrypt=True`, null],
+    ['url_credentials', `git clone https://deploy:${rnd(ALNUM, 20, 42)}@git.example.com/org/repo.git`, null],
+    ['generic_secret_assignment', `api_key = "${rnd(ALNUM, 24, 43)}"`, null],
+    ['generic_secret_assignment', `DB_PASSWORD: ${rnd(ALNUM, 10, 44)}#9`, null],
+    ['generic_secret_assignment', `"client_secret": "${rnd(B64U, 30, 45)}"`, null],
+    ['email', 'contact maria.silva+ops@acme-corp.pt for access', 'maria.silva+ops@acme-corp.pt'],
+    ['email', 'user JOAO.Costa@sub.empresa.co.uk failed login', 'JOAO.Costa@sub.empresa.co.uk'],
+    ['iban', 'IBAN PT50 0002 0123 1234 5678 9015 4 transfer', 'PT50 0002 0123 1234 5678 9015 4'],
+    ['iban', 'conta GB82WEST12345698765432 ok', 'GB82WEST12345698765432'],
+    ['credit_card', 'card 4111 1111 1111 1111 declined', '4111 1111 1111 1111'],
+    ['credit_card', 'pan=5555555555554444;', '5555555555554444'],
+    ['pt_nif', 'NIF: 123456789 do cliente', '123456789'],
+    ['pt_nif', 'contribuinte n.º 500000000', '500000000'],
+    ['phone_international', 'ligar +351 912 345 678 urgente', '+351 912 345 678'],
+    ['phone_international', 'tel 00351-213-456-789.', '00351-213-456-789'],
+    ['high_entropy_blob', `blob=${rnd(B64, 48, 46)}Zq9`, null],
+];
+
+/** Text that must NOT be altered (false-positive corpus: ordinary code, hashes, ids). */
+export const NEGATIVES = [
+    'const password = getPassword();',
+    'password: string;',
+    'token = process.env.API_TOKEN',
+    'const secret = config.secret',
+    'api_key = "${API_KEY}"',
+    'client_secret: <your-client-secret>',
+    'password = ""',
+    'if (!token) throw new Error("token required")',
+    'authToken: undefined',
+    'import { sanitizedChildEnv } from "../utils/child-env.js";',
+    'commit 283f6c2a1b9e4d7c5f0a8b6e3d2c1f9a8b7c6d5e merged',
+    'sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
+    'id 3f2504e0-4f89-41d3-9a0c-0305e82c3301 created',
+    'integrity "sha512-Q7DGnIuEtPSmGZ6JGVkLqUIxhEbuPDtCXXXgEngqNBhwxXrvTjTU0wsyxXfT3qlJl+ZRHU6h3cPRV0vg3s2uHQ=="',
+    '/Users/dev/projects/very-long-directory-name/another-long-segment/file-name-here.js',
+    'veryLongCamelCaseIdentifierNameThatKeepsGoingAndGoingForeverAndEver',
+    'see logo@2x.png and icon@3x.webp',
+    'user@host:~$ ls',
+    'import x from "@types/node"; npm i @scope/pkg',
+    'mail admin@example.com for docs',
+    'version +1.2.3 build 20261028 pid 123456789 ts=1698480000',
+    'timestamp 2026-10-28T09:00:00+01:00',
+    'order 4111 1111 1111 1112 failed luhn',
+    'number 123456789012345 is a plain id',
+    'NIF: 123456780 invalido',
+    'IBAN PT50 0002 0123 1234 5678 9015 5 wrong check digit',
+    'https://github.com/VISIONHAMMER/deepdebug-local-agent/pull/52',
+    'postgresql://localhost:5432/app',
+    'jdbc:postgresql://db:5432/app?ssl=true',
+    'Bearer token missing',
+    'sk-learn is a library; sk-short',
+    'The quick brown fox jumps over the lazy dog 1234.',
+    'phone format example: +1 (see docs)',
+    'java.lang.NullPointerException at com.acme.Foo.bar(Foo.java:42)',
+    'ERROR 2026-10-28 10:00:01 retry 3/5 host=db-01 latency=233ms',
+    'secret_manager.get_secret_version(name)',
+    'git clone git@github.com:VISIONHAMMER/repo.git',
+    'url = `https://${user}:${token}@github.com/o/r.git`',
+    'gcloud secrets versions access latest --secret=pg-password-qa',
+    'password_hash VARCHAR(255) NOT NULL',
+];
+
+export function validPtNif(prefix8) {
+    let sum = 0;
+    for (let i = 0; i < 8; i++) sum += Number(prefix8[i]) * (9 - i);
+    const c = 11 - (sum % 11);
+    return prefix8 + String(c >= 10 ? 0 : c);
+}