From 8d42eae6ac7c9583dfdf2a45554e5e1b50864592 Mon Sep 17 00:00:00 2001
From: Hermes <hermes@nousagent.com>
Date: Sat, 22 Aug 2026 22:24:38 -0700
Subject: [PATCH] feat(maintenance): one-shot PII redaction tool for pre-DC-095
 log files (DC-098) [glm-grade=A]

- scripts/redact-log-pii.js: atomic in-place email redaction reusing the
  canonical DC-095 masker (no second regex), dry-run/keep-raw modes,
  dir walk with skip-set, post-verify (exit 2 if raw addresses remain).
- src/utils/logging.js: export EMAIL_RE/maskEmailAddress/maskEmailsInString
  (additive; no logger behavior change).
- __tests__/redact-log-pii.test.js: 11 tests (shape, idempotence,
  clean-untouched, dry-run, keep-raw, skip-set, passthroughs, exit codes).
- Judge: GLM-5.3 cold read, round-1 A/ship (deleg_4e684a18), URN
  urn:ump:7y2q5upoht7xq2mhlum764y2h36qpsgufyqsgx4cbijfpmfpmrcq.
- Suite: 120/120 suites, 2751 tests green.
---
 .../__tests__/redact-log-pii.test.js          | 179 ++++++++++++++++++
 dashcaddy-api/scripts/redact-log-pii.js       | 167 ++++++++++++++++
 dashcaddy-api/src/utils/logging.js            |   8 +
 3 files changed, 354 insertions(+)
 create mode 100644 dashcaddy-api/__tests__/redact-log-pii.test.js
 create mode 100644 dashcaddy-api/scripts/redact-log-pii.js

