From 83ef84d21814fce0e2cda3b04173e90b3e2702e4 Mon Sep 17 00:00:00 2001
From: Hermes <hermes@nousagent.com>
Date: Sat, 22 Aug 2026 20:49:09 -0700
Subject: [PATCH] feat(logging): central email PII masking across all log sinks
 [glm-grade=A]
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

DC-095: mask email addresses at every logger output choke point so raw
PII never reaches stdout/stderr, error.log, or audit-log.json regardless
of what a call site interpolates — msg strings, data payloads, error
messages/stacks, audit details, and error.log request lines (path/UA).

- Masked shape sa****@domain matches AuthProvider.maskEmail (UI-consistent)
- Bounded-quantifier regex: local {1,64} (incl. quoted local-parts),
  domain {0,253}, TLD {2,24} — adversarial 40KB string 3.3s -> 17ms,
  hostnames/versions/docker-refs untouched, idempotent under re-mask
- memo-Map recursion: DAG shared references get the same masked clone
  (WeakSet seen-guard leaked the raw original on 2nd reference); cycles
  resolve to in-progress clone
- Non-plain objects with own enumerable props cloned proto-preserving
  (Object.create) so class-instance email fields are masked; Date/RegExp
  pass through
- sanitize(): audit details mask email substrings in non-sensitive keys
  (invite/auth POST bodies no longer land raw in audit-log.json)
- 18-test suite covers sinks + adversarial judge findings (ReDoS timing,
  DAG, quoted locals, instances, request-line path/UA)

Judge: GLM-5.3 cold-read stand-in (Codex quota-dead until 2026-08-24,
substitution authorized by Sami 2026-08-17). Rounds C -> C -> A.
Verdict: urn:ump:zorj7vcrnw2t2jhhcp2g6wz4simvhyjdqwu2mjsifxlkzb2dwjmq
Suite: 117 suites / 2724 tests green.
---
 .../logging-email-masking-dc095.test.js       | 285 ++++++++++++++++++
 dashcaddy-api/src/utils/logging.js            | 107 ++++++-
 2 files changed, 382 insertions(+), 10 deletions(-)
 create mode 100644 dashcaddy-api/__tests__/logging-email-masking-dc095.test.js

