@swfte/nexus-sdk 0.1.0

package/src/redact.cjs

@@ -0,0 +1,734 @@
+'use strict';
+/**
+ * In-process scrubbing, before anything is queued.
+ *
+ * A port of the Python SDK's `nexus/redact.py`, kept deliberately close to it: the two SDKs write
+ * into one ledger, and `tier: 'full'` has to mean the same thing in both or a customer who read one
+ * README and deployed the other gets a surprise made of their users' data.
+ *
+ * Obfuscation happens at the source, never at the backend — the one thing from Datadog's design
+ * worth copying without modification. Once a secret has left the process it has left the process;
+ * "we redact on ingest" is a promise about somebody else's infrastructure that a security review
+ * cannot verify.
+ *
+ * This is a deliberately smaller redactor than the wrapper's `nexus_devtools/redact.py`, and the
+ * difference is a design decision rather than an omission. That one runs on a developer's laptop
+ * against arbitrary shell output and can afford entropy heuristics and a wide pattern set. This one
+ * runs on the request path of a production service, where the cost is paid per call by somebody
+ * else's end users — so it is a bounded set of anchored patterns plus key-name matching, compiled
+ * once, with no entropy scan over unbounded text.
+ *
+ * The compensating control is that the **default tier is `metadata_only`**: at T0 no free text is
+ * transmitted at all, so redaction is a second line of defence rather than the only one.
+ *
+ * **Redaction failing must fail closed on the field, not on the event** (case 5.8). Dropping the
+ * whole event because one string could not be scrubbed also drops the governance record, which is
+ * exactly the record you most want when something odd is happening.
+ *
+ * ── What is different from the Python, and why ────────────────────────────────────────────────
+ *
+ * Three things could not be transliterated, and each is a correctness issue rather than a style
+ * one. They are called out where they occur, but in summary:
+ *
+ * 1. **Unicode classes.** Python's `re.UNICODE` makes `\w` and `[^\W\d_]` mean "any script".
+ *    JavaScript's `\w` is ASCII-only even with the `u` flag, so `[^\W\d_]` would have silently
+ *    become "ASCII letter" and `jane@example.中国` would have stopped being an email address — the
+ *    exact defect the Python file's comment says it fixed. Written with `\p{L}` instead.
+ * 2. **The IBAN checksum.** Python builds one arbitrarily large integer and takes `% 97`.
+ *    JavaScript numbers lose integer precision past 2^53, so a 34-character IBAN would produce a
+ *    rounded value and a checksum that passes or fails at random. Computed incrementally instead,
+ *    which is exact.
+ * 3. **Regex state.** A `g`-flagged regex in JavaScript carries a mutable `lastIndex`, so calling
+ *    `.test()` on a shared one gives a different answer every other call. Every anchored predicate
+ *    here uses a non-global regex, and every scanner goes through `String.replace`, which resets it.
+ */
+
+const MASK = '[REDACTED]';
+
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// credentials
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Opening markers of secrets whose pattern has **no bounded length**, so a match can require
+ * arbitrarily many characters to complete. Everything else this module hunts is short and either
+ * matches inside the scan window or starts past the emitted prefix and is truncated away. See
+ * {@link scanWindow}.
+ */
+const UNTERMINATED_MARKERS = ['-----BEGIN'];
+
+/**
+ * A `name =` / `name:` opener, used to answer the question the marker list cannot: *did the emitted
+ * prefix stop in the middle of somebody's secret?*
+ *
+ * A 9 kB `password = "…"` runs past the scan window, never meets its closing quote, matches no
+ * pattern, and would ship its first 280 characters. This is a post-condition on the output: the
+ * last assignment visible in the emitted text is looked up in {@link isSensitiveKey} and, if the
+ * mask does not follow it, the value ran past what we could scan. It needs no list of secret
+ * shapes, so a vendor format nobody has invented yet is covered on the day it appears.
+ */
+const ASSIGN_OPENER_RE = /([A-Za-z_][A-Za-z0-9_\-]{0,63})\s*[:=]/g;
+
+/**
+ * Anchored, high-precision patterns. Order matters only in that longer forms come first.
+ *
+ * The set was chosen from the LLM-vendor list, which is the wrong axis: this SDK watches agents
+ * *calling tools*, and the credential an agent hands a tool is a payments key or a package-registry
+ * token far more often than it is a model key. Each of the second group was measured leaking
+ * through the Python `redact()` before being added there.
+ *
+ * Deliberately NOT here: bare 32-hex. It is the shape of an Azure key and also the shape of every
+ * MD5 in every log line this SDK will ever see, and a rule that masks content hashes deletes the
+ * record it exists to protect. `sk_test_` IS included alongside `sk_live_`: a test key is still a
+ * credential, and telling them apart is the customer's job, not ours.
+ */
+const PATTERNS = [
+  /\bsk-ant-[A-Za-z0-9_-]{16,}/gi,                                        // Anthropic
+  /\bsk-proj-[A-Za-z0-9_-]{16,}/gi,                                       // OpenAI project keys
+  /\bsk-[A-Za-z0-9]{20,}/gi,                                              // OpenAI classic
+  /\bAIza[0-9A-Za-z_-]{30,}/gi,                                           // Google API
+  /\bAKIA[0-9A-Z]{16}\b/gi,                                               // AWS access key id
+  /\bASIA[0-9A-Z]{16}\b/gi,                                               // AWS temporary key id
+  /\bgh[pousr]_[A-Za-z0-9]{20,}/gi,                                       // GitHub
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}/gi,                                     // Slack
+  /\bey[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/gi,     // JWT
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/gi,
+  /\bhf_[A-Za-z0-9]{20,}/gi,                                              // HuggingFace
+  /\b[sr]k_(?:live|test)_[A-Za-z0-9]{20,}/gi,                             // Stripe secret/restricted
+  /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/gi,                       // SendGrid
+  /\bnpm_[A-Za-z0-9]{30,}/gi,                                             // npm automation token
+  /\bpypi-[A-Za-z0-9_-]{32,}/gi,                                          // PyPI API token
+  /\bglpat-[A-Za-z0-9_-]{20}/gi,                                          // GitLab PAT
+  /\bdop_v1_[a-f0-9]{64}/gi,                                              // DigitalOcean
+];
+
+/**
+ * The words that make a *name* sensitive, written once.
+ *
+ * Two rules consume this alternation — the `key=value` rule that runs over prose, and the key-name
+ * rule that runs over mapping keys — and they are deliberately two separately compiled patterns
+ * rather than one built out of the other. Sharing the vocabulary keeps them from drifting; building
+ * one from the other makes one of them a no-op, which is a defect the Python file carries a long
+ * comment about having shipped.
+ *
+ * These are safe as substrings — no ordinary English or field-name word contains them — so they
+ * live here rather than in the segment list below. The test for membership is not "is this secret"
+ * but "can this word appear inside an innocent name": `cvv` cannot, `pin` can (`shipping`), and
+ * that is the whole basis for the split.
+ */
+const SENSITIVE_WORDS =
+  'api[_\\-]?key|secret|token|password|passwd|passphrase|credential|' +
+  'authorization|session[_\\-]?id|private[_\\-]?key|access[_\\-]?key|cookie|' +
+  'mnemonic|totp|cvv|cvc|mfa[_\\-]?code|recovery[_\\-]?code|seed[_\\-]?phrase';
+
+/**
+ * Words sensitive only as a **whole segment** of a name.
+ *
+ * `auth` as a substring also condemns `author` and `authored_by` — which are not secrets, and are
+ * precisely the fields a governance ledger exists to carry. A rule that masks the author of a
+ * deploy has stopped protecting anything and started deleting the record. Likewise `pin` inside
+ * `shipping`, `otp` inside `dotproduct`, `dob` inside `dobson`.
+ *
+ * Deliberately absent, having been considered and rejected upstream: `pass` (`pass_rate`,
+ * `first_pass` are metrics, and `password`/`passwd`/`passphrase` already cover the credential),
+ * `salt`, `nonce` and `sig` (public by construction — masking a signature deletes the governance
+ * record without protecting anything), and `refresh` (`refresh_token` is already caught by `token`;
+ * `refresh` alone is an interval).
+ */
+const SEGMENT_WORDS = 'auth|pwd|pin|otp|ssn|dob|jwt|bearer';
+
+const SEGMENT_IN_NAME = '(?:[A-Za-z0-9]+[_\\-])*(?:' + SEGMENT_WORDS + ')(?:[_\\-][A-Za-z0-9]+)*';
+
+/**
+ * `KEY=value` / `"key": "value"` / `--token value` / `Authorization: Bearer …`
+ *
+ * Prose, so `auth` stays in: `auth = hunter2hunter2` in a log line is a credential whatever the
+ * surrounding sentence is, and the value group's four-character floor keeps it off ordinary text.
+ * Both vocabularies are spelled with the scope each one requires, in BOTH rules — splicing the
+ * segment words in as bare substrings here makes `pin` mask `shipping: 12345` and `otp` mask
+ * `dotproduct = 0.9871`.
+ *
+ * Three capture groups, and the count is load-bearing: the replacement keeps 1 and 2 and masks 3.
+ */
+const SENSITIVE_KEY = new RegExp(
+  '\\b(' + SEGMENT_IN_NAME + '|[A-Za-z0-9_\\-]*(?:' + SENSITIVE_WORDS + ')[A-Za-z0-9_\\-]*)' +
+  '(\\s*[:=]\\s*|\\s+)' +
+  '("[^"]{4,}"|\'[^\']{4,}\'|[^\\s,;\'"})]{4,})',
+  'gi');
+
+/**
+ * A mapping key whose *name* alone condemns its value. Anchored end to end over a character class
+ * that includes `.`, so `x-api-key`, `AWS_SECRET_ACCESS_KEY` and `db_password` match while
+ * `headers` does not — that one is recursed into instead.
+ *
+ * Non-global on purpose: it is used with `.test()`, and a `g` flag would make it stateful.
+ */
+const SENSITIVE_NAME = new RegExp(
+  '^[A-Za-z0-9_\\-.]*(?:' + SENSITIVE_WORDS + ')[A-Za-z0-9_\\-.]*$', 'i');
+
+/**
+ * The segment-scoped rule: the word must occupy whole `_`/`-`/`.`-delimited segments of the name.
+ * `auth`, `auth_token` and `req.auth` match; `authored_by` does not.
+ */
+const SENSITIVE_SEGMENT = new RegExp(
+  '^(?:[A-Za-z0-9]+[_\\-.])*(?:' + SEGMENT_WORDS + ')(?:[_\\-.][A-Za-z0-9]+)*$', 'i');
+
+const BEARER = /\b(bearer|basic|token)\s+([A-Za-z0-9._\-+/=]{8,})/gi;
+
+/** userinfo in a URL: `https://user:pass@host/…` */
+const URL_USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/)([^/@\s:]+):([^/@\s]+)@/gi;
+
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// personal data — the *second* line of defence, never the first
+//
+// The first line is the tier: at `metadata_only` no free text reaches the wire at all, so none of
+// the patterns below has to be right for the default configuration to be safe. They earn their
+// place at T1/T2, where a customer has consciously opted into content and still should not ship a
+// card number by accident.
+//
+// The set is small and anchored, for the reason in the module header: this runs on somebody else's
+// request path. It is also, by construction, incomplete — `John Doe` is not recognisable by any
+// regular expression, and a field that names a patient will always leak at T2. That is an argument
+// for the tier gate being the primary control, not for a longer pattern list here.
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Unicode dashes. A card number pasted out of a word processor, a PDF or a CRM arrives with U+2011
+ * (non-breaking hyphen) or U+2013 (en dash) where the author typed a hyphen, and to the reader it
+ * is identical. Written as a character class rather than by normalising the input, because
+ * normalising would change the very text we are about to emit — NFKC is not length-preserving, so
+ * every match offset would then be an offset into a string the caller never gave us.
+ */
+const DASHES = '\\-\u2010\u2011\u2012\u2013\u2014\u2015\u2212\uff0d';
+
+/**
+ * Email.
+ *
+ * **This is the rule the unicode difference bites hardest.** Python spells the domain and TLD
+ * `[^\W\d_]` under `re.UNICODE`, which means "a letter in any script" and is what lets
+ * `jane@example.中国` — an internationalised domain, ordinary in half the world — be recognised.
+ * JavaScript's `\w` stays ASCII even under the `u` flag, so the literal transliteration would have
+ * quietly narrowed the rule back to ASCII-only and reintroduced the exact defect Python's comment
+ * records fixing. `\p{L}` is the honest equivalent.
+ *
+ * The boundaries are lookarounds rather than `\b` for the same reason: `\b` is ASCII-defined in
+ * JavaScript, so it would fire in the middle of a non-ASCII TLD.
+ */
+const EMAIL = /(?<![A-Za-z0-9._%+\-])[A-Za-z0-9._%+\-]+@\p{L}(?:[\p{L}\p{N}_.\-]*[\p{L}\p{N}_])?\.\p{L}{2,24}(?!\p{L})/gu;
+
+/**
+ * US SSN and the national-ID shapes that share its form. Applied before the phone rules, which
+ * overlap it; the more specific rule must win.
+ *
+ * The separator is any of space / dot / dash, but **the same one twice** — the backreference is
+ * what keeps this off `123 45-6789`-shaped coincidences and, more importantly, off arbitrary digit
+ * soup. A bare `123456789` is deliberately NOT matched: nine digits with no separator is also every
+ * order id, every epoch-ish counter and every autoincrement primary key in the corpus, and a rule
+ * that masks all of them stops being a redactor and starts being a censor.
+ */
+const NATIONAL_ID = new RegExp(
+  '(?<![\\d' + DASHES + '])\\d{3}([ .' + DASHES + '])\\d{2}\\1\\d{4}(?![\\d' + DASHES + '])', 'g');
+
+/**
+ * IBAN. Gated on the ISO 7064 mod-97 checksum for the same reason {@link CARD} is gated on Luhn:
+ * the shape alone (two letters, two digits, alphanumerics) matches product SKUs and git refs.
+ */
+const IBAN = /\b[A-Za-z]{2}\d{2}[A-Za-z0-9]{11,30}\b/g;
+
+/**
+ * E.164 and the written NANP forms. The lookarounds keep it off version strings and durations.
+ *
+ * An extension has to be *consumed*, not merely tolerated: the trailing `(?![\w\-])` is what keeps
+ * this rule off version strings, so it cannot simply be relaxed. Without the extension branch,
+ * `415.555.2671x22` was not a phone number — and a direct line with an extension is more
+ * identifying than one without, not less.
+ */
+const PHONE = new RegExp(
+  '(?<![\\w.\\-])(?:\\+\\d{1,3}[ .\\-]?)?(?:\\(\\d{3}\\)[ .\\-]?|\\d{3}[ .\\-])\\d{3}[ .\\-]\\d{4}' +
+  '(?:[ ]?(?:x|ext\\.?|extension)[ ]?\\d{1,6})?(?![\\w\\-])' +
+  '|(?<![\\w.\\-])\\+\\d{9,15}(?![\\w\\-])', 'g');
+
+/**
+ * Payment-card candidates. Shape alone over-matches every long integer in a log line, so a
+ * candidate is masked only once it passes Luhn — precision bought for a few microseconds.
+ */
+const CARD = new RegExp(
+  '(?<![\\d' + DASHES + '])(?:\\d[ .' + DASHES + ']?){12,18}\\d(?![\\d' + DASHES + '])', 'g');
+
+function luhn(digits) {
+  let total = 0;
+  let alt = false;
+  for (let i = digits.length - 1; i >= 0; i -= 1) {
+    let d = digits.charCodeAt(i) - 48;
+    if (alt) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    total += d;
+    alt = !alt;
+  }
+  return total % 10 === 0;
+}
+
+function maskCard(m) {
+  const digits = m.replace(/\D/g, '');
+  return digits.length >= 13 && digits.length <= 19 && luhn(digits) ? MASK : m;
+}
+
+/**
+ * ISO 7064 mod-97: rotate the first four characters to the end, letters as A=10..Z=35, `% 97 == 1`.
+ *
+ * Same role as {@link luhn} — it turns a shape that over-matches into a rule precise enough to run
+ * on somebody else's request path. `GB29NWBK60161331926819` passes; `DE49PRODUCTSKU12345` does not,
+ * and neither does a git ref that happens to start with two letters and two digits.
+ *
+ * **Computed incrementally rather than as one integer, and that is not a micro-optimisation.**
+ * Python can take `% 97` of an arbitrarily large int exactly. A 34-character IBAN expands to a
+ * ~40-digit number, which in JavaScript is far past `Number.MAX_SAFE_INTEGER` — the literal port
+ * would round it and then decide the checksum from whatever the rounding produced, passing and
+ * failing effectively at random. Reducing digit by digit is exact and needs no BigInt.
+ */
+function ibanOk(s) {
+  const up = String(s).toUpperCase();
+  const rotated = up.slice(4) + up.slice(0, 4);
+  let remainder = 0;
+  for (let i = 0; i < rotated.length; i += 1) {
+    const code = rotated.charCodeAt(i);
+    let part;
+    if (code >= 65 && code <= 90) part = String(code - 55);        // A..Z -> 10..35
+    else if (code >= 48 && code <= 57) part = String(code - 48);   // 0..9
+    else return false;
+    for (let j = 0; j < part.length; j += 1) {
+      remainder = (remainder * 10 + (part.charCodeAt(j) - 48)) % 97;
+    }
+  }
+  return remainder === 1;
+}
+
+function maskIban(m) {
+  return ibanOk(m) ? MASK : m;
+}
+
+/**
+ * `[pattern, replacement]`. IBAN runs before {@link CARD}: an IBAN's digit run can be long enough
+ * for the card rule to consider it, and the more specific rule must win — the same ordering
+ * argument as {@link NATIONAL_ID} before {@link PHONE}.
+ */
+const PII_RULES = [
+  [EMAIL, () => MASK],
+  [NATIONAL_ID, () => MASK],
+  [IBAN, maskIban],
+  [CARD, maskCard],
+  [PHONE, () => MASK],
+];
+
+/**
+ * Return `{ text, redacted }`. Never throws — see case 5.8.
+ *
+ * On failure the whole string becomes the mask rather than propagating: the caller keeps its event,
+ * this one field becomes unreadable. That is the correct direction, because the alternative is
+ * dropping the governance record at exactly the moment something odd is happening.
+ */
+function redact(text) {
+  if (text === null || text === undefined || text === '') {
+    return { text: text === 0 ? '0' : (text || ''), redacted: false };
+  }
+  try {
+    let out = String(text);
+    const before = out;
+    for (const pat of PATTERNS) out = out.replace(pat, MASK);
+    out = out.replace(URL_USERINFO, (_m, scheme, user) => scheme + user + ':' + MASK + '@');
+    out = out.replace(BEARER, (_m, kind) => kind + ' ' + MASK);
+    out = out.replace(SENSITIVE_KEY, (_m, name, sep) => name + sep + MASK);
+    for (const [pat, repl] of PII_RULES) out = out.replace(pat, repl);
+    return { text: out, redacted: out !== before };
+  } catch (_err) {
+    return { text: MASK, redacted: true };
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// URLs
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * A path segment that carries a secret rather than naming a resource. Two shapes:
+ *
+ * - twelve or more characters containing **both** a letter and a digit — `TOKEN123ABCDEF`,
+ *   `ORD-2026-0012`, a base62 invite code. Requiring both is what keeps `messages`, `completions`
+ *   and `pancreatic-carcinoma` out of it; requiring twelve is what keeps `v1` and `2026-08-27` out.
+ * - thirty-two or more characters of anything path-safe — the length alone is the tell.
+ *
+ * Numeric-only segments are deliberately kept. `/users/12345` is a resource id and it is what makes
+ * a path groupable.
+ */
+const PATH_TOKEN =
+  /^(?=[A-Za-z0-9._~-]{12,}$)(?=[^A-Za-z]*[A-Za-z])(?=[^0-9]*[0-9])[A-Za-z0-9._~-]+$|^[A-Za-z0-9._~-]{32,}$/;
+
+/**
+ * The path with token-shaped segments masked, then run through {@link redact}.
+ *
+ * Both steps are needed and neither subsumes the other. `redact` catches a JWT or an API key sitting
+ * in a path, because those have recognisable shapes; it cannot catch `/reset/TOKEN123ABCDEF`,
+ * because a random opaque string has no shape to recognise. The segment rule catches exactly that,
+ * by position and entropy-ish shape. Single-use credentials live in paths far more often than in
+ * queries — `/reset/<token>`, `/invite/<token>`, `/verify/<token>` are the standard shape of every
+ * password-reset email ever sent.
+ */
+function safePath(path) {
+  return redact(String(path).split('/')
+    .map((seg) => (PATH_TOKEN.test(seg) ? MASK : seg))
+    .join('/')).text;
+}
+
+/**
+ * scheme + host + path. Query, fragment and userinfo are dropped.
+ *
+ * A URL stops being metadata the moment it has a query string: `?q=…` is free text of exactly the
+ * class the tier gate just refused to store, and magic links carry single-use tokens that no
+ * pattern above can recognise.
+ */
+function safeUrl(u) {
+  try {
+    const parsed = new URL(String(u));
+    const host = parsed.port ? parsed.hostname + ':' + parsed.port : parsed.hostname;
+    return parsed.protocol + '//' + host + safePath(parsed.pathname);
+  } catch (_err) {
+    return MASK;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// key names
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Key names whose numeric value describes the *operation* rather than the subject of it. These are
+ * the numbers telemetry exists to carry, and they are what makes the tier gate affordable — without
+ * them `metadata_only` would emit no measurements at all and nobody would leave it on.
+ *
+ * An allowlist, not a denylist, and that direction is the whole point. A denylist of sensitive
+ * numeric names has to anticipate `ssn`, `mrn`, `iban`, `lat`, `salary` and whatever the next
+ * customer's schema calls them; it fails open on the first one nobody thought of. This fails
+ * closed: an unrecognised numeric key is masked, and the cost of being wrong is one masked metric
+ * that somebody notices and adds here.
+ */
+const STRUCTURAL_NUMBER_KEYS = new Set([
+  'attempt', 'attempts', 'batch', 'capacity', 'code', 'concurrency', 'count', 'depth',
+  'dropped', 'duration', 'elapsed', 'errors', 'exit_code', 'failures', 'hits', 'index',
+  'iteration', 'length', 'limit', 'lines', 'misses', 'offset', 'page', 'pending', 'port',
+  'position', 'priority', 'queued', 'retries', 'rows', 'size', 'status', 'status_code',
+  'step', 'timeout', 'tokens', 'total', 'version', 'weight',
+]);
+
+/**
+ * Suffixes that make a numeric key structural whatever its stem: `upload_bytes`,
+ * `render_duration_ms`, `retry_count`. Matching on the suffix rather than the whole name is what
+ * keeps the allowlist from needing an entry per metric a customer invents.
+ */
+const STRUCTURAL_NUMBER_SUFFIXES = [
+  '_bytes', '_count', '_duration', '_elapsed', '_index', '_len', '_length', '_limit', '_ms',
+  '_ns', '_offset', '_pct', '_percent', '_rate', '_ratio', '_retries', '_rows', '_s',
+  '_seconds', '_size', '_status', '_total', '_us',
+];
+
+const endsWithStructuralSuffix = (k) => STRUCTURAL_NUMBER_SUFFIXES.some((s) => k.endsWith(s));
+
+/**
+ * Whether a numeric value under this key is a measurement rather than a fact about a person.
+ *
+ * Deliberately conservative: it decides on the *name*, which is the only evidence available, and a
+ * name is weak evidence. `lat`/`lon`, `ssn`, `card` and `balance` are absent and therefore masked
+ * below `full`; `duration_ms` and `rows` are present and survive.
+ */
+function isStructuralNumberKey(key) {
+  const k = String(key).trim().toLowerCase();
+  return STRUCTURAL_NUMBER_KEYS.has(k) || endsWithStructuralSuffix(k);
+}
+
+/**
+ * The same question for the elements of a *list* under this key — and a stricter answer.
+ *
+ * A list element has no name of its own, so it can only inherit its parent key's verdict. But the
+ * two halves of the allowlist do not survive that inheritance equally, and treating them as if they
+ * did is how `{ rows: [123456789, 4111111111111111] }` would ship at `metadata_only`:
+ *
+ * - The **suffix** half names a *unit* — `_ms`, `_bytes`, `_pct`. A unit means the same thing
+ *   whether the key holds one measurement or a hundred, so `durations_ms: [12, 15, 402]` is exactly
+ *   as structural as `duration_ms: 12`. These inherit.
+ * - The **bare-name** half names a *quantity* — `count`, `rows`, `batch`, `depth`. Under a scalar
+ *   that is the tally; under a list it is the things being tallied, which is the opposite of
+ *   structural. These do not inherit.
+ */
+function isStructuralNumberKeyForSequence(key) {
+  return endsWithStructuralSuffix(String(key).trim().toLowerCase());
+}
+
+/**
+ * Codepoint ranges for the scripts whose letterforms are confusable with ASCII: Greek and Cyrillic.
+ * Named as *classes* rather than as a list of homoglyph characters, because a list of characters is
+ * a list and the attacker picks the character.
+ */
+const CONFUSABLE_RANGES = [[0x0370, 0x03ff], [0x0400, 0x052f], [0x1f00, 0x1fff]];
+
+/**
+ * Whether `name` mixes ASCII letters with Cyrillic or Greek ones.
+ *
+ * `аpi_key` with a Cyrillic `а` renders identically to `api_key` and matches neither pattern, so the
+ * value would ship. NFKC does not help: Cyrillic `а` and Latin `a` are different letters in
+ * different scripts, not compatibility variants of one letter, and Unicode is right about that.
+ *
+ * So this asks a different question — not "is this character a homoglyph" but "is this name written
+ * in one script". A field name that mixes ASCII with Cyrillic is mojibake or an attack; it is not a
+ * name a developer typed on purpose. Fails closed on the mix.
+ *
+ * Only these two scripts are named, and only against ASCII. A name written wholly in Cyrillic,
+ * Greek, Japanese or Arabic is somebody's ordinary field name and is left entirely alone — the rule
+ * is about the *mixture*, which is the thing that has no innocent reading.
+ */
+function hasConfusableScript(name) {
+  let hasAscii = false;
+  let hasConfusable = false;
+  for (const ch of String(name)) {
+    // `\p{L}` rather than a case-comparison trick: the question is "is this a letter in any
+    // script", and only a unicode property escape answers it for Greek and Cyrillic alike.
+    if (!/\p{L}/u.test(ch)) continue;
+    const o = ch.codePointAt(0);
+    if (o < 128) hasAscii = true;
+    else if (CONFUSABLE_RANGES.some(([lo, hi]) => o >= lo && o <= hi)) hasConfusable = true;
+    if (hasAscii && hasConfusable) return true;
+  }
+  return false;
+}
+
+/**
+ * Does this mapping key's *name* alone condemn its value?
+ *
+ * Fails closed: an unrepresentable key is treated as sensitive. Masking a harmless value costs a
+ * field; not masking a harmful one costs a credential.
+ *
+ * **The name is normalised before it is matched, and that is a bug fix rather than a courtesy.**
+ * Both patterns are anchored over a character class that excludes whitespace, so `"API_KEY "` — one
+ * trailing space — fails the match outright and ships the value. Keys arrive with stray whitespace
+ * constantly: parsed headers, CSV columns, YAML round-trips, hand-written JSON. NFKC additionally
+ * folds the compatibility forms (fullwidth `ａｐｉ＿ｋｅｙ` is the same key wearing different
+ * codepoints).
+ */
+function isSensitiveKey(key) {
+  try {
+    const name = String(key).normalize('NFKC').trim();
+    if (hasConfusableScript(name)) return true;
+    return SENSITIVE_NAME.test(name) || SENSITIVE_SEGMENT.test(name);
+  } catch (_err) {
+    return true;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// the bounded scan
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * How much text is scanned beyond the emitted limit.
+ *
+ * Redacting a whole input and then keeping 256 characters makes every pattern walk a megabyte to
+ * produce a tweet. Scanning a window slightly wider than the limit keeps the cost constant while
+ * leaving room for a secret that straddles the cut — truncating first, exactly at the limit, would
+ * slice a key in half and ship the surviving prefix.
+ */
+const SCAN_OVERSCAN = 4096;
+
+/**
+ * Ceiling on how much text is scanned when the caller asked for no truncation at all. Some bound
+ * has to exist or the absence of a limit is an unbounded regex walk on the caller's request thread;
+ * 64 KiB is far above any free-text field a sane caller emits and far below the point where the
+ * walk is felt.
+ */
+const FULL_SCAN_CEILING = 65536;
+
+/**
+ * Redact with a bounded scan. Returns `{ text, redacted, unfinished }`.
+ *
+ * The single implementation of two rules, so that no caller can hold a different opinion about
+ * either one:
+ *
+ * - **Scan a bounded window, not the whole input.**
+ * - **Never emit the prefix of something you could not finish scanning.** The overscan covers a
+ *   secret straddling the cut. It cannot cover one *longer than the window*, because a PEM needs
+ *   its `-----END` terminator before the pattern fires — so the first `limit` characters, which are
+ *   the start of the key, would ship untouched. `unfinished` reports that, and every caller turns
+ *   it into a mask.
+ *
+ * `unfinished` is a post-condition on the *output* rather than a guess about the input, so it
+ * generalises to the next unterminated pattern instead of enumerating this one. Two questions are
+ * asked of the emitted text: does an unbounded-length opener survive in it, and does the last
+ * assignment in it name something sensitive with no mask after it — meaning the value is still
+ * running when the output stops. Both are linear in the emitted prefix, which is already bounded.
+ */
+function scanWindow(text, limit) {
+  const s = String(text);
+  const window = limit === null || limit === undefined ? FULL_SCAN_CEILING : limit + SCAN_OVERSCAN;
+  const truncated = s.length > window;
+  const r = redact(s.slice(0, window));
+  let scrubbed = r.text;
+  if (limit !== null && limit !== undefined) scrubbed = scrubbed.slice(0, limit);
+
+  let unfinished = UNTERMINATED_MARKERS.some((m) => scrubbed.includes(m));
+  if (!unfinished && truncated) {
+    let last = null;
+    // `matchAll` rather than `exec` in a loop: the shared pattern is `g`-flagged, and `exec`
+    // would mutate its `lastIndex` across calls — the JavaScript hazard with no Python analogue.
+    for (const m of scrubbed.matchAll(ASSIGN_OPENER_RE)) last = m;
+    if (last !== null && isSensitiveKey(last[1])) {
+      unfinished = !scrubbed.slice(last.index + last[1].length).includes(MASK);
+    }
+  }
+  return { text: scrubbed, redacted: r.redacted, unfinished };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// the tier ladder's leaves
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * The three tiers, defined here rather than in `core.cjs`.
+ *
+ * They used to live in the core, which meant this module could not name them without a circular
+ * require. Since the redactor is the thing that *acts* on a tier, it is the honest owner of the
+ * vocabulary, and the core imports it from here.
+ */
+const TIER_METADATA_ONLY = 'metadata_only';
+const TIER_HASHED = 'hashed';
+const TIER_FULL = 'full';
+
+/**
+ * The single gate every free-text field passes through when a caller wants one string back.
+ *
+ * It lives in one function rather than at the call sites because that is precisely how these fields
+ * leaked in the wrapper: one shell command was redacted on the `tool_action` path and shipped raw
+ * on three others. A gate here cannot be forgotten by the next call site.
+ *
+ * **Three tiers, three branches.** At T0 this returns `null`, and the envelope builder drops keys
+ * whose value is `null`, so the field is *absent* rather than blanked — a reader can tell "no
+ * content was captured" from "the content was empty". Returning `null` also means a new tier, or a
+ * typo, degrades to silence rather than to egress, which is the only failure direction worth having.
+ */
+function wireText(text, tier, limit) {
+  if (text === null || text === undefined) return null;
+  const s = String(text);
+  if (!s) return s;
+  if (tier !== TIER_FULL && tier !== TIER_HASHED) return null;
+  const r = scanWindow(s, limit === undefined ? 512 : limit);
+  return r.unfinished ? MASK : r.text;
+}
+
+/**
+ * Structured redaction — the common miss.
+ *
+ * Tool arguments and structured outputs are objects, not prompt strings, and a redactor that only
+ * walks free text passes an API key straight through when it arrives as
+ * `{ headers: { Authorization: 'Bearer …' } }`. Bounded in width and depth so a pathological
+ * payload cannot turn scrubbing into the slow part of a request.
+ *
+ * Three rules worth stating, each of which was a defect somewhere before it was a rule:
+ *
+ * - A sensitive **name** masks the whole value whatever its type. `{ api_key: 12345678 }` and
+ *   `{ auth: { token: '…' } }` are both condemned by the name; descending into them to scrub the
+ *   leaves would emit the shape of a credential, and a credential's shape is a credential. This
+ *   over-approximates — a field named `token_count` masks a harmless integer — and the trade is
+ *   deliberate: a false positive costs one number, a false negative costs a secret.
+ * - **A number's type says nothing about its sensitivity.** `{ ssn: 123456789, card:
+ *   4111111111111111 }` would otherwise pass every tier unchanged while the same values as strings
+ *   were correctly dropped — a type-confusion hole, not a policy decision. So numbers go through
+ *   the structural-name allowlist below `full`.
+ * - **Depth is bounded.** Without it the walk is capped only by the stack.
+ *
+ * At T0 string values are dropped rather than blanked, for the reason in {@link wireText}.
+ * Booleans and `null` survive every tier — a flag is not content.
+ */
+function scrubMapping(data, tier, opts) {
+  const o = opts || {};
+  const maxKeys = o.maxKeys === undefined ? 32 : o.maxKeys;
+  const limit = o.limit === undefined ? 256 : o.limit;
+  const maxDepth = o.maxDepth === undefined ? 6 : o.maxDepth;
+
+  if (!data || typeof data !== 'object' || Array.isArray(data) || maxDepth <= 0) return {};
+  const out = {};
+  for (const k of Object.keys(data).slice(0, maxKeys)) {
+    const key = String(k).slice(0, 64);
+    const v = data[k];
+    if (isSensitiveKey(key)) { out[key] = MASK; continue; }
+
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      out[key] = scrubMapping(v, tier, { maxKeys, limit, maxDepth: maxDepth - 1 });
+    } else if (Array.isArray(v)) {
+      // The key's verdict travels with its elements, but only the half of it that survives the
+      // trip — see `isStructuralNumberKeyForSequence`. Without any inheritance a list under
+      // `durations_ms` would have every measurement masked below `full`, and the allowlist exists
+      // precisely so `metadata_only` still carries numbers somebody will look at.
+      out[key] = v.slice(0, 16).map((i) => scrubItem(i, tier, maxKeys, limit, maxDepth - 1,
+        isStructuralNumberKeyForSequence(key)));
+    } else if (v === null || v === undefined || typeof v === 'boolean') {
+      out[key] = v === undefined ? null : v;
+    } else if (typeof v === 'number' || typeof v === 'bigint') {
+      out[key] = (tier === TIER_FULL || isStructuralNumberKey(key)) ? v : MASK;
+    } else {
+      const scrubbed = wireText(String(v), tier, limit);
+      if (scrubbed !== null) out[key] = scrubbed;
+    }
+  }
+  return out;
+}
+
+/**
+ * One element of a list.
+ *
+ * The container types recurse into each other, and the depth budget is what stops it. Fixing a
+ * nesting hole at the level it was found — one more type check for the two-deep case — only moves
+ * it to three deep: `{ batch: [[{ api_key: '…' }]] }` is not exotic, it is a batch insert, a
+ * JSON-RPC batch, a paged tool result.
+ *
+ * A list element has no key of its own to judge, so it inherits its parent key's verdict for
+ * numbers. Without that, `{ rows: [123456789, 4111111111111111] }` comes through `metadata_only` —
+ * the tier that promises no content — completely unchanged.
+ */
+function scrubItem(item, tier, maxKeys, limit, maxDepth, numbersOk) {
+  if (maxDepth <= 0) return MASK;
+  if (item && typeof item === 'object' && !Array.isArray(item)) {
+    return scrubMapping(item, tier, { maxKeys, limit, maxDepth });
+  }
+  if (Array.isArray(item)) {
+    return item.slice(0, 16).map((i) => scrubItem(i, tier, maxKeys, limit, maxDepth - 1, numbersOk));
+  }
+  if (item === null || item === undefined || typeof item === 'boolean') {
+    return item === undefined ? null : item;
+  }
+  if (typeof item === 'number' || typeof item === 'bigint') {
+    return (tier === TIER_FULL || numbersOk) ? item : MASK;
+  }
+  return wireText(String(item), tier, limit);
+}
+
+module.exports = {
+  MASK,
+  TIER_METADATA_ONLY,
+  TIER_HASHED,
+  TIER_FULL,
+  redact,
+  scanWindow,
+  wireText,
+  scrubMapping,
+  safeUrl,
+  safePath,
+  isSensitiveKey,
+  isStructuralNumberKey,
+  isStructuralNumberKeyForSequence,
+  hasConfusableScript,
+  luhn,
+  ibanOk,
+  // Exported for tests that need to assert on the vocabulary rather than on one example.
+  SENSITIVE_WORDS,
+  SEGMENT_WORDS,
+  STRUCTURAL_NUMBER_KEYS,
+  STRUCTURAL_NUMBER_SUFFIXES,
+};