@link-foundation/sensitive-data-sanitizer 0.19.3 → 0.21.0

package/src/credentials-entry.js

@@ -0,0 +1,62 @@
+/**
+ * Credentials-only entry point (`@link-foundation/sensitive-data-sanitizer/credentials`).
+ *
+ * It loads the credential detectors without the personal-data detectors,
+ * faker or libphonenumber, so it starts faster and suits synchronous loggers.
+ * Every function here runs with `credentialsOnly: true` (issue 137).
+ */
+import {
+  inspect as inspectText,
+  sanitize as sanitizeText,
+  redact as redactText,
+} from './sanitizer.js';
+import { failure } from './detection.js';
+import { createSanitizer as createAsyncSanitizer } from './engines.js';
+import { createSyncSanitizer as createSync } from './sync-sanitizer.js';
+
+export { REDACTED, entropy } from './detection.js';
+export { builtInRules } from './rule-catalog.js';
+export { tokenChecksum, tokenWithChecksum } from './token-checksum.js';
+export {
+  reservedPlaceholderTypes,
+  isPlaceholderToken,
+} from './placeholder-types.js';
+export {
+  knownSecretsFromEnv,
+  knownSecretsFromGitHubAuth,
+  knownSecretsFromGitHubConfig,
+} from './known.js';
+
+function credentialOptions(options = {}) {
+  const transforms = [
+    options.transformation,
+    ...Object.values(options.transformations ?? {}),
+  ];
+  // The feature registry is shared by both entries in one process, so these
+  // options are rejected explicitly.
+  if (
+    options.credentialsOnly === false ||
+    options.properNames !== undefined ||
+    options.scripts !== undefined ||
+    transforms.some((transform) => transform?.mode === 'fake')
+  ) {
+    throw failure('ERR_CONFIG');
+  }
+  return { ...options, credentialsOnly: true };
+}
+
+export function inspect(text, options) {
+  return inspectText(text, credentialOptions(options));
+}
+export function sanitize(text, options) {
+  return sanitizeText(text, credentialOptions(options));
+}
+export function redact(text, findings, options) {
+  return redactText(text, findings, credentialOptions(options));
+}
+export function createSanitizer(options) {
+  return createAsyncSanitizer(credentialOptions(options));
+}
+export function createSyncSanitizer(options) {
+  return createSync(credentialOptions(options));
+}

package/src/credentials.js

@@ -7,6 +7,57 @@ export function credentialPlaceholder(value) {
     ) || referencePrefix(value)?.[0] === value
   );
 }
