deepdebug-local-agent 1.1.0 → 1.3.0

package/src/ws-channel/metadata-guard.js

@@ -0,0 +1,78 @@
+/**
+ * metadata-guard.js - the metadata-only outbound filter for the Local Agent WS
+ * channel (T4-10). A NEW filtering module: it opens no socket itself and
+ * returns null when the flag is off, so with the flag off nothing changes.
+ *
+ * Every outbound message passes: size limit -> rate limit -> allowlist
+ * validation. A violation is dropped, logged WITHOUT its content (type, field
+ * name, reason code, byte size) and, for command replies, answered with a
+ * metadata-only error so the control plane does not wait for a timeout.
+ */
+import { METADATA_COMMANDS, validateOutbound, projectResponse } from "./allowlist.js";
+import { createTransitGuard } from "./transit-guard.js";
+
+export function createWsMetadataGuard({ config, transit, logger = console, now = Date.now } = {}) {
+    if (!config || config.mode !== "enforce") return null; // flag off: no guard, no behaviour change
+    const guard = transit || createTransitGuard({ now });
+    const stats = { sent: 0, blocked: 0 };
+
+    // Content-free log line: only codes/names/sizes, never values.
+    const logBlocked = (info) => {
+        stats.blocked++;
+        logger.warn(`[ws-metadata] BLOCKED ${JSON.stringify(info)}`);
+    };
+
+    /** Serialises + checks one message. @returns {string|null} the frame to send, null if blocked. */
+    function frame(msg) {
+        const v = validateOutbound(msg);
+        if (!v.ok) { logBlocked({ reason: v.reason, type: v.type || null, field: v.field || null }); return null; }
+        const serialized = JSON.stringify(msg);
+        const size = guard.checkSize(serialized);
+        if (!size.ok) { logBlocked({ reason: size.reason, type: v.type }); return null; }
+        const rate = guard.checkRate();
+        if (!rate.ok) { logBlocked({ reason: rate.reason, type: v.type }); return null; }
+        stats.sent++;
+        return serialized;
+    }
+
+    const errorFrame = (requestId, command, errorCode) =>
+        frame({ requestId, command, ok: false, errorCode });
+
+    return {
+        mode: "enforce",
+        stats,
+        /** Spontaneous (non-reply) messages: register, hello, status, cost. */
+        frameMessage: frame,
+        /**
+         * Inbound command gate: legacy content commands never execute in
+         * metadata-only mode. @returns {{ok:true}|{ok:false,errorFrame:string|null}}
+         */
+        admitCommand(requestId, command) {
+            if (!METADATA_COMMANDS.includes(command)) {
+                logBlocked({ reason: "command-not-allowed", type: "command", field: "command" });
+                return { ok: false, errorFrame: errorFrame(requestId, command, "blocked_metadata_only") };
+            }
+            const a = guard.admitRequest(requestId);
+            if (!a.ok) return { ok: false, errorFrame: errorFrame(requestId, command, "rate_limited") };
+            return { ok: true };
+        },
+        /** Reply to an admitted command: projected onto the allowlist, TTL-checked, validated. */
+        frameResponse(requestId, command, result) {
+            const t = guard.consumeRequest(requestId);
+            if (!t.ok) {
+                logBlocked({ reason: t.reason, type: "response" });
+                return null; // nothing to reply to / too late: drop silently (no queueing)
+            }
+            const p = projectResponse(requestId, command, result);
+            if (!p.ok) {
+                logBlocked({ reason: p.reason, type: "response", field: p.field || null });
+                return errorFrame(requestId, command, "blocked_metadata_only");
+            }
+            return frame(p.message) || errorFrame(requestId, command, "blocked_metadata_only");
+        },
+        /** Error reply for a request that never reached execution (e.g. bad signature). */
+        frameError(requestId, command, errorCode) {
+            return errorFrame(requestId, command, errorCode);
+        },
+    };
+}

package/src/ws-channel/policy-offline.js