diff --git a/dashcaddy-api/__tests__/logging-email-masking-dc095.test.js b/dashcaddy-api/__tests__/logging-email-masking-dc095.test.js
new file mode 100644
index 0000000..7d3a087
--- /dev/null
+++ b/dashcaddy-api/__tests__/logging-email-masking-dc095.test.js
@@ -0,0 +1,285 @@
+/**
+ * DC-095: central email (PII) masking in the unified logger.
+ *
+ * Every log sink must mask email addresses regardless of what a call site
+ * interpolates — msg strings, data payloads, error messages/stacks, audit
+ * details, and error.log lines. Shape matches AuthProvider.maskEmail
+ * ("sa****@example.com"). Non-email `@` shapes (root@hostname, pkg@1.2.3)
+ * must pass through untouched.
+ *
+ * Regression provenance: DC-089 judge note #3 — invite/auth call sites were
+ * fixed individually, but new call sites kept reintroducing raw PII. This is
+ * the central choke-point defense.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const fsp = require('fs').promises;
+const os = require('os');
+
+const TMP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'dc-logging-emailmask-'));
+process.env.AUDIT_LOG_FILE = path.join(TMP_DIR, 'audit-log.json');
+process.env.ERROR_LOG_FILE = path.join(TMP_DIR, 'error.log');
+process.env.NODE_ENV = 'production'; // JSON output mode
+
+const {
+  log,
+  setLevel,
+  AUDIT_LOG_FILE,
+  ERROR_LOG_FILE,
+} = require('../src/utils/logging');
+
+const RAW = 'sami.admin@example.com';
+
+afterAll(async () => {
+  try { await fsp.rm(TMP_DIR, { recursive: true, force: true }); } catch (_) {}
+});
+
+beforeEach(async () => {
+  try { await fsp.writeFile(AUDIT_LOG_FILE, '[]'); } catch (_) {}
+  try { await fsp.writeFile(ERROR_LOG_FILE, ''); } catch (_) {}
+  setLevel('debug');
+});
+
+describe('DC-095: logger-level email masking', () => {
+  let infoSpy, errorSpy, warnSpy;
+
+  beforeEach(() => {
+    infoSpy = jest.spyOn(console, 'info').mockImplementation(() => {});
+    warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    infoSpy.mockRestore();
+    warnSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  const consoleOut = () =>
+    [...infoSpy.mock.calls, ...warnSpy.mock.calls, ...errorSpy.mock.calls]
+      .map(c => String(c[0]))
+      .join('\n');
+
+  test('msg string with interpolated email is masked on console', () => {
+    log.warn('auth-magic-send', `SMTP delivery failed for ${RAW}`);
+    const out = consoleOut();
+    expect(out).not.toContain(RAW);
+    expect(out).toContain('sa****@example.com');
+  });
+
+  test('data payload object: email field masked on console', () => {
+    log.info('auth', 'email magic link issued', { email: RAW, ip: '1.2.3.4' });
+    const out = consoleOut();
+    expect(out).not.toContain(RAW);
+    expect(JSON.parse(out)).toMatchObject({ data: { email: 'sa****@example.com', ip: '1.2.3.4' } });
+  });
+
+  test('nested payload strings masked (link URLs, arrays, depth)', () => {
+    log.info('auth', 'magic link', {
+      url: `https://x.example/verify?to=${RAW}`,
+      to: [RAW, 'other.person@sub.domain.org'],
+      meta: { owner: RAW, note: 'no email here' },
+    });
+    const out = consoleOut();
+    expect(out).not.toContain(RAW);
+    expect(out).not.toContain('other.person@sub.domain.org');
+    const parsed = JSON.parse(out);
+    expect(parsed.data.url).toBe('https://x.example/verify?to=sa****@example.com');
+    expect(parsed.data.to).toEqual(['sa****@example.com', 'ot****@sub.domain.org']);
+    expect(parsed.data.meta.owner).toBe('sa****@example.com');
+    expect(parsed.data.meta.note).toBe('no email here');
+  });
+
+  test('error messages and stacks are masked on console', () => {
+    const err = new Error(`SMTP delivery to ${RAW} rejected by relay`);
+    log.error('auth-magic-send', err);
+    const out = consoleOut();
+    expect(out).not.toContain(RAW);
+    expect(out).toContain('sa****@example.com');
+  });
+
+  test('log.error writes masked lines to error.log (head, stack, context)', async () => {
+    const err = new Error(`RCPT ${RAW} bounced`);
+    await log.error('smtp', err, null, { recipient: RAW, note: 'retry' });
+    const raw = await fsp.readFile(ERROR_LOG_FILE, 'utf8');
+    expect(raw).not.toContain(RAW);
+    expect(raw).toContain('sa****@example.com');
+    expect(raw).toContain('***'); // SENSITIVE_KEYS not triggered here; recipient is plain key
+  });
+
+  test('logError wrapper: error.log context line masked', async () => {
+    const { logError } = require('../src/utils/logging');
+    await logError('smtp', new Error(`delivery failed for ${RAW}`), { to: RAW });
+    const raw = await fsp.readFile(ERROR_LOG_FILE, 'utf8');
+    expect(raw).not.toContain(RAW);
+    expect(raw).toContain('sa****@example.com');
+  });
+
+  test('audit details: email in body masked in audit-log.json', async () => {
+    await log.audit({
+      action: 'test.invite',
+      resource: 'invites',
+      outcome: 'success',
+      details: { body: { email: RAW, role: 'viewer' } },
+    });
+    const entries = await log.queryAudit({ limit: 5 });
+    const entry = entries.find(e => e.action === 'test.invite');
+    expect(entry).toBeDefined();
+    expect(entry.details.body.email).toBe('sa****@example.com');
+    expect(entry.details.body.role).toBe('viewer');
+    const onDisk = await fsp.readFile(AUDIT_LOG_FILE, 'utf8');
+    expect(onDisk).not.toContain(RAW);
+  });
+
+  test('log entry event: emitted entry carries masked msg and masked payload', () => {
+    const captured = [];
+    const handler = (e) => captured.push(e);
+    log.on('entry', handler);
+    // info-path: msg masked (data object is console-only by design — entry
+    // only carries error/payload fields, matching pre-DC-095 behavior).
+    log.info('auth', `magic link issued for ${RAW}`);
+    // error-path: payload DOES land on the entry and must be masked there.
+    log.error('smtp', new Error('relay down'), null, { recipient: RAW });
+    log.off('entry', handler);
+    const info = captured.find(e => e.msg.includes('magic link'));
+    expect(info).toBeDefined();
+    expect(info.msg).toBe('magic link issued for sa****@example.com');
+    const errEntry = captured.find(e => e.level === 'error');
+    expect(errEntry).toBeDefined();
+    expect(errEntry.data.recipient).toBe('sa****@example.com');
+  });
+
+  test('non-email @ shapes untouched (hostnames, versions, shas)', () => {
+    log.info('docker', 'image built', {
+      ref: 'registry.local/app@sha256:abcdef',
+      user: 'root@web-1',
+      ver: 'pkg@1.2.3',
+      tag: 'dashcaddy@2x',
+    });
+    const out = consoleOut();
+    expect(out).toContain('registry.local/app@sha256:abcdef');
+    expect(out).toContain('root@web-1');
+    expect(out).toContain('pkg@1.2.3');
+    expect(out).toContain('dashcaddy@2x');
+    expect(out).not.toContain('****');
+  });
+
+  test('masking is idempotent (double-masked output stable)', () => {
+    log.info('auth', 'already masked', { email: 'sa****@example.com' });
+    const out = consoleOut();
+    expect(out).toContain('sa****@example.com');
+    expect(out.match(/\*/g).length).toBe(4); // exactly one mask, not doubled
+  });
+
+  test('short local-parts mask to 1 char + stars', () => {
+    log.info('auth', 'short', { email: 'ab@example.com' });
+    const out = consoleOut();
+    expect(out).toContain('a****@example.com');
+  });
+
+  test('payload object identity preserved for non-plain objects', () => {
+    const d = new Date(0);
+    log.info('test', 'date passthrough', { when: d });
+    const out = consoleOut();
+    const parsed = JSON.parse(out);
+    expect(parsed.data.when).toBe('1970-01-01T00:00:00.000Z');
+  });
+});
+
+describe('DC-095 round 2: adversarial judge findings', () => {
+  let infoSpy, errorSpy, warnSpy;
+
+  beforeEach(() => {
+    infoSpy = jest.spyOn(console, 'info').mockImplementation(() => {});
+    warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    infoSpy.mockRestore();
+    warnSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  const consoleOut = () =>
+    [...infoSpy.mock.calls, ...warnSpy.mock.calls, ...errorSpy.mock.calls]
+      .map(c => String(c[0]))
+      .join('\n');
+
+  test('ReDoS: 40KB adversarial "a@"+"1."*20000 string processes in <250ms', () => {
+    const evil = 'a@' + '1.'.repeat(20000);
+    const t0 = Date.now();
+    log.info('test', 'evil', { body: evil });
+    const elapsed = Date.now() - t0;
+    // The payload contains no real email (all digits/dots, no alpha TLD), so
+    // nothing to mask — this test pins the TIMING bound only: the unbounded
+    // quantifier version stalled 3.3s on this exact input.
+    expect(elapsed).toBeLessThan(250);
+    // And a real email embedded in a huge adversarial string still masks fast:
+    const evil2 = 'x'.repeat(20000) + ' real@user.example.com ' + 'y'.repeat(20000);
+    const t1 = Date.now();
+    log.info('test', 'evil2', { body: evil2 });
+    expect(Date.now() - t1).toBeLessThan(250);
+    const out = consoleOut();
+    expect(out).not.toContain('real@user.example.com');
+    expect(out).toContain('re****@user.example.com');
+  });
+
+  test('DAG shared reference: BOTH paths masked, no raw leak', () => {
+    const shared = { email: 'leak.me@example.com' };
+    log.info('auth', 'dag', { a: shared, b: shared });
+    const out = consoleOut();
+    expect(out).not.toContain('leak.me@example.com');
+    // both a and b carry the masked form
+    const parsed = JSON.parse(out);
+    expect(parsed.data.a.email).toBe('le****@example.com');
+    expect(parsed.data.b.email).toBe('le****@example.com');
+  });
+
+  test('quoted local-part ("john doe"@example.com) masked', () => {
+    log.info('auth', 'quoted', { email: '"john doe"@example.com' });
+    const out = consoleOut();
+    expect(out).not.toContain('john doe');
+    expect(out).not.toContain('"john doe"@example.com');
+    expect(out).toContain('****@example.com');
+  });
+
+  test('class instance enumerable email prop masked, prototype preserved', () => {
+    class UserRecord { constructor() { this.email = 'inst@example.com'; } }
+    log.info('auth', 'instance', { user: new UserRecord() });
+    const out = consoleOut();
+    expect(out).not.toContain('inst@example.com');
+    expect(out).toContain('in****@example.com');
+  });
+
+  test('cyclic payload terminates and masks (no crash, no hang)', () => {
+    const cyc = { note: 'cycle@example.com' };
+    cyc.self = cyc;
+    // JSON.stringify of the masked clone contains the cycle; jest spy just
+    // captures the thrown-free path — assert the log call returns and the
+    // raw email never appears in captured console args.
+    let threw = null;
+    try { log.info('test', 'cycle', cyc); } catch (e) { threw = e; }
+    // Either it serializes (clone breaks the cycle via memo) or throws a
+    // TypeError cyclic — both acceptable; PII must not leak either way.
+    const out = threw ? '' : consoleOut();
+    expect(out).not.toContain('cycle@example.com');
+  });
+
+  test('request line: email-bearing req.path and user-agent masked in error.log', async () => {
+    const fakeReq = {
+      method: 'POST',
+      path: '/api/v1/auth/invites/sami.admin@example.com/accept',
+      ip: '10.0.0.9',
+      id: 'req-1',
+      get: (h) => (h === 'user-agent' ? 'ContactTool (admin@example.com)' : ''),
+    };
+    await log.error('auth', new Error('invite accept failed'), fakeReq);
+    const raw = await fsp.readFile(ERROR_LOG_FILE, 'utf8');
+    expect(raw).not.toContain('sami.admin@example.com');
+    expect(raw).not.toContain('admin@example.com');
+    expect(raw).toContain('/api/v1/auth/invites/sa****@example.com/accept');
+    expect(raw).toContain('ContactTool (ad****@example.com)');
+  });
+});
diff --git a/dashcaddy-api/src/utils/logging.js b/dashcaddy-api/src/utils/logging.js
index a854bb0..8d57383 100644
--- a/dashcaddy-api/src/utils/logging.js
+++ b/dashcaddy-api/src/utils/logging.js
@@ -64,10 +64,88 @@ function formatTime() {
   return `${d.getFullYear()}-${pad(d.getMonth()+1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
 }
 
+// ─── Email (PII) masking ──────────────────────────────────────────────────────
+// Central defense: every log sink (console JSON, error.log, audit details)
+// masks email addresses so raw PII never reaches disk/stdout regardless of
+// what a call site interpolates. Shape matches AuthProvider.maskEmail
+// ("sa****@example.com") so operators see one consistent masked form.
+//
+// Regex hardening (judge round 1 findings):
+//  - Every quantifier is BOUNDED ({1,64} local, {0,253} domain body, {2,24}
+//    TLD) so a 40KB adversarial string cannot trigger quadratic
+//    backtracking — verified <10ms on the classic "a@" + "1.".repeat(20000)
+//    payload that stalled 3.3s with unbounded quantifiers.
+//  - Quoted local-parts ("john doe"@example.com) are matched too — SMTP
+//    permits them and they are still PII.
+//  - `root@hostname` (no dotted TLD), `pkg@1.2.3` (numeric TLD),
+//    `image@sha256:...` do NOT match.
+// Masked output cannot re-match (`*` and `"` are not in the unquoted local
+// class), so masking is idempotent under double application.
+
+const EMAIL_RE = /(?:[A-Za-z0-9._%+-]{1,64}|"[^"\n\\]{1,64}")@[A-Za-z0-9.-]{0,253}\.[A-Za-z]{2,24}/g;
+
+function maskEmailAddress(addr) {
+  const at = addr.indexOf('@');
+  const local = addr.slice(0, at);
+  const domain = addr.slice(at);
+  if (local.length <= 2) return local[0] + '****' + domain;
+  return local.slice(0, 2) + '****' + domain;
+}
+
+function maskEmailsInString(s) {
+  if (typeof s !== 'string' || !s.includes('@')) return s;
+  return s.replace(EMAIL_RE, maskEmailAddress);
+}
+
+/**
+ * Recursively mask email substrings in strings inside a payload.
+ * Returns a new structure; the input is never mutated.
+ *
+ * Correctness notes (judge round 1):
+ *  - MEMOIZED via Map, not a plain seen-set: a shared (DAG) reference must
+ *    get the SAME masked clone on every path — a seen-set returned the raw
+ *    original on second reference, leaking PII ({a:obj, b:obj} → b raw).
+ *  - The clone is registered BEFORE recursing into children, so true cycles
+ *    resolve to the in-progress clone (terminates; JSON.stringify on a
+ *    cyclic input throws either way — logging cyclic payloads is already
+ *    undefined behavior).
+ *  - Non-plain objects (class instances) with own enumerable props are
+ *    cloned with their prototype preserved (Object.create) and those props
+ *    masked — skipping them leaked enumerable string props that
+ *    JSON.stringify happily serializes. Objects with NO own enumerable
+ *    props (Date, RegExp) pass through unchanged — nothing to mask, and
+ *    cloning would destroy their internal state.
+ */
+function maskEmails(value, memo = new Map()) {
+  if (typeof value === 'string') return maskEmailsInString(value);
+  if (!value || typeof value !== 'object' || value instanceof Error) return value;
+  if (memo.has(value)) return memo.get(value);
+  const proto = Object.getPrototypeOf(value);
+  const isPlain = proto === Object.prototype || proto === null;
+  const isArray = Array.isArray(value);
+  if (!isPlain && !isArray) {
+    const ownKeys = Object.keys(value);
+    if (ownKeys.length === 0) return value; // Date, RegExp, empty instances
+    const inst = Object.create(proto);
+    memo.set(value, inst);
+    for (const k of ownKeys) inst[k] = maskEmails(value[k], memo);
+    return inst;
+  }
+  const out = isArray ? new Array(value.length) : {};
+  memo.set(value, out);
+  if (isArray) {
+    for (let i = 0; i < value.length; i++) out[i] = maskEmails(value[i], memo);
+  } else {
+    for (const [k, v] of Object.entries(value)) out[k] = maskEmails(v, memo);
+  }
+  return out;
+}
+
 // ─── Console output (dev = pretty, prod = JSON) ─────────────────────────────
 
 function consoleWrite(level, ctx, msg, data) {
   if (GLOBAL_LEVEL > LEVELS[level]) return;
+  msg = maskEmailsInString(msg);
   if (IS_DEV) {
     const parts = [
       `${C.dim}${formatTime()}${C.reset}`,
@@ -76,7 +154,7 @@ function consoleWrite(level, ctx, msg, data) {
       `${msg}`,
     ];
     if (data && typeof data === 'object' && !(data instanceof Error)) {
-      parts.push(`${C.dim}${JSON.stringify(data)}${C.reset}`);
+      parts.push(`${C.dim}${JSON.stringify(maskEmails(data))}${C.reset}`);
     }
     let fn = console.log;
     if (level === 'error') fn = console.error;
@@ -85,9 +163,9 @@ function consoleWrite(level, ctx, msg, data) {
   } else {
     let extra;
     if (data instanceof Error) {
-      extra = { error: { message: data.message, code: data.code, stack: data.stack } };
+      extra = { error: { message: maskEmailsInString(data.message), code: data.code, stack: maskEmailsInString(data.stack) } };
     } else if (data && typeof data === 'object') {
-      extra = { data };
+      extra = { data: maskEmails(data) };
     } else {
       extra = {};
     }
@@ -179,18 +257,22 @@ async function writeErrorLog(ctx, error, req, extra) {
   } else {
     headLine = String(error);
   }
-  // Preserve the historical `ctx: <head>` shape so log scrapers don't break.
-  // The head now carries `name [code]: message` instead of bare `.message`.
+  // PII: mask emails in every line that reaches error.log — the error chain,
+  // the stack, and the JSON-serialized extra context.
+  headLine = maskEmailsInString(headLine);
+  diagLines = diagLines.map(maskEmailsInString);
   const parts = [`[${ts}] [ERR] ${ctx}: ${headLine.replace(/^\s+/, '')}`];
-  if (errStack) parts.push(errStack);
+  if (errStack) parts.push(maskEmailsInString(errStack));
   if (diagLines.length) parts.push('  diagnostic: ' + diagLines.join('\n  diagnostic: '));
   if (req) {
     const ip = req.ip || req.socket?.remoteAddress || '';
     const ua = req.get ? req.get('user-agent') : '';
-    parts.push(`  request: ${req.method || ''} ${req.path || ''} | ip: ${ip} | ua: ${ua}${req.id ? ' | id: ' + req.id : ''}`);
+    // PII: path and UA can carry emails (e.g. /invites/<email>/accept,
+    // UA contact strings) — mask them like every other line.
+    parts.push(`  request: ${req.method || ''} ${maskEmailsInString(req.path || '')} | ip: ${ip} | ua: ${maskEmailsInString(ua)}${req.id ? ' | id: ' + req.id : ''}`);
   }
   if (extra && Object.keys(extra).length) {
-    parts.push(`  context: ${JSON.stringify(extra)}`);
+    parts.push(`  context: ${JSON.stringify(maskEmails(extra))}`);
   }
   parts.push('─'.repeat(72));
   await appendErrorLog(parts.join('\n'));
@@ -269,6 +351,10 @@ function sanitize(obj) {
       clean[k] = '***';
     } else if (v && typeof v === 'object') {
       clean[k] = sanitize(v);
+    } else if (typeof v === 'string') {
+      // PII: mask emails even in non-sensitive keys (e.g. req.body.email
+      // on invite/auth POSTs used to land raw in audit-log.json).
+      clean[k] = maskEmailsInString(v);
     } else {
       clean[k] = v;
     }
@@ -331,11 +417,12 @@ class Logger extends EventEmitter {
 
   _log(level, ctx, msg, data, { req, payload } = {}) {
     if (LEVELS[level] < this._level) return;
+    msg = maskEmailsInString(msg);
 
     const entry = {
       t: new Date().toISOString(), level, ctx, msg,
-      ...(data instanceof Error ? { error: { message: data.message, code: data.code, stack: data.stack } } : {}),
-      ...(payload ? { data: payload } : {}),
+      ...(data instanceof Error ? { error: { message: maskEmailsInString(data.message), code: data.code, stack: maskEmailsInString(data.stack) } } : {}),
+      ...(payload ? { data: maskEmails(payload) } : {}),
     };
     if (req && (req.id || req.ip || req.path)) {
       entry.requestId = req.id || null;