+// One template or mask token: ${NAME}, $${NAME}, $NAME, $1, <name>, [NAME],
+// ****, XXXX or an ellipsis. Values made only of these (optionally split by
+// a user:password colon) carry no credential material.
+// `hive-mask` and `mask` output (`ghp…b4N`, `ab***yz`; NFKC projection turns
+// `…` into `...`) keeps at most a few characters around the marker, so a
+// second pass leaves it unchanged.
+const templateToken =
+  /^(?:\$?\$\{[A-Za-z_][\w.-]*\}|\$[A-Za-z_]\w*|\$\d|<[^<>\r\n]{1,64}>|\[[A-Z][A-Z0-9_ ]{0,63}\]|[^\s…*.]{0,4}(?:…|\.{3}|\*{3,})[^\s…*.]{0,4}|[xX]{4,})$/u;
+// A whole value that is already a template, a mask or `[REDACTED]`.
+export function maskedValue(value) {
+  return credentialPlaceholder(value) || templateToken.test(value);
+}
+const unquote = (part) => part.replace(/^["']|["']$/g, '');
+
+function templatedValue(value) {
+  const body = value.replace(/^(?:token|Bearer|Basic)\s+/i, '');
+  const colon = body.indexOf(':');
+  const parts = (
+    colon < 0 ? [body] : [body.slice(0, colon), body.slice(colon + 1)]
+  ).map((part) => unquote(part.trim()));
+  return (
+    parts.some(Boolean) &&
+    parts.every((part) => !part || templateToken.test(part))
+  );
+}
+
+// Detectors stop at whitespace or brackets, so `<API token>` or `[PASSWORD]`
+// can arrive truncated; complete them from the following text first.
+export function templatedCredential(text, finding) {
+  if (finding.category !== 'credential' || finding.rule === 'known-secret') {
+    return false;
+  }
+  let value = text.slice(finding.start, finding.end);
+  const closer =
+    value.lastIndexOf('<') > value.lastIndexOf('>')
+      ? '>'
+      : value.lastIndexOf('[') > value.lastIndexOf(']')
+        ? ']'
+        : '';
+  if (closer) {
+    const rest = text.slice(finding.end, finding.end + 64);
+    const index = rest.indexOf(closer);
+    if (index < 0 || /[\r\n]/.test(rest.slice(0, index))) {
+      return false;
+    }
+    value += rest.slice(0, index + 1);
+  }
+  // A template glued to literal characters (`<x>abc`, `[A]x9`) is not one.
+  const after = text[finding.start + value.length] ?? '';
+  return !/[\w$%+/=.-]/.test(after) && templatedValue(value);
+}
 // Only variable references and the documented gh lookup are exempt. Arbitrary
 // shell commands and Actions expressions can contain literal credentials.
 export function referencePrefix(value) {

package/src/crypto-addresses.js

@@ -0,0 +1,74 @@
+import { createHash } from 'node:crypto';
+
+// Offline checksum validation for Bitcoin addresses (Presidio parity): legacy
+// Base58Check (P2PKH/P2SH) and SegWit Bech32/Bech32m. Ethereum addresses carry
+// no case-insensitive checksum and stay format-only.
+const base58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest();
+
+export function base58Check(value) {
+  let number = 0n;
+  for (const char of value) {
+    const digit = base58.indexOf(char);
+    if (digit < 0) {
+      return false;
+    }
+    number = number * 58n + BigInt(digit);
+  }
+  const hex = number.toString(16);
+  const body = Buffer.from(hex.length % 2 ? `0${hex}` : hex, 'hex');
+  const zeros = /^1*/.exec(value)[0].length;
+  const bytes = Buffer.concat([Buffer.alloc(zeros), body]);
+  if (bytes.length !== 25) {
+    return false;
+  }
+  const check = sha256(sha256(bytes.subarray(0, 21))).subarray(0, 4);
+  return check.equals(bytes.subarray(21));
+}
+
+const bech32Charset = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+function polymod(values) {
+  const generator = [
+    0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3,
+  ];
+  let checksum = 1;
+  for (const value of values) {
+    const top = checksum >>> 25;
+    checksum = ((checksum & 0x1ffffff) << 5) ^ value;
+    for (let i = 0; i < 5; i++) {
+      if ((top >>> i) & 1) {
+        checksum ^= generator[i];
+      }
+    }
+  }
+  return checksum >>> 0;
+}
+export function bech32Address(value) {
+  if (value !== value.toLowerCase() && value !== value.toUpperCase()) {
+    return false;
+  }
+  const lower = value.toLowerCase();
+  const separator = lower.lastIndexOf('1');
+  const prefix = lower.slice(0, separator);
+  const data = [...lower.slice(separator + 1)].map((char) =>
+    bech32Charset.indexOf(char)
+  );
+  if (!['bc', 'tb'].includes(prefix) || data.length < 7 || data.includes(-1)) {
+    return false;
+  }
+  const expanded = [
+    ...[...prefix].map((char) => char.charCodeAt(0) >> 5),
+    0,
+    ...[...prefix].map((char) => char.charCodeAt(0) & 31),
+    ...data,
+  ];
+  const constant = polymod(expanded);
+  return constant === 1 || constant === 0x2bc830a3;
+}
+
+export function cryptoAddress(value) {
+  if (/^0x[a-fA-F0-9]{40}$/.test(value)) {
+    return true;
+  }
+  return /^(?:bc|tb)1/i.test(value) ? bech32Address(value) : base58Check(value);
+}

package/src/detection.js

@@ -1,23 +1,25 @@
-import { cardNetwork, cardEvidence } from './confidence.js';
+import {
+  cardNetwork,
+  cardEvidence,
+  cardContext,
+  uatpCard,
+} from './confidence.js';
 import { isIP } from 'node:net';
+import { Buffer } from 'node:buffer';
 import { serviceRules } from './rules.js';
-import { detectContext, valueRange, authorizationRange } from './context.js';
-import { detectPersonal } from './personal.js';
+import { detectContext, valueRange, authorizationRanges } from './context.js';
 import { detectGitleaks } from './gitleaks.js';
-import { detectCatalog } from './entities.js';
-import { detectIdentity } from './identity.js';
-import { detectNational } from './national.js';
-import { detectPersonalContext } from './personal-context.js';
 import {
   detectCredentialFormats,
   credentialPlaceholder,
+  maskedValue,
 } from './credentials.js';
 import { localAddress } from './public.js';
 import { detectKnownPersonal } from './personal-variants.js';
-import { detectDocumentEntities } from './document-entities.js';
-import { detectProseAndDocuments } from './proper-names.js';
 import { builtInEnabled } from './policy.js';
-import { detectStrict } from './strict.js';
+import { feature } from './features.js';
+import { tokenChecksum } from './token-checksum.js';
+import { refineCredentialSpans, cookieValues } from './credential-spans.js';
 
 export const REDACTED = '[REDACTED]';
 export const failure = (code = 'ERR_SANITIZATION', location = {}) =>
@@ -49,6 +51,30 @@ export function personalPattern(value) {
     .map(escapePattern)
     .join('[ \\t_-]+');
 }
+// Hex and base64 spellings of a known secret, at any length. The generic
+// decoders need 16 or more encoded characters, so they cannot see short ones.
+const encodedForms = new Map();
+function knownEncodedForms(value) {
+  let pattern = encodedForms.get(value);
+  if (!pattern) {
+    const bytes = Buffer.from(value, 'utf8');
+    const hex = bytes.toString('hex');
+    const base64 = bytes.toString('base64').replace(/=+$/, '');
+    const url = bytes.toString('base64url');
+    const alternatives = [...new Set([hex, hex.toUpperCase()])].join('|');
+    const base64Forms = [...new Set([base64, url])].map(escapePattern);
+    pattern = new RegExp(
+      `(?<![\\da-fA-F])(?:${alternatives})(?![\\da-fA-F])|(?<![\\w+/-])(?:${base64Forms.join('|')})(?:={0,2}(?![\\w+/=-]))`,
+      'g'
+    );
+    if (encodedForms.size > 1024) {
+      encodedForms.clear();
+    }
+    encodedForms.set(value, pattern);
+  }
+  return pattern;
+}
+
 export function escapePattern(text) {
   return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -123,34 +149,42 @@ export function luhn(value) {
 function detectCookies(text, emit) {
   for (const match of text.matchAll(/(?:Set-)?Cookie[ \t]*:[ \t]*/gi)) {
     const range = valueRange(text, match.index + match[0].length, 'line');
-    if (
-      range &&
-      range.end > range.start &&
-      text.slice(range.start, range.end) !== REDACTED
-    ) {
-      emit({
-        ...range,
-        type: 'SECRET',
-        category: 'credential',
-        rule: 'cookie',
-      });
+    for (const value of range
+      ? cookieValues(text, range.start, range.end)
+      : []) {
+      if (!maskedValue(text.slice(value.start, value.end))) {
+        emit({
+          ...value,
+          type: 'SECRET',
+          category: 'credential',
+          rule: 'cookie',
+        });
+      }
     }
   }
 }
 
 export function nativeDetect(text, options, emit) {
-  const output = emit;
-  emit = (finding) => {
+  const found = [];
+  detectNative(text, options, (finding) => found.push(finding));
+  for (const finding of refineCredentialSpans(text, found)) {
     if (builtInEnabled(finding, options)) {
-      output(finding);
+      emit(finding);
     }
-  };
+  }
+}
+
+function detectNative(text, options, emit) {
   const credential = { type: 'SECRET', category: 'credential' };
   for (const value of options.knownSecrets ?? []) {
     collectMatches(text, new RegExp(escapePattern(value), 'g'), emit, {
       ...credential,
       rule: 'known-secret',
     });
+    collectMatches(text, knownEncodedForms(value), emit, {
+      ...credential,
+      rule: 'known-secret',
+    });
   }
   detectKnownPersonal(
     text,
@@ -176,18 +210,18 @@ export function nativeDetect(text, options, emit) {
       ? (details) => options.debug({ event: 'gitleaks-rule', ...details })
       : undefined
   );
+  const checked = (finding) =>
+    emit(
+      tokenChecksum(text.slice(finding.start, finding.end))
+        ? { ...finding, confidence: 0.99 }
+        : finding
+    );
   for (const [rule, pattern] of serviceRules) {
-    collectMatches(text, pattern, emit, { ...credential, rule });
+    collectMatches(text, pattern, checked, { ...credential, rule });
   }
   detectContext(text, emit, options.credentialsOnly);
   if (!options.credentialsOnly) {
-    detectPersonal(text, emit);
-    detectProseAndDocuments(text, emit, options, detectDocumentEntities);
-    detectCatalog(text, emit);
-    detectIdentity(text, emit);
-    detectNational(text, emit);
-    detectPersonalContext(text, emit);
-    detectStrict(text, emit, options);
+    feature('detectPersonalData')(text, emit, options);
   }
   detectCredentialFormats(text, emit);
   // detect-secrets-style quoted entropy detection; bare commit hashes and
@@ -248,9 +282,11 @@ function detectAuthorization(text, emit, credential) {
   for (const match of text.matchAll(
     /(?:Proxy-)?Authorization[ \t]*:[ \t]*/gi
   )) {
-    const range = authorizationRange(text, match.index + match[0].length);
-    if (range && !credentialPlaceholder(text.slice(range.start, range.end))) {
-      emit({ ...range, ...credential, rule: 'authorization' });
+    const start = match.index + match[0].length;
+    for (const range of authorizationRanges(text, start)) {
+      if (!credentialPlaceholder(text.slice(range.start, range.end))) {
+        emit({ ...range, ...credential, rule: 'authorization' });
+      }
     }
   }
 }
@@ -277,7 +313,16 @@ function detectPersonalFormats(text, options, emit) {
   collectMatches(
     text,
     /(?<![\p{L}\p{N}_.!#$%&'*+/?^`{|}~-])[\p{L}\p{N}_.!#$%&'*+/?^`{|}~-]+@[\p{L}\p{N}](?:[\p{L}\p{N}.-]{0,252})\.[\p{L}]{2,63}(?![\p{L}\p{N}_-])/gu,
-    (finding) => emit(emailAfterMention(text, finding)),
+    (finding) => {
+      // `https://user:password@host` is URL user info, not an address.
+      if (
+        !/[a-z][a-z0-9+.-]*:\/\/[^\s/@]*:$/i.test(
+          text.slice(Math.max(0, finding.start - 256), finding.start)
+        )
+      ) {
+        emit(emailAfterMention(text, finding));
+      }
+    },
     { type: 'EMAIL', category: 'personal', rule: 'email' }
   );
   collectMatches(
@@ -311,20 +356,21 @@ function detectPersonalFormats(text, options, emit) {
     0,
     (value, match) =>
       luhn(value) &&
-      cardNetwork(value) &&
+      (cardNetwork(value) ||
+        (uatpCard(value) && cardContext(text, match.index, value))) &&
       cardEvidence(text, match.index, value)
   );
   collectMatches(
     text,
-    /\b\d{3}-\d{2}-\d{4}\b/g,
+    /(?<![\w.-])\d{3}([-.])\d{2}\1\d{4}(?![\w-]|\.\d)/g,
     emit,
     { type: 'ID', category: 'personal', rule: 'us-ssn' },
     0,
-    (v) => !/^(?:000|666|9\d\d)-|^\d{3}-00-|0000$/.test(v)
+    (v) => !/^(?:000|666|9\d\d)\D|^\d{3}\D00\D|0000$/.test(v)
   );
   collectMatches(
     text,
-    /(?<![\w.])(?:\d{1,3}\.){3}\d{1,3}(?![\w.])/g,
+    /(?<![\w.])(?:\d{1,3}\.){3}\d{1,3}(?!\w|\.\d)/g,
     emit,
     { type: 'IP_ADDRESS', category: 'personal', rule: 'ipv4' },
     0,

package/src/document-person-cues.js

@@ -8,7 +8,7 @@ const name = "[A-Z][a-z]{1,47}(?:['’-][A-Z]?[a-z]{1,47})?";
 // unit in logs and lowercase `dr` is usually a word or path fragment. A
 // capitalized `Ms` right after a number is still a unit (`took 30 Ms Retry`).
 const cue =
-  '(?:[Cc]andidate|[Rr]ecruiter|[Aa]pplicant|[Dd]ear|[Hh]i|Mr\\.?|(?<!\\d[ \\t]*)Ms\\.?|Dr\\.?|[Mm]essage[ \\t]+from)';
+  '(?:[Cc]andidate|[Rr]ecruiter|[Aa]pplicant|[Dd]ear|[Hh]i|Mr\\.?|Ms(?<!\\d[ \\t]*Ms)\\.?|Dr\\.?|[Mm]essage[ \\t]+from)';
 const pattern = new RegExp(
   `(?<!${boundary})${cue}[ \\t]+(${name})(?!${boundary})`,
   'gu'

package/src/encoded.js

@@ -1,68 +1,101 @@
 import { TextDecoder } from 'node:util';
 import { Buffer } from 'node:buffer';
-import { failure } from './detection.js';
 import { jsonStringRuns } from './json-string-runs.js';
 
+// Decoded candidates are re-scanned by every detector, so their number is
+// bounded per window of the input; a denser window falls back to masking the
+// remaining candidates as `encoded-limit` runs, without blocking the text.
+const WINDOW = 65536;
+const WINDOW_CANDIDATES = 4096;
+
+const WRAPPED =
+  /(?<![A-Za-z0-9_+/-])[A-Za-z0-9_+/-]{16,128}(?:\r?\n[A-Za-z0-9_+/-]{1,128})+={0,2}(?![A-Za-z0-9_+/-])/g;
+
 export function* decodedRuns(text, depth = 0) {
   if (depth >= 2) {
     return;
   }
+  // Wrapped runs come first: a line inside a decoded wrapped run is covered
+  // by the run's own finding and is not decoded again.
   const patterns = [
+    WRAPPED,
     /(?<![A-Za-z0-9_+/-])[A-Za-z0-9_+/-]{16}[A-Za-z0-9_+/-]*={0,2}(?![A-Za-z0-9_+/-])/g,
     /(?:[^\s"'<>?=&:/]{0,128}%[\da-fA-F]{2})+(?:[^\s"'<>?=&:/]{0,128})/g,
-    /(?<![A-Za-z0-9_+/-])[A-Za-z0-9_+/-]{16,128}(?:\r?\n[A-Za-z0-9_+/-]{1,128})+={0,2}(?![A-Za-z0-9_+/-])/g,
     /(?:&#(?:x[\da-fA-F]{1,6}|\d{1,7});|&(?:amp|lt|gt|quot|apos|nbsp);){2,2048}/g,
     /(?:\\x[\da-fA-F]{2}){2,2048}/g,
     undefined, // JSON candidates use a linear scanner below.
   ];
-  const seen = new Set();
-  let count = 0;
+  const scan = { depth, seen: new Set(), counts: new Map(), covered: [] };
   for (const [index, pattern] of patterns.entries()) {
-    const marker = ['', '%', '\n', '&', '\\x', '"'][index];
+    const marker = ['\n', '', '%', '&', '\\x', '"'][index];
     if (marker && !text.includes(marker)) {
       continue;
     }
+    const inWrappedRun = coverage(scan.covered);
     for (const match of candidateMatches(text, pattern)) {
-      const raw = match[0];
-      if (raw.length > 8192) {
-        if (isLimitedTextRun(raw)) {
-          yield {
-            start: match.index,
-            end: match.index + raw.length,
-            limited: true,
-            depth,
-          };
-        }
-        continue;
-      }
-      const candidates = decodeCandidates(raw);
-      for (const candidate of candidates) {
-        const { text: decoded, encoding } = candidate;
-        const key = `${match.index}:${raw.length}:${decoded}`;
-        if (seen.has(key) || !decodedText(raw, decoded)) {
-          continue;
-        }
-        seen.add(key);
-        if (++count > 4096) {
-          throw failure('ERR_LIMIT');
-        }
-        const inset = encoding === 'json-content' ? 1 : 0;
-        const run = {
-          start: match.index + inset,
-          end: match.index + raw.length - inset,
-          text: decoded,
-          encoding,
-          depth,
-        };
-        yield run;
-        for (const inner of decodedRuns(decoded, depth + 1)) {
-          yield { ...run, text: inner.text, depth: inner.depth };
-        }
+      if (index !== 1 || !inWrappedRun(match.index)) {
+        yield* matchRuns(match, index === 0, scan);
       }
     }
   }
 }
 
+// Tests ascending offsets against the sorted, disjoint wrapped runs.
+function coverage(covered) {
+  let cursor = 0;
+  return (start) => {
+    while (cursor < covered.length && covered[cursor].end <= start) {
+      cursor++;
+    }
+    return cursor < covered.length && covered[cursor].start <= start;
+  };
+}
+
+function* matchRuns(match, wrapped, scan) {
+  const raw = match[0];
+  const start = match.index;
+  const end = start + raw.length;
+  const limited = { start, end, limited: true, depth: scan.depth };
+  if (raw.length > 8192) {
+    if (isLimitedTextRun(raw, wrapped)) {
+      scan.covered.push(limited);
+      yield limited;
+    }
+    return;
+  }
+  const window = Math.floor(start / WINDOW);
+  for (const candidate of decodeCandidates(raw)) {
+    const { text: decoded, encoding } = candidate;
+    const key = `${start}:${raw.length}:${decoded}`;
+    if (scan.seen.has(key) || !decodedText(raw, decoded)) {
+      continue;
+    }
+    scan.seen.add(key);
+    const count = (scan.counts.get(window) ?? 0) + 1;
+    scan.counts.set(window, count);
+    if (count > WINDOW_CANDIDATES) {
+      yield limited;
+      return;
+    }
+    if (wrapped && scan.covered.at(-1)?.start !== start) {
+      scan.covered.push({ start, end });
+    }
+    const inset = encoding === 'json-content' ? 1 : 0;
+    const run = {
+      start: start + inset,
+      end: end - inset,
+      text: decoded,
+      encoding,
+      depth: scan.depth,
+      ...(candidate.layout && { layout: candidate.layout }),
+    };
+    yield run;
+    for (const inner of decodedRuns(decoded, scan.depth + 1)) {
+      yield { ...run, text: inner.text, depth: inner.depth };
+    }
+  }
+}
+
 function candidateMatches(text, pattern) {
   return pattern ? text.matchAll(pattern) : jsonStringRuns(text);
 }
@@ -76,20 +109,59 @@ function decodedText(raw, decoded) {
   );
 }
 
-function isLimitedTextRun(raw) {
+function isLimitedTextRun(raw, wrapped) {
   // Bare opaque identifiers may share the base64 alphabet. Require a
-  // textual decode, or an explicit percent/wrapped encoding boundary.
-  const probe = decodeCandidates(raw.slice(0, 4096), true);
+  // textual decode, an explicit percent encoding, or the uniform layout of
+  // wrapped base64 (`base64 -w`, PEM bodies). Lists of identifiers or commit
+  // hashes are ordinary lines and are scanned one by one.
+  if (raw.includes('%')) {
+    return true;
+  }
+  const head = wrapped
+    ? raw.slice(0, 8192).replace(/\s/g, '').slice(0, 4096)
+    : raw.slice(0, 4096);
+  const probe = decodeCandidates(head, true);
   return (
-    raw.includes('%') ||
-    raw.includes('\n') ||
     probe.some(
       // eslint-disable-next-line no-control-regex -- Exclude binary controls from the bounded UTF-8 text probe.
       (c) => c.text && !/[\x00-\x08\x0e-\x1f\x7f]/.test(c.text)
+    ) ||
+    (wrapped && isWrappedBinary(raw))
+  );
+}
+
+// Wrapped binary base64 uses the standard alphabet, lines of one width that
+// is a multiple of four and is not plain hexadecimal.
+function isWrappedBinary(raw) {
+  // Trim the padding without a regular expression: `/=+$/` backtracks
+  // quadratically over long `=` runs that are not at the end.
+  let end = raw.length;
+  while (end > 0 && raw.charCodeAt(end - 1) === 61) {
+    end -= 1;
+  }
+  const lines = raw.slice(0, end).split(/\r?\n/);
+  const width = lines[0].length;
+  return (
+    width % 4 === 0 &&
+    !/[-_]/.test(raw) &&
+    !/^[\da-fA-F\s]+$/.test(raw) &&
+    lines.every((line, i) =>
+      i === lines.length - 1 ? line.length <= width : line.length === width
     )
   );
 }
 
+// Line width and separator of a wrapped run, re-applied when re-encoding.
+function wrapLayout(raw) {
+  if (!raw.includes('\n')) {
+    return undefined;
+  }
+  return {
+    width: raw.split(/\r?\n/, 1)[0].length,
+    newline: raw.includes('\r\n') ? '\r\n' : '\n',
+  };
+}
+
 function decodeCandidates(raw, partial) {
   const candidates = [];
   if (raw.startsWith('"')) {
@@ -153,8 +225,7 @@ function decodeCandidates(raw, partial) {
           text: new TextDecoder('utf-8', { fatal: true }).decode(bytes, {
             stream: partial,
           }),
-          wrapped: raw.includes('\n'),
-          padded: raw.endsWith('='),
+          layout: wrapLayout(raw),
         });
       } catch {
         /* Binary content. */
@@ -167,6 +238,7 @@ function decodeCandidates(raw, partial) {
           text: new TextDecoder('utf-8', { fatal: true }).decode(
             Buffer.from(compact, 'hex')
           ),
+          layout: wrapLayout(raw),
         });
       } catch {
         /* Binary content. */
@@ -198,16 +270,30 @@ export function encodeRun(run, text) {
         : `&#${c.codePointAt(0)};`
     ).join('');
   } else {
-    encoded = bytes.toString(run.encoding);
+    encoded = wrap(bytes.toString(run.encoding), run.layout);
   }
   const decoded =
     run.encoding === 'json-content'
       ? { text: JSON.parse(`"${encoded}"`) }
       : decodeCandidates(encoded).find((c) => c.encoding === run.encoding);
-  if (!decoded || decoded.text !== text) {
-    throw failure('ERR_ENCODING');
+  // A short payload may re-encode below the length a decoder recognizes
+  // (hex needs 32 digits); callers then mask the encoded text as it stands.
+  return decoded?.text === text ? encoded : undefined;
+}
+
+function wrap(encoded, layout) {
+  if (!layout?.width || encoded.length <= layout.width) {
+    return encoded;
+  }
+  const lines = [];
+  for (let i = 0; i < encoded.length; i += layout.width) {
+    lines.push(encoded.slice(i, i + layout.width));
+  }
+  // Padding never starts a line of its own.
+  if (/^=+$/.test(lines.at(-1)) && lines.length > 1) {
+    lines[lines.length - 2] += lines.pop();
   }
-  return encoded;
+  return lines.join(layout.newline);
 }
 
 export function encodedValue(raw) {