@@ -0,0 +1,40 @@
+/**
+ * policy-offline.js - D19: PolicyGate per action; offline = DENY (fail-closed).
+ *
+ * Actions that need a PolicyGate decision (a platform-authored tool command or
+ * a human-approval token) are denied while the agent has no live connection to
+ * the control plane. Purely local, allowlisted commands do not need PolicyGate
+ * and are unaffected. Active only when LOCAL_AGENT_WS_METADATA_ONLY=enforce.
+ */
+
+/** decideExec().via prefixes that mean "PolicyGate authorised this". */
+const GATED_VIA_PREFIXES = Object.freeze(["platform-tool:", "human-approval:"]);
+
+export const OFFLINE_DENY_REASON = "PolicyGate unreachable: no connection to the control plane (offline = DENY)";
+
+export function requiresPolicyGate(via) {
+    return typeof via === "string" && GATED_VIA_PREFIXES.some((p) => via.startsWith(p));
+}
+
+/**
+ * Generic per-action decision.
+ * @returns {{decision:"ALLOW"|"DENY",reason?:string}}
+ */
+export function decideOffline({ gated, online }) {
+    if (gated && !online) return { decision: "DENY", reason: OFFLINE_DENY_REASON };
+    return { decision: "ALLOW" };
+}
+
+/**
+ * Builds the guard plugged into exec-policy (`cfg.offlineGuard`): receives a
+ * decideExec() result and downgrades PolicyGate-backed ALLOWs to DENY when offline.
+ */
+export function createOfflinePolicyGuard({ connection, onDeny = () => {} }) {
+    return function offlineGuard(decision) {
+        if (!decision || !decision.allow || !requiresPolicyGate(decision.via)) return decision;
+        const verdict = decideOffline({ gated: true, online: connection.isOnline() });
+        if (verdict.decision === "ALLOW") return decision;
+        onDeny({ via: decision.via.split(":")[0] });
+        return { allow: false, status: 403, reason: verdict.reason, via: "policy-gate-offline" };
+    };
+}

package/src/ws-channel/transit-guard.js

@@ -0,0 +1,55 @@
+/**
+ * transit-guard.js - D17 controls for content/metadata in transit through the
+ * control plane: nothing is persisted or queued here, no payload is ever
+ * logged, replies are only sent for known requests inside a TTL, and size and
+ * rate are bounded.
+ */
+export const DEFAULT_LIMITS = Object.freeze({
+    maxMessageBytes: 4096,
+    requestTtlMs: 60_000,
+    maxInFlight: 256,
+    rateWindowMs: 10_000,
+    rateMax: 200,
+});
+
+export function createTransitGuard({ now = Date.now, limits = {} } = {}) {
+    const lim = { ...DEFAULT_LIMITS, ...limits };
+    const inFlight = new Map(); // requestId -> expiresAt (in memory only; never persisted)
+    let windowStart = now();
+    let windowCount = 0;
+
+    const sweep = () => {
+        const t = now();
+        for (const [id, exp] of inFlight) if (exp <= t) inFlight.delete(id);
+    };
+
+    return {
+        limits: lim,
+        /** Registers an inbound request. @returns {{ok:true}|{ok:false,reason:string}} */
+        admitRequest(requestId) {
+            sweep();
+            if (inFlight.size >= lim.maxInFlight) return { ok: false, reason: "too-many-in-flight" };
+            inFlight.set(requestId, now() + lim.requestTtlMs);
+            return { ok: true };
+        },
+        /** A reply may only be sent once, to a known request, before its TTL. */
+        consumeRequest(requestId) {
+            const exp = inFlight.get(requestId);
+            if (exp === undefined) return { ok: false, reason: "unknown-request" };
+            inFlight.delete(requestId);
+            if (exp <= now()) return { ok: false, reason: "request-expired" };
+            return { ok: true };
+        },
+        checkSize(serialized) {
+            return Buffer.byteLength(serialized, "utf8") <= lim.maxMessageBytes ? { ok: true } : { ok: false, reason: "message-too-large" };
+        },
+        checkRate() {
+            const t = now();
+            if (t - windowStart >= lim.rateWindowMs) { windowStart = t; windowCount = 0; }
+            if (windowCount >= lim.rateMax) return { ok: false, reason: "rate-limited" };
+            windowCount++;
+            return { ok: true };
+        },
+        pending: () => inFlight.size,
+    };
+}

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);
+}

package/test/dlp/index.test.js

@@ -0,0 +1,166 @@
+import { test, describe, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+    protectEgress, protectEgressAsync, protectDeep, dlpConfigFromEnv, getDlpStats, resetDlpStats,
+    DENIED, rulesetHash, RULESET_VERSION,
+} from '../../src/dlp/index.js';
+import { IncidentForwarder } from '../../src/siblings/incident-forwarder.js';
+import { POSITIVES } from './fixtures.js';
+
+const GH = POSITIVES.find(([id]) => id === 'github_token')[1];
+const KEY = POSITIVES.find(([id]) => id === 'pem_private_key')[1];
+const env = (mode, extra = {}) => ({ LOCAL_AGENT_DLP_MODE: mode, ...extra });
+
+beforeEach(() => resetDlpStats());
+
+describe('config', () => {
+    test('default is off', () => {
+        assert.equal(dlpConfigFromEnv({}).mode, 'off');
+        assert.deepEqual(dlpConfigFromEnv({}).blockClasses, []);
+    });
+    test('parses mode, block classes (unknown ignored) and max bytes', () => {
+        const c = dlpConfigFromEnv(env('enforce', { LOCAL_AGENT_DLP_BLOCK_CLASSES: 'private-key, nope ,cloud-credential', LOCAL_AGENT_DLP_MAX_BYTES: '1000' }));
+        assert.equal(c.mode, 'enforce');
+        assert.deepEqual(c.blockClasses, ['private-key', 'cloud-credential']);
+        assert.equal(c.maxBytes, 1000);
+        assert.equal(dlpConfigFromEnv(env('enforce', { LOCAL_AGENT_DLP_MAX_BYTES: 'x' })).maxBytes, 2_000_000);
+    });
+});
+
+describe('protectEgress', () => {
+    test('off (default): identical output and no counters', () => {
+        const r = protectEgress(GH, { env: {} });
+        assert.equal(r.text, GH);
+        assert.equal(getDlpStats({}).scanned, 0);
+    });
+    test('warn: identical output, counters move', () => {
+        const r = protectEgress(GH, { env: env('warn') });
+        assert.equal(r.text, GH);
+        assert.equal(r.total, 1);
+        assert.equal(getDlpStats(env('warn')).dlp_redactions_total.github_token, 1);
+    });
+    test('enforce: redacted, stats by rule, local log has counts but not the value', () => {
+        const logs = [];
+        const r = protectEgress(`x ${GH}`, { env: env('enforce'), source: 'unit', log: (o, m) => logs.push([o, m]) });
+        assert.equal(r.text, 'x [REDACTED:github_token]');
+        assert.equal(logs.length, 1);
+        assert.deepEqual(logs[0][0].rules, { github_token: 1 });
+        assert.ok(!JSON.stringify(logs).includes(GH));
+        const stats = getDlpStats(env('enforce'));
+        assert.equal(stats.mode, 'enforce');
+        assert.equal(stats.ruleset_version, RULESET_VERSION);
+        assert.equal(stats.ruleset_hash, rulesetHash());
+        assert.deepEqual(stats.dlp_redactions_total, { github_token: 1 });
+        assert.ok(!JSON.stringify(stats).includes(GH));
+    });
+    test('clean text produces no log record', () => {
+        let called = 0;
+        protectEgress('hello world', { env: env('enforce'), log: () => { called++; } });
+        assert.equal(called, 0);
+    });
+    test('a throwing logger never breaks the data path', () => {
+        const r = protectEgress(GH, { env: env('enforce'), log: () => { throw new Error('boom'); } });
+        assert.equal(r.text, '[REDACTED:github_token]');
+    });
+    test('block class withholds everything and counts', () => {
+        const r = protectEgress(`a ${KEY} b`, { env: env('enforce', { LOCAL_AGENT_DLP_BLOCK_CLASSES: 'private-key' }) });
+        assert.equal(r.text, '[BLOCKED:private-key]');
+        assert.equal(r.blocked, true);
+        assert.equal(getDlpStats(env('enforce')).blocked, 1);
+    });
+    test('oversize fails closed in enforce', () => {
+        const r = protectEgress('a'.repeat(200), { env: env('enforce', { LOCAL_AGENT_DLP_MAX_BYTES: '100' }) });
+        assert.equal(r.text, '[REDACTED:dlp_oversize]');
+    });
+});
+
+describe('protectEgressAsync (PolicyGate, D19)', () => {
+    test('enforce without policyDecision just masks', async () => {
+        const r = await protectEgressAsync(GH, { env: env('enforce') });
+        assert.equal(r.text, '[REDACTED:github_token]');
+    });
+    test('ALLOW lets masked content out', async () => {
+        const r = await protectEgressAsync(`x ${GH}`, { env: env('enforce'), policyDecision: async () => 'ALLOW' });
+        assert.equal(r.text, 'x [REDACTED:github_token]');
+        assert.equal(r.denied, false);
+    });
+    for (const [name, fn] of [
+        ['DENY', async () => 'DENY'],
+        ['unknown answer', async () => 'MAYBE'],
+        ['undefined (no answer)', async () => undefined],
+        ['offline (throws)', async () => { throw new Error('ECONNREFUSED'); }],
+        ['sync throw', () => { throw new Error('x'); }],
+    ]) {
+        test(`${name} = DENY`, async () => {
+            const r = await protectEgressAsync('clean text', { env: env('enforce'), policyDecision: fn });
+            assert.equal(r.text, DENIED);
+            assert.equal(r.denied, true);
+        });
+    }
+    test('timeout = DENY', async () => {
+        const r = await protectEgressAsync('clean', { env: env('enforce'), timeoutMs: 20, policyDecision: () => new Promise(() => {}) });
+        assert.equal(r.denied, true);
+    });
+    test('policyDecision is ignored when the flag is off or warn', async () => {
+        for (const m of ['off', 'warn']) {
+            const r = await protectEgressAsync('clean', { env: env(m), policyDecision: async () => 'DENY' });
+            assert.equal(r.text, 'clean');
+            assert.equal(r.denied, false);
+        }
+    });
+});
+
+describe('protectDeep', () => {
+    test('off returns the same reference', () => {
+        const v = { a: GH };
+        assert.equal(protectDeep(v, { env: {} }).value, v);
+    });
+    test('enforce masks nested payloads', () => {
+        const r = protectDeep({ a: [GH], b: { c: 'ok' } }, { env: env('enforce') });
+        assert.deepEqual(r.value, { a: ['[REDACTED:github_token]'], b: { c: 'ok' } });
+        assert.equal(getDlpStats(env('enforce')).dlp_redactions_total.github_token, 1);
+    });
+});
+
+describe('integration: incident forwarder (log excerpts leaving the network)', () => {
+    const NOOP_LOGGER = { info() {}, warn() {}, error() {}, debug() {} };
+    const evt = (message) => ({ adapter: 'sap', errorCode: 'E1', file: '/logs/a', message, source: 'svc', timestamp: '2026-10-28T10:00:00Z' });
+    const prev = process.env.LOCAL_AGENT_DLP_MODE;
+    const restore = () => { if (prev === undefined) delete process.env.LOCAL_AGENT_DLP_MODE; else process.env.LOCAL_AGENT_DLP_MODE = prev; };
+
+    async function sendOne(message) {
+        const bodies = [];
+        const f = new IncidentForwarder({
+            logger: NOOP_LOGGER,
+            suppressor: { shouldSuppress: () => false },
+            fetchImpl: async (_u, init) => { bodies.push(JSON.parse(init.body)); return { ok: true, status: 200 }; },
+        });
+        f.configure({ gatewayUrl: 'http://gw.invalid', apiKey: 'k', tenantId: 't' });
+        f.handleAdapterEvent(evt(message), 'sap');
+        await f.flush();
+        return bodies[0];
+    }
+
+    test('flag off: payload is byte-identical to the original message', async () => {
+        delete process.env.LOCAL_AGENT_DLP_MODE;
+        try {
+            const body = await sendOne(`login failed token=${GH} user maria@acme-corp.pt`);
+            assert.equal(body.message, `login failed token=${GH} user maria@acme-corp.pt`);
+        } finally { restore(); }
+    });
+    test('enforce: secrets and e-mails are masked before the POST', async () => {
+        process.env.LOCAL_AGENT_DLP_MODE = 'enforce';
+        try {
+            const body = await sendOne(`login failed ${GH} user maria@acme-corp.pt`);
+            assert.equal(body.message, 'login failed [REDACTED:github_token] user [REDACTED:email]');
+            assert.equal(body.service, 'svc');
+        } finally { restore(); }
+    });
+    test('warn: payload unchanged', async () => {
+        process.env.LOCAL_AGENT_DLP_MODE = 'warn';
+        try {
+            const body = await sendOne(`x ${GH}`);
+            assert.equal(body.message, `x ${GH}`);
+        } finally { restore(); }
+    });
+});