@dreamforgestudiollc/emet 0.0.0-stage → 0.2.4

package/src/persons.js

@@ -0,0 +1,116 @@
+/**
+ * EMET - persons
+ *
+ * A person is who logged in. A host-tag is which door they used.
+ * Tokens used to carry subject: "owner" for every connection. That cannot
+ * scale to a second human. This module is the first cut: one owner person
+ * in a `persons` collection, and a subject resolver the token issuer calls.
+ *
+ * Invitation, membership, and scopes on dispatch are later cuts.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const COLLECTION = 'persons';
+/** Stdio has no login. Every local write is stamped with this one subject. */
+export const LOCAL_SUBJECT = 'local';
+export const actorStore = new AsyncLocalStorage();
+export function currentActor() {
+  const s = actorStore.getStore();
+  if (typeof s === 'string' && s.trim()) return { personId: s.trim(), scopes: [] };
+  if (s && typeof s === 'object') {
+    return {
+      personId: s.personId || null,
+      clientId: s.clientId || null,
+      scopes: Array.isArray(s.scopes) ? s.scopes : [],
+      transport: s.transport || null,
+      authenticated: s.authenticated === true
+    };
+  }
+  return { personId: null, clientId: null, scopes: [], transport: null, authenticated: false };
+}
+export function currentPersonId() {
+  return currentActor().personId;
+}
+export function currentClientId() {
+  const s = actorStore.getStore();
+  if (!s || typeof s === 'string') return 'stdio';
+  return s.clientId === undefined ? 'stdio' : s.clientId;
+}
+
+/** Server stamp only. A caller value is never read. Stdio is one fixed local subject. */
+export function writerStamp() {
+  const s = actorStore.getStore();
+  if (!s || typeof s === 'string') {
+    const id = typeof s === 'string' && s.trim() ? s.trim() : LOCAL_SUBJECT;
+    return { person_id: id, client_id: 'stdio' };
+  }
+  if (s.transport === 'http') {
+    return { person_id: s.personId || null, client_id: s.clientId === undefined ? null : s.clientId };
+  }
+  return { person_id: s.personId || LOCAL_SUBJECT, client_id: s.clientId === undefined ? 'stdio' : s.clientId };
+}
+
+/**
+ * HTTP binds a source tag at approval. Returns that tag (or null when none
+ * was bound). Returns undefined on stdio, where the caller tag is checked
+ * against EMET_SOURCE_TAGS instead.
+ */
+export function boundSourceTag() {
+  const s = actorStore.getStore();
+  if (!s || typeof s !== 'object' || s.transport !== 'http') return undefined;
+  const tag = typeof s.sourceTag === 'string' ? s.sourceTag.trim() : '';
+  return tag || null;
+}
+
+export function displayNameFromUserDoc(text) {
+  const heading = String(text || '').match(/^#\s+User Profile\s+[\u2014\u2013-]\s+(.+)$/im);
+  if (heading) return heading[1].trim();
+  return null;
+}
+
+export function slugPersonId(name) {
+  const s = String(name || '')
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+  return s || 'owner';
+}
+
+export async function ensureOwnerPerson(db, { display_name } = {}) {
+  const col = db.collection(COLLECTION);
+  const existing = await col.findOne({ role: 'owner' });
+  if (existing) return existing;
+  const person_id = slugPersonId(display_name);
+  const row = {
+    person_id,
+    display_name: String(display_name || person_id).trim() || person_id,
+    role: 'owner',
+    created_at: new Date()
+  };
+  await col.insertOne(row);
+  return row;
+}
+
+/** Subject stamped on new tokens. Falls back to "owner" if the table is empty. */
+export async function resolveTokenSubject(db) {
+  if (!db) return 'owner';
+  const owner = await db.collection(COLLECTION).findOne({ role: 'owner' });
+  return owner?.person_id || 'owner';
+}
+
+/** Person on this request, from the bearer token. Host-tags stay separate. */
+export function personFromAuth(extra) {
+  const info = extra && extra.authInfo;
+  const s = (info && info.extra && info.extra.subject) || (info && info.subject);
+  if (typeof s === 'string' && s.trim()) return s.trim();
+  return null;
+}
+
+export async function getPerson(db, person_id) {
+  if (!db || !person_id) return null;
+  return db.collection(COLLECTION).findOne({ person_id });
+}

package/src/provenance.js

@@ -0,0 +1,257 @@
+/**
+ * EMET - Enduring Memory & Epistemic Tiers
+ * Copyright (c) 2026 Dreamforge Studio LLC
+ *
+ * Licensed under the MIT License - see LICENSE
+ *
+ * Provenance: how a tier-1 entry reaches the tier-2 record that justifies it.
+ *
+ * "Epistemic Tiers" names the pairing of a claim with its evidence. A layer
+ * entry that asserts something, with no reachable source, is a claim the system
+ * merely happens to hold - so the link between the tiers is not a convenience,
+ * it is the half of the name that makes the other half worth anything.
+ *
+ * TWO MECHANISMS, DELIBERATELY, AND THEY ARE NOT REDUNDANT COPIES.
+ *
+ *   POINTER   - the entry records the transcript span it came from: a session id
+ *               and a range of exchange indices. Exact. Conditional: absent on
+ *               everything written before pointers existed, and legitimately
+ *               absent on entries consolidated from other entries rather than
+ *               from a conversation.
+ *
+ *   TIMESTAMP - every entry has one, unconditionally, so a window around it can
+ *               always be searched. Universal. Approximate: it depends on
+ *               choosing the window, it degrades when sessions overlap or run
+ *               long, and when it is wrong it returns the NEIGHBOURING span
+ *               rather than failing. A silent wrong answer is the worst possible
+ *               failure shape for a provenance mechanism.
+ *
+ * PRECEDENCE IS WHAT KEEPS THEM FROM CONFLICTING. The pointer wins whenever it
+ * is present; the timestamp is the fallback when it is null. They are never
+ * averaged, never combined, and the timestamp is never preferred merely because
+ * it returned something. Without a stated precedence two links are ambiguity;
+ * with one they are a primary and a fallback.
+ *
+ * AND KEEPING BOTH BUYS SOMETHING NEITHER GIVES ALONE: they can check each
+ * other. If an entry's pointer names a session whose span sits nowhere near that
+ * entry's own timestamp, something is wrong - a mis-written pointer, a field
+ * copied from another entry, an entry attributed to the wrong session. Two
+ * independently derived answers that can disagree is redundancy in the
+ * engineering sense. A single link that can only be trusted is not.
+ *
+ * WHY THESE ARE TOP-LEVEL FIELDS. They sit beside the entry, not inside the
+ * metadata JSON string, for the same reason `superseded_by`, `valid_until` and
+ * `is_live` were promoted: the store cannot filter into a JSON string, so a
+ * pointer buried there could be written but never queried - and the reverse
+ * question, "what did we take from this session?", is exactly a query.
+ *
+ * NO BACKFILL. An entry written before pointers existed cannot be given a true
+ * one; the only way to invent it is to infer the span from the timestamp, which
+ * is precisely the weaker method the pointer exists to replace. Historical
+ * entries keep a null pointer and resolve by timestamp, and that remains correct
+ * for them - superseded, not wrong. Old records are not rewritten to look like
+ * new ones; the method that applies to them is written down instead.
+ */
+
+import { ValidationError } from './validation.js';
+
+/** Default half-width of the timestamp fallback window, in seconds. */
+export const FALLBACK_WINDOW_SECONDS = 3600;
+
+/** How far a pointer's session may sit from an entry's timestamp before the
+ *  cross-check calls it suspicious. Generous: long sessions are normal, and a
+ *  false alarm here trains its reader to ignore the check. */
+const CROSS_CHECK_TOLERANCE_SECONDS = 24 * 3600;
+
+function isPositiveInt(v) {
+  return Number.isInteger(v) && v > 0;
+}
+
+/**
+ * Validate a caller-supplied provenance object.
+ *
+ * Accepts either shape, and only one of them:
+ *   { session_id, exchange_start, exchange_end }  - derived from a conversation
+ *   { entries: [id, ...] }                        - consolidated from other entries
+ *
+ * The second shape exists because a required field with no honest value invites
+ * fabrication. An entry consolidated from three others has no transcript span,
+ * and must be able to say so explicitly rather than carry a nearest-timestamp
+ * guess dressed as a citation.
+ */
+export function validateProvenance(input) {
+  if (input === null || input === undefined) return null;
+  if (typeof input !== 'object' || Array.isArray(input)) {
+    throw new ValidationError('derived_from', 'must be an object');
+  }
+
+  const hasSpan = input.session_id !== undefined;
+  const hasEntries = input.entries !== undefined;
+
+  if (hasSpan && hasEntries) {
+    throw new ValidationError(
+      'derived_from',
+      'give a transcript span or a list of source entries, not both - an entry has one origin'
+    );
+  }
+  if (!hasSpan && !hasEntries) {
+    throw new ValidationError(
+      'derived_from',
+      'needs either session_id (with optional exchange_start/exchange_end) or entries'
+    );
+  }
+
+  if (hasEntries) {
+    if (!Array.isArray(input.entries) || input.entries.length === 0) {
+      throw new ValidationError('derived_from.entries', 'must be a non-empty array of entry ids');
+    }
+    if (!input.entries.every(isPositiveInt)) {
+      throw new ValidationError('derived_from.entries', 'entry ids must be positive integers');
+    }
+    return { entries: [...input.entries] };
+  }
+
+  if (typeof input.session_id !== 'string' || input.session_id.length === 0) {
+    throw new ValidationError('derived_from.session_id', 'must be a non-empty string');
+  }
+  const start = input.exchange_start;
+  const end = input.exchange_end;
+  if (start !== undefined && !isPositiveInt(start)) {
+    throw new ValidationError('derived_from.exchange_start', 'must be a positive integer');
+  }
+  if (end !== undefined && !isPositiveInt(end)) {
+    throw new ValidationError('derived_from.exchange_end', 'must be a positive integer');
+  }
+  if (isPositiveInt(start) && isPositiveInt(end) && end < start) {
+    throw new ValidationError('derived_from.exchange_end', 'must not be before exchange_start');
+  }
+
+  return {
+    session_id: input.session_id,
+    exchange_start: isPositiveInt(start) ? start : null,
+    exchange_end: isPositiveInt(end) ? end : (isPositiveInt(start) ? start : null)
+  };
+}
+
+/**
+ * The top-level columns to store for a validated provenance object.
+ * Always returns every key, so an entry without provenance stores explicit nulls
+ * rather than absent fields - absence and "no pointer" must not be the same
+ * shape as "this field was never part of the schema".
+ */
+export function provenanceColumns(provenance) {
+  if (!provenance) {
+    return { source_session_id: null, source_exchange_start: null, source_exchange_end: null, derived_from_ids: null };
+  }
+  if (provenance.entries) {
+    return { source_session_id: null, source_exchange_start: null, source_exchange_end: null, derived_from_ids: provenance.entries };
+  }
+  return {
+    source_session_id: provenance.session_id,
+    source_exchange_start: provenance.exchange_start,
+    source_exchange_end: provenance.exchange_end,
+    derived_from_ids: null
+  };
+}
+
+/**
+ * Resolve how to reach the evidence for an entry.
+ *
+ * This is the precedence rule, in one place, so no caller has to decide it.
+ */
+export function resolveProvenance(entry, windowSeconds = FALLBACK_WINDOW_SECONDS) {
+  if (!entry) throw new ValidationError('entry', 'is required');
+
+  if (entry.source_session_id) {
+    return {
+      method: 'pointer',
+      exact: true,
+      session_id: entry.source_session_id,
+      exchange_start: entry.source_exchange_start ?? null,
+      exchange_end: entry.source_exchange_end ?? null,
+      how: 'Read this session\'s transcript and take the named exchange range.'
+    };
+  }
+
+  if (Array.isArray(entry.derived_from_ids) && entry.derived_from_ids.length > 0) {
+    return {
+      method: 'entries',
+      exact: true,
+      entries: entry.derived_from_ids,
+      how: 'This entry was consolidated from other entries. Read those; they carry their own provenance.'
+    };
+  }
+
+  const timestamp = typeof entry.timestamp === 'number' ? entry.timestamp : null;
+  if (timestamp === null) {
+    return {
+      method: 'none',
+      exact: false,
+      how: 'No pointer and no timestamp. The source of this entry cannot be reached; treat the claim as unsourced.'
+    };
+  }
+
+  return {
+    method: 'timestamp',
+    exact: false,
+    timestamp_start: timestamp - windowSeconds,
+    timestamp_end: timestamp + windowSeconds,
+    how:
+      'No pointer on this entry, so fall back to searching transcripts over a window around its ' +
+      'timestamp. This is approximate: it can return a neighbouring span rather than the real ' +
+      'one, and an empty result is not proof that nothing was recorded. Do not cite a window ' +
+      'result with the confidence of a pointer.'
+  };
+}
+
+/**
+ * Cross-check a pointer against the entry's own timestamp.
+ *
+ * The reason to keep both mechanisms rather than replacing one with the other:
+ * two independently derived answers can disagree, and a disagreement is
+ * information. Returns a finding; it never throws and never blocks a write,
+ * because a suspicious pointer is a thing to look at, not a thing to refuse.
+ */
+export function crossCheckProvenance(entry, transcript, toleranceSeconds = CROSS_CHECK_TOLERANCE_SECONDS) {
+  if (!entry || !entry.source_session_id) return { checked: false, reason: 'no pointer to check' };
+  if (!transcript) {
+    return {
+      checked: true,
+      agrees: false,
+      finding: `Entry points at session "${entry.source_session_id}", which does not exist in the transcript store.`
+    };
+  }
+
+  const toSeconds = (v) => {
+    if (v instanceof Date) return v.getTime() / 1000;
+    if (typeof v === 'number') return v > 1e11 ? v / 1000 : v;
+    return null;
+  };
+  const start = toSeconds(transcript.session_start);
+  const end = toSeconds(transcript.session_end) ?? start;
+  const at = typeof entry.timestamp === 'number' ? entry.timestamp : null;
+
+  if (at === null || start === null) return { checked: false, reason: 'not enough timing information to compare' };
+
+  const distance = at < start ? start - at : (at > end ? at - end : 0);
+  if (distance <= toleranceSeconds) return { checked: true, agrees: true, distance_seconds: Math.round(distance) };
+
+  return {
+    checked: true,
+    agrees: false,
+    distance_seconds: Math.round(distance),
+    finding:
+      `Entry timestamp sits ${Math.round(distance / 3600)}h outside the session its pointer names. ` +
+      `The pointer and the timestamp disagree about where this entry came from - likely a field ` +
+      `copied from another entry, or an entry attributed to the wrong session. Report it; do not ` +
+      `silently prefer either one.`
+  };
+}
+
+export default {
+  validateProvenance,
+  provenanceColumns,
+  resolveProvenance,
+  crossCheckProvenance,
+  FALLBACK_WINDOW_SECONDS
+};

package/src/redact.js

@@ -0,0 +1,231 @@
+/**
+ * EMET - Enduring Memory & Epistemic Tiers
+ * Copyright (c) 2026 Dreamforge Studio LLC
+ *
+ * Licensed under the MIT License - see LICENSE
+ *
+ * Secret redaction at the write path.
+ *
+ * Why this exists (2026-09-07): an OAuth passphrase was pasted into a chat and a
+ * screenshot during a connector re-add, and the session transcript that would
+ * carry it verbatim was minutes away from being written to the store. A rule
+ * that says "do not paste secrets" is an instruction; a scrubber the content
+ * passes through before it lands anywhere is a control. This module is the
+ * control. It sits inside the single write path (THE DOOR, a decision record):
+ * memory saves, transcript saves, document writes, and log output all pass
+ * through it, so an instance cannot opt out by forgetting.
+ *
+ * What it masks, in order:
+ *   1. Literal values of secret-bearing environment variables (anything whose
+ *      name contains PASSPHRASE, PASSWORD, SECRET, TOKEN, API_KEY, PRIVATE_KEY,
+ *      or MONGODB_URI), plus the user:password pair inside any URI among them.
+ *      These are exact-string matches and cannot false-positive.
+ *   2. Credentials embedded in URIs: scheme://user:password@host.
+ *   3. Bearer tokens and JWTs.
+ *   4. key/value pairs whose key names a secret (passphrase, password, secret,
+ *      token, api_key, client_secret, access_token, refresh_token, authorization)
+ *      followed by : or = and a value. The key survives, the value does not.
+ *
+ * What it deliberately does NOT mask: hex digests (sha256 values are 64 hex
+ * chars and are part of the integrity record), ids, and ordinary prose. Rule 4
+ * can mask a word in prose that follows "token:" - that is accepted. Masking a
+ * word costs a word; missing a secret costs the secret. (An English prefix
+ * hyphenated onto a key word - "re-authorization:" - is not treated as a key;
+ * that one masked prose on 2026-09-07 and is excluded.)
+ *
+ * The mask is visible on purpose: '*****' says "something was here and was
+ * removed", which is the honest record. A silent drop would be a summary.
+ *
+ * The hit count reports CHANGES. Text that already carries the mask is matched
+ * and left as it is, uncounted - otherwise every read-modify-write of a
+ * document re-reports the masks it already held (observed 2026-09-07).
+ */
+
+export const MASK = '*****';
+
+const SECRET_ENV_NAME = /(PASSPHRASE|PASSWORD|PASSWD|SECRET|TOKEN|API[_-]?KEY|PRIVATE[_-]?KEY|MONGODB_URI)/i;
+const MIN_LITERAL_LENGTH = 6;
+
+// Registered literal secrets. A Set so re-registering is a no-op.
+const literals = new Set();
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Registers one literal secret value. Anything shorter than MIN_LITERAL_LENGTH
+ * is ignored - masking "abc" everywhere would shred ordinary text.
+ * If the value is a URI with credentials, the user:password pair is registered
+ * as well, so a URI quoted with a different host or query still masks.
+ */
+export function registerSecret(value) {
+  if (typeof value !== 'string') return false;
+  const v = value.trim();
+  if (v.length < MIN_LITERAL_LENGTH) return false;
+  literals.add(v);
+  literalOrder = null;
+  const m = v.match(/^[a-z][a-z0-9+.-]*:\/\/([^/@\s]+)@/i);
+  if (m && m[1].includes(':')) {
+    const [, pass] = m[1].split(/:(.*)/s);
+    if (pass && pass.length >= MIN_LITERAL_LENGTH) literals.add(pass);
+  }
+  return true;
+}
+
+/** Registers every secret-bearing value in an env object (defaults to process.env). */
+export function registerSecretsFromEnv(env = process.env) {
+  let n = 0;
+  for (const [k, v] of Object.entries(env)) {
+    if (SECRET_ENV_NAME.test(k) && registerSecret(v)) n++;
+  }
+  return n;
+}
+
+/** Test seam. Not for production use. */
+export function _clearRegisteredSecrets() {
+  literals.clear();
+  literalOrder = null;
+}
+
+// Longest-first order, computed once per registry change rather than once per
+// write. The registry changes at startup and effectively never again; sorting
+// it on every scrub was work repeated for no reason.
+let literalOrder = null;
+function orderedLiterals() {
+  if (literalOrder === null) literalOrder = [...literals].sort((a, b) => b.length - a.length);
+  return literalOrder;
+}
+
+export function registeredSecretCount() {
+  return literals.size;
+}
+
+// A necessary-condition prefilter for the key/value rule. Every alternative in
+// KEY_NAMES contains one of these substrings, so text without any of them
+// cannot match - and skipping the full pattern then is free correctness.
+const KEY_HINT = /pass|secret|token|key|authorization|credential/i;
+
+// Pattern rules. Each replaces with a function so the hit count is exact.
+// `pre` is a cheap NECESSARY condition: a substring the full pattern cannot
+// match without. It never decides a match - it only decides whether the
+// expensive scan is worth starting.
+const KEY_NAMES = '(?:pass(?:phrase|word|wd)|secret|token|api[_-]?key|client_secret|access_token|refresh_token|authorization|credential)';
+const RULES = [
+  // scheme://user:password@host  ->  scheme://*****:*****@host
+  { name: 'uri-credentials', pre: (t) => t.includes('://'),
+    re: /([a-z][a-z0-9+.-]*:\/\/)([^/@\s:]+):([^/@\s]+)@/gi, sub: (_m, scheme) => `${scheme}${MASK}:${MASK}@` },
+  // Bearer <token>
+  { name: 'bearer', pre: (t) => t.includes('Bearer'),
+    re: /\b(Bearer)\s+[A-Za-z0-9._~+/=-]{8,}/g, sub: (_m, w) => `${w} ${MASK}` },
+  // JWT
+  { name: 'jwt', pre: (t) => t.includes('eyJ'),
+    re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, sub: () => MASK },
+  // key: value / key = value / "key": "value"   (key survives, value is masked)
+  { name: 'key-value',
+    // Every alternative in KEY_NAMES contains one of these substrings, and the
+    // rule also requires a ':' or '='. Both are NECESSARY conditions, so
+    // failing this check cannot skip a match the full pattern would have found.
+    pre: (t) => KEY_HINT.test(t) && (t.includes(':') || t.includes('=')),
+    // The scheme words of an Authorization header are not the secret; the
+    // bearer rule above has already masked what followed them.
+    // G5 (2026-09-07): the prefix class lets a header name like x-api-key
+    // through, but it also let "re-authorization:" in prose count as a key and
+    // mask the word after it (thread §32). An English prefix joined by a hyphen
+    // is not a key name: re-, pre-, de-, un-, non- are excluded right before
+    // the key word.
+    // G6 (2026-09-07): the value stops at a backtick and does not swallow a
+    // trailing period or closing parenthesis - prose like `passphrase: x`. kept
+    // losing its closing backtick and full stop. A secret that itself ends in
+    // "." or ")" keeps that one character visible; accepted.
+    re: new RegExp(`(["']?\\b[\\w.-]*(?<!\\b(?:re|pre|de|un|non)-)${KEY_NAMES}["']?\\s*[:=]\\s*)(["']?)(?!(?:Bearer|Basic|Digest)\\b)(?=[^\\s"'\`,;}\\]]{4})([^\\s"'\`,;}\\]]*[^\\s"'\`,;}\\].)])([.)]*)(\\2)`, 'gi'),
+    sub: (_m, key, q, _v, trail, q2) => `${key}${q}${MASK}${trail}${q2}` }
+];
+
+/**
+ * Redacts a string. Returns { text, hits } where hits is the number of
+ * replacements made. Non-strings are returned unchanged with hits 0.
+ */
+export function redactWithReport(input) {
+  if (typeof input !== 'string' || input.length === 0) return { text: input, hits: 0 };
+  let text = input;
+  let hits = 0;
+  // Literals first: exact, longest first so a value that contains another is
+  // masked whole rather than leaving a fragment.
+  //
+  // These are literal strings, so they need no regex at all. The previous
+  // version compiled one RegExp per literal PER CALL and scanned the whole body
+  // with it whether or not the literal was present. indexOf answers "is it
+  // here" far more cheaply than a regex scan, and split/join is the same
+  // operation as a global replace on an escaped literal - identical output,
+  // identical hit count.
+  for (const lit of orderedLiterals()) {
+    if (!text.includes(lit)) continue;
+    const parts = text.split(lit);
+    hits += parts.length - 1;
+    text = parts.join(MASK);
+  }
+  // G4 (2026-09-07): a hit is a CHANGE. Text that already carries the mask
+  // ("passphrase: *****") matches the key/value rule and is replaced with
+  // itself; counting that made every read-modify-write of a document report
+  // the masks it already held as new redactions. The receipt's `redacted` is
+  // the number of spans this write changed - nothing else.
+  for (const rule of RULES) {
+    // The prefilter is a necessary condition for the pattern, so skipping on a
+    // miss cannot change the output. It exists because the scrubber was paying
+    // nearly full price on documents containing no secrets at all: measured
+    // 2026-09-08, a clean 300 KB body cost 6.40 ms against 7.25 ms for a
+    // secret-bearing one. The cost was scanning, not replacing.
+    if (rule.pre && !rule.pre(text)) continue;
+    text = text.replace(rule.re, (...args) => {
+      const out = rule.sub(...args);
+      if (out !== args[0]) hits++;
+      return out;
+    });
+  }
+  return { text, hits };
+}
+
+/** Convenience: the redacted string only. */
+export function redactText(input) {
+  return redactWithReport(input).text;
+}
+
+const SECRET_KEY = new RegExp(`^[\\w.-]*${KEY_NAMES}$`, 'i');
+
+/**
+ * Deep-redacts any value: strings are scrubbed; object keys that name a secret
+ * have their value masked outright regardless of content; arrays and plain
+ * objects are walked. Other types pass through. Returns { value, hits }.
+ */
+export function redactDeep(value, _seen = new WeakSet()) {
+  if (typeof value === 'string') {
+    const r = redactWithReport(value);
+    return { value: r.text, hits: r.hits };
+  }
+  if (Array.isArray(value)) {
+    let hits = 0;
+    const out = value.map(v => { const r = redactDeep(v, _seen); hits += r.hits; return r.value; });
+    return { value: out, hits };
+  }
+  if (value && typeof value === 'object') {
+    if (_seen.has(value)) return { value, hits: 0 };
+    _seen.add(value);
+    if (value instanceof Date || Buffer.isBuffer?.(value)) return { value, hits: 0 };
+    let hits = 0;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (SECRET_KEY.test(k) && v !== null && v !== undefined && v !== '' && typeof v !== 'object') {
+        // G4: an already-masked value is left as it is and not counted.
+        if (v === MASK) { out[k] = v; } else { out[k] = MASK; hits++; }
+      } else {
+        const r = redactDeep(v, _seen); hits += r.hits; out[k] = r.value;
+      }
+    }
+    return { value: out, hits };
+  }
+  return { value, hits: 0 };
+}
+
+// Load-time registration: the process's own secrets are always known to it.
+registerSecretsFromEnv();