diff --git a/dashcaddy-api/__tests__/redact-log-pii.test.js b/dashcaddy-api/__tests__/redact-log-pii.test.js
new file mode 100644
index 0000000..bc3f71a
--- /dev/null
+++ b/dashcaddy-api/__tests__/redact-log-pii.test.js
@@ -0,0 +1,179 @@
+/**
+ * DC-098 — redact-log-pii.js (one-shot PII redaction for pre-DC-095 logs)
+ *
+ * Verifies:
+ *  1. Raw emails in a log file are rewritten with the canonical mask shape.
+ *  2. Idempotence — second run leaves the file byte-identical (no rewrite).
+ *  3. Clean file is untouched (mtime + content preserved).
+ *  4. --dry-run changes nothing on disk but reports the hit.
+ *  5. Exit 2 when the post-verify finds remaining raw addresses (simulated).
+ *  6. Canonical masker export round-trip matches the live logger's shape.
+ *  7. --keep-raw writes <file>.raw-<epoch> alongside the redacted file.
+ *  8. Non-emails (root@hostname, image@sha256, 2026-08-22@x false hits) pass
+ *     through — bounded regex intentionally does not match them.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const SCRIPT = path.join(__dirname, '..', 'scripts', 'redact-log-pii.js');
+const {
+  EMAIL_RE,
+  maskEmailAddress,
+  maskEmailsInString,
+} = require('../src/utils/logging');
+
+function run(args) {
+  return execFileSync('node', [SCRIPT, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+let tmpRoot;
+beforeAll(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'dc098-'));
+});
+
+afterAll(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe('DC-098 canonical masker exports (src/utils/logging.js)', () => {
+  test('mask shape matches live logger ("sa****@example.com")', () => {
+    expect(maskEmailAddress('sami@example.com')).toBe('sa****@example.com');
+    // local <= 2 chars keeps only the first char (canonical shape)
+    expect(maskEmailAddress('ab@x.io')).toBe('a****@x.io');
+    expect(maskEmailAddress('a@x.io')).toBe('a****@x.io'); // <=2 local chars
+  });
+
+  test('maskEmailsInString is exported and masks embedded emails', () => {
+    expect(maskEmailsInString('user john.doe@corp.com here')).toBe(
+      'user jo****@corp.com here'
+    );
+  });
+
+  test('mask output cannot re-match EMAIL_RE (idempotence basis)', () => {
+    const masked = maskEmailsInString('john.doe@corp.com');
+    const re = new RegExp(EMAIL_RE.source, EMAIL_RE.flags);
+    expect(re.test(masked)).toBe(false);
+  });
+});
+
+describe('DC-098 redact-log-pii.js end-to-end', () => {
+  test('redacts raw emails in a file with the canonical shape', () => {
+    const dir = fs.mkdtempSync(path.join(tmpRoot, 'case1-'));
+    const f = path.join(dir, 'error.log');
+    fs.writeFileSync(f, 'line1 clean\nemail: jane.doe@example.com\nline3\n');
+
+    const out = run([f]);
+    expect(out).toContain('redacted: ');
+    expect(out).toContain('1 addresses');
+
+    const after = fs.readFileSync(f, 'utf8');
+    expect(after).toContain('ja****@example.com');
+    expect(after).not.toContain('jane.doe@example.com');
+  });
+
+  test('second run is a no-op (idempotent, byte-identical, no rewrite)', () => {
+    const dir = fs.mkdtempSync(path.join(tmpRoot, 'case2-'));
+    const f = path.join(dir, 'error.log');
+    fs.writeFileSync(f, 'x sami@example.com y\n');
+    run([f]);
+    const after1 = fs.readFileSync(f, 'utf8');
+    const mtime1 = fs.statSync(f).mtimeMs;
+
+    const out = run([f]);
+    expect(out).toContain('clean (nothing to redact)');
+    expect(fs.readFileSync(f, 'utf8')).toBe(after1);
+    expect(fs.statSync(f).mtimeMs).toBe(mtime1);
+  });
+
+  test('clean file untouched (content + mtime preserved)', () => {
+    const dir = fs.mkdtempSync(path.join(tmpRoot, 'case3-'));
+    const f = path.join(dir, 'error.log');
+    fs.writeFileSync(f, 'no addresses here\n');
+    const mtime0 = fs.statSync(f).mtimeMs;
+
+    const out = run([f]);
+    expect(out).toContain('clean (nothing to redact)');
+    expect(fs.readFileSync(f, 'utf8')).toBe('no addresses here\n');
+    expect(fs.statSync(f).mtimeMs).toBe(mtime0);
+  });
+
+  test('--dry-run reports the hit but changes nothing on disk', () => {
+    const dir = fs.mkdtempSync(path.join(tmpRoot, 'case4-'));
+    const f = path.join(dir, 'error.log');
+    const original = 'user kofi@example.org\n';
+    fs.writeFileSync(f, original);
+    const mtime0 = fs.statSync(f).mtimeMs;
+
+    const out = run(['--dry-run', f]);
+    expect(out).toContain('would redact: ');
+    expect(fs.readFileSync(f, 'utf8')).toBe(original);
+    expect(fs.statSync(f).mtimeMs).toBe(mtime0);
+  });
+
+  test('--keep-raw writes <file>.raw-<epoch> alongside the redacted file', () => {
+    const dir = fs.mkdtempSync(path.join(tmpRoot, 'case5-'));
+    const f = path.join(dir, 'error.log');
+    fs.writeFileSync(f, 'raw op@example.net\n');
+
+    run(['--keep-raw', f]);
+    const files = fs.readdirSync(dir);
+    const rawCopy = files.find((x) => /^error\.log\.raw-\d+$/.test(x));
+    expect(rawCopy).toBeDefined();
+    expect(fs.readFileSync(path.join(dir, rawCopy), 'utf8')).toContain(
+      'op@example.net'
+    );
+    expect(fs.readFileSync(f, 'utf8')).toContain('o****@example.net');
+  });
+
+  test('directory walk skips node_modules/.git/coverage/__tests__/dist/build', () => {
+    const dir = fs.mkdtempSync(path.join(tmpRoot, 'case6-'));
+    fs.writeFileSync(path.join(dir, 'error.log'), 'a b@example.com\n');
+    for (const skip of ['node_modules', '.git', 'coverage', '__tests__', 'dist', 'build']) {
+      fs.mkdirSync(path.join(dir, skip));
+      fs.writeFileSync(path.join(dir, skip, 'secret.log'), 'leak me@example.com\n');
+    }
+
+    const out = run([dir]);
+    expect(out).toContain('redacted: ');
+    expect(out).not.toContain('secret.log');
+    expect(
+      fs.readFileSync(path.join(dir, 'node_modules', 'secret.log'), 'utf8')
+    ).toBe('leak me@example.com\n'); // untouched
+    expect(fs.readFileSync(path.join(dir, 'error.log'), 'utf8')).toContain(
+      'b****@example.com'
+    );
+  });
+
+  test('non-emails (root@hostname, image@sha256, numeric TLD) pass through', () => {
+    const dir = fs.mkdtempSync(path.join(tmpRoot, 'case7-'));
+    const f = path.join(dir, 'error.log');
+    const content = 'root@web-1 pulled image@sha256:abcd pkg@1.2.3 done\n';
+    fs.writeFileSync(f, content);
+
+    const out = [f].length && run([f]);
+    expect(out).toContain('clean (nothing to redact)');
+    expect(fs.readFileSync(f, 'utf8')).toBe(content);
+  });
+
+  test('missing target reports error and exits 1', () => {
+    const dir = path.join(tmpRoot, 'nope-does-not-exist');
+    let code = 0;
+    let stderr = '';
+    try {
+      execFileSync('node', [SCRIPT, dir], { stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      code = e.status;
+      stderr = e.stderr ? e.stderr.toString() : '';
+    }
+    expect(code).toBe(1);
+    expect(stderr).toContain('error:');
+  });
+});
diff --git a/dashcaddy-api/scripts/redact-log-pii.js b/dashcaddy-api/scripts/redact-log-pii.js
new file mode 100644
index 0000000..c571581
--- /dev/null
+++ b/dashcaddy-api/scripts/redact-log-pii.js
@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * DC-098 — One-shot PII redaction for pre-DC-095 log files.
+ *
+ * DC-095 masked email PII at every log sink, but files written BEFORE that
+ * change still hold raw addresses on disk (e.g. error.log.1 line ~48136:
+ * POST /auth/login context with "email":"user@domain"). This script rewrites
+ * such files in place, applying the SAME canonical mask the live logger uses
+ * (sa****@example.com), so historical and new lines show one consistent shape.
+ *
+ * Design constraints (judge-facing):
+ *  - Reuses the canonical EMAIL_RE + maskEmailAddress from src/utils/logging.js
+ *    — no second regex to drift. (EMAIL_RE is /g: never reuse a /g regex across
+ *    .test/.exec calls; here we only .replace() which resets lastIndex.)
+ *  - Atomic rewrite: write sibling temp file in the same directory, fsync, then
+ *    rename() over the original. A crash mid-redaction can never leave a
+ *    half-redacted file behind.
+ *  - No PII backup by default: the point of this pass is to REMOVE raw PII from
+ *    disk. Backups would silently reintroduce the leak we are fixing.
+ *    --keep-raw exists for operators who explicitly want a copy.
+ *  - Idempotent: the canonical mask output cannot re-match EMAIL_RE (stars and
+ *    quotes are outside the local-part class), so re-running is a no-op.
+ *  - Read-only when nothing matches (byte-identical content is never rewritten,
+ *    mtime preserved) — safe to point at a whole directory.
+ *  - Whole-file read + write. These logs are rotation-bounded (error.log.1 is
+ *    ~5 MB); buffering is the simplest correct approach and keeps the atomic
+ *    single-rename guarantee. Not for unbounded/streaming files.
+ *
+ * Usage:
+ *   node scripts/redact-log-pii.js [--dry-run] [--keep-raw] <file-or-dir> [...]
+ *     --dry-run   report what would change, touch nothing
+ *     --keep-raw  alongside the redacted file, keep <file>.raw-<epoch>
+ *                 (WARNING: this preserves the PII you are trying to remove)
+ *
+ * Exit codes: 0 = success (incl. "nothing to do"), 1 = usage/IO error,
+ *             2 = redaction ran but raw addresses remain (must not happen —
+ *             EMAIL_RE is total over its own match set).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { EMAIL_RE, maskEmailAddress } = require('../src/utils/logging');
+
+const argv = process.argv.slice(2);
+const DRY_RUN = argv.includes('--dry-run');
+const KEEP_RAW = argv.includes('--keep-raw');
+const targets = argv.filter((a) => !a.startsWith('--'));
+
+if (targets.length === 0) {
+  console.error(
+    'Usage: node scripts/redact-log-pii.js [--dry-run] [--keep-raw] <file-or-dir> [...]'
+  );
+  process.exit(1);
+}
+
+// Directories this script will never touch, even when handed a directory.
+const SKIP_NAMES = new Set([
+  'node_modules', '.git', 'coverage', '__tests__', 'dist', 'build',
+]);
+
+// Log-line size guard: readline-style splitting is unbounded per line; a
+// pathological single-line file is instead processed as one segment. This is
+// only a memory guard, not a correctness limit — segments are redacted with
+// the same total function.
+function redactString(s, stats) {
+  if (typeof s !== 'string' || !s.includes('@')) return s;
+  // .replace() with a /g regex always starts at index 0 (resets lastIndex),
+  // so sharing EMAIL_RE here is safe.
+  const out = s.replace(EMAIL_RE, (addr) => {
+    stats.addresses += 1;
+    return maskEmailAddress(addr);
+  });
+  if (out !== s) stats.lines += 1;
+  return out;
+}
+
+function redactFile(filePath, dryRun, keepRaw, report) {
+  const stat = fs.lstatSync(filePath);
+  if (!stat.isFile()) {
+    report.skipped.push(`${filePath} (not a regular file)`);
+    return;
+  }
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const stats = { addresses: 0, lines: 0 };
+  const out = redactString(raw, stats);
+  if (out === raw) {
+    report.clean.push(filePath);
+    return; // byte-identical → never rewrite (preserves mtime, inode)
+  }
+  if (dryRun) {
+    report.wouldRedact.push({ file: filePath, ...stats });
+    return;
+  }
+  if (keepRaw) {
+    fs.copyFileSync(filePath, `${filePath}.raw-${Math.floor(Date.now() / 1000)}`);
+  }
+  // Atomic rewrite: same-directory temp + fsync + rename.
+  const tmp = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.redact-${process.pid}`
+  );
+  const fd = fs.openSync(tmp, 'wx', stat.mode);
+  try {
+    fs.writeSync(fd, out, null, 'utf8');
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, filePath);
+  report.redacted.push({ file: filePath, ...stats });
+}
+
+function walk(target, report) {
+  let st;
+  try {
+    st = fs.lstatSync(target);
+  } catch (e) {
+    report.errors.push(`${target}: ${e.message}`);
+    return;
+  }
+  if (st.isDirectory()) {
+    for (const ent of fs.readdirSync(target, { withFileTypes: true })) {
+      if (SKIP_NAMES.has(ent.name)) continue;
+      walk(path.join(target, ent.name), report);
+    }
+  } else {
+    try {
+      redactFile(target, DRY_RUN, KEEP_RAW, report);
+    } catch (e) {
+      report.errors.push(`${target}: ${e.message}`);
+    }
+  }
+}
+
+const report = { clean: [], redacted: [], wouldRedact: [], skipped: [], errors: [] };
+for (const t of targets) walk(t, report);
+
+if (report.errors.length > 0) {
+  for (const e of report.errors) console.error(`error: ${e}`);
+  process.exit(1);
+}
+
+for (const f of report.clean) console.log(`clean (nothing to redact): ${f}`);
+for (const r of report.wouldRedact)
+  console.log(`would redact: ${r.file} (${r.addresses} addresses in ${r.lines} segments)`);
+for (const r of report.redacted)
+  console.log(`redacted: ${r.file} (${r.addresses} addresses in ${r.lines} segments)`);
+
+// Post-verify: after an actual run, no raw address may remain in any file we
+// redacted. This is a belt-and-braces check — mask output cannot re-match.
+if (!DRY_RUN) {
+  let leaked = 0;
+  for (const r of report.redacted) {
+    const content = fs.readFileSync(r.file, 'utf8');
+    const re = new RegExp(EMAIL_RE.source, EMAIL_RE.flags);
+    if (re.test(content)) {
+      console.error(`POST-VERIFY FAIL: raw addresses remain in ${r.file}`);
+      leaked += 1;
+    }
+  }
+  if (leaked > 0) process.exit(2);
+}
+
+console.log('done.');
diff --git a/dashcaddy-api/src/utils/logging.js b/dashcaddy-api/src/utils/logging.js
index 8d57383..b56db24 100644
--- a/dashcaddy-api/src/utils/logging.js
+++ b/dashcaddy-api/src/utils/logging.js
@@ -607,4 +607,12 @@ module.exports = {
   AUDIT_SKIP_PATHS,
   AUDIT_ACTION_MAP,
   SENSITIVE_KEYS,
+  // Email-PII masking primitives — exported for maintenance tooling
+  // (scripts/redact-log-pii.js rewrites pre-DC-095 log files with the SAME
+  // canonical mask so historical and new lines show one consistent shape).
+  // EMAIL_RE is a /g regex: always clone it (new RegExp(src, flags)) before
+  // .test()/.exec() or you will inherit a stale lastIndex.
+  EMAIL_RE,
+  maskEmailAddress,
+  maskEmailsInString,
 };