@link-foundation/sensitive-data-sanitizer 0.12.2 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.14.0
+
+### Minor Changes
+
+- d5b2aac: Add known-only reversible sanitization, Unicode known-value boundaries and bounded Russian entity case matching. Correct placeholder namespace collisions, Russian document entities and fake-name roles, and credential prose false positives. Report irreversible replacements in placeholder results.
+
+## 0.13.0
+
+### Minor Changes
+
+- 818f198: Add reversible typed placeholders with private JSON and Links Notation maps, map reuse and restoration, a no-map anonymization mode, and opt-in multilingual document entity detection for employers, schools, cities and regions.
+
 ## 0.12.2
 
 ### Patch Changes

package/README.md

@@ -22,6 +22,50 @@ sensitive-data-sanitizer redact session.jsonl --stream --jsonl --two-pass --outp
 
 ## Quick Start
 
+### Readable placeholders and document profiles
+
+Use the opt-in `documents` profile for CVs and similar prose. It adds bounded
+employer, school, city and region detection across the existing 17 locales.
+Default and publication log profiles keep their existing detection behavior.
+
+```js
+import { sanitize, restore } from '@link-foundation/sensitive-data-sanitizer';
+
+const result = sanitize('Jane Doe worked at Acme Ltd in Springfield.', {
+  profile: 'documents',
+  transformation: { mode: 'placeholder' },
+});
+// result.text: Person-1 worked at Organization-1 in Location-1.
+// Keep result.map private. Share only result.text.
+restore(result.text, result.map); // exact original document
+restore('Ask Person-1 about Organization-1.', result.map); // derived answer
+```
+
+The restore map **is personal data**. It contains original spellings and private
+occurrence metadata; never commit it, send it to a model, or publish the whole
+result object. The CLI writes maps separately with mode `0600`, and publication
+checks reject serialized restore maps. Reuse `result.map` in the next
+`transformation.map` to keep IDs stable across files. JSON and Links Notation
+serializations carry the same versioned map. Credentials stay fully redacted
+and out of the map unless explicitly opted in.
+
+```sh
+sensitive-data-sanitizer redact cv.txt --profile documents --placeholder --map private.lino --output safe.txt
+sensitive-data-sanitizer restore safe.txt --map private.lino --output restored.txt
+sensitive-data-sanitizer redact cv.txt --profile documents --placeholder --no-map
+```
+
+`knownOnly: true` (CLI `--known-only`) limits replacement to `knownPersonal`,
+`knownSecrets` and reused map identities, preserving fictional examples.
+Placeholder results report `irreversibleRedactions`; a nonzero count means some
+replacements, such as credentials excluded from the map, cannot be restored.
+
+For irreversible output, choose `transformation: { mode: 'placeholder', map:
+false }`: no restore map is returned or written. Detection limits still apply
+in either mode. See the [placeholder API](docs/API.md#reversible-placeholders),
+[coverage](docs/COVERAGE.md#document-entities), and
+[runnable example](examples/reversible-placeholders.mjs).
+
 Sanitizer APIs require Node.js 22.13 or later. Template arithmetic utilities are available under `@link-foundation/sensitive-data-sanitizer/legacy`; the existing universal example uses that browser-compatible entry. From this checkout:
 
 ```sh

package/bin/placeholders.js

@@ -0,0 +1,115 @@
+import { resolve } from 'node:path';
+import { failure } from '../src/detection.js';
+import {
+  createRestoreMap,
+  readRestoreMap,
+  writeRestoreMap,
+  restore,
+} from '../src/restore-map.js';
+import { readTextFile, atomicWrite } from '../src/files.js';
+
+export async function placeholderOptions(config, options) {
+  if (config.command === 'restore') {
+    return;
+  }
+  if (config.placeholder) {
+    options.transformation = { mode: 'placeholder' };
+  }
+  const transform = options.transformation;
+  validatePlaceholderFlags(config, transform);
+  if (transform?.mode !== 'placeholder') {
+    return;
+  }
+  validateMapArgs(config);
+  if (config.placeholderFormat) {
+    transform.format = config.placeholderFormat;
+  }
+  if (config.mapCredentials) {
+    transform.credentials = true;
+  }
+  if (config.noMap) {
+    transform.map = false;
+  }
+  if (config.map) {
+    try {
+      const { lstat } = await import('node:fs/promises');
+      await lstat(config.map);
+      transform.map = await readRestoreMap(config.map);
+      config.replaceMap = true;
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+      transform.map = createRestoreMap({ format: transform.format });
+    }
+  } else if (transform.map !== false) {
+    // The CLI cannot return a private map alongside stdout safely.
+    throw failure('ERR_ARGUMENT');
+  }
+  config.restoreMap = transform.map;
+}
+function validatePlaceholderFlags(config, transform) {
+  if (
+    (config.map ||
+      config.noMap ||
+      config.placeholderFormat ||
+      config.mapCredentials ||
+      config.mapFormat) &&
+    transform?.mode !== 'placeholder'
+  ) {
+    throw failure('ERR_ARGUMENT');
+  }
+}
+function validateMapArgs(config) {
+  if (config.map && config.noMap) {
+    throw failure('ERR_ARGUMENT');
+  }
+  if (config.mapFormat && !['json', 'lino'].includes(config.mapFormat)) {
+    throw failure('ERR_ARGUMENT');
+  }
+  if (
+    config.map &&
+    [config.path, config.output, config.config]
+      .filter(Boolean)
+      .some((path) => resolve(path) === resolve(config.map))
+  ) {
+    throw failure('ERR_OUTPUT');
+  }
+}
+
+export async function saveMap(config) {
+  if (config.map) {
+    await writeRestoreMap(config.map, config.restoreMap, {
+      replace: Boolean(config.replaceMap),
+      ...(config.mapFormat ? { format: config.mapFormat } : {}),
+    });
+  }
+}
+export async function restoreCommand(config, { stdout }) {
+  if (
+    !config.map ||
+    config.path === '-' ||
+    config.stream ||
+    config.noMap ||
+    config.placeholder ||
+    config.mapCredentials ||
+    config.json ||
+    config.jsonl ||
+    config.inPlace
+  ) {
+    throw failure('ERR_ARGUMENT');
+  }
+  if (config.output && resolve(config.output) === resolve(config.map)) {
+    throw failure('ERR_OUTPUT');
+  }
+  const text = restore(
+    await readTextFile(config.path, config.maxBytes),
+    await readRestoreMap(config.map)
+  );
+  if (config.output) {
+    await atomicWrite(config.output, text);
+  } else {
+    stdout.write(text);
+  }
+  return 0;
+}

package/bin/sensitive-data-sanitizer.js

@@ -21,16 +21,18 @@ import { encodeLogText } from '../src/log-bytes.js';
 import { createWikidataVerifier } from '../src/public-verifier.js';
 import { streamCommand } from './stream.js';
 import { sessionStructuralFields } from '../src/structured.js';
+import { placeholderOptions, saveMap, restoreCommand } from './placeholders.js';
 import {
   createGitleaksDetector,
   createTrufflehogDetector,
   createPresidioDetector,
 } from '../src/external.js';
 
-const help = `Usage: sensitive-data-sanitizer <redact|scan|history> [path|-] [options]
+const help = `Usage: sensitive-data-sanitizer <redact|scan|restore|history> [path|-] [options]
 
 redact    Sanitize one text log or stdin; publish only after verification
 scan      Report metadata for a file, directory, or stdin (never source text)
+restore   Restore placeholders in a file using --map PATH (private output)
 history   Audit local reachable Git blobs, commit/tag metadata, and reflogs
 history rewrite SOURCE --output DIRECTORY [--apply]
           Preview a fresh mirror clone; --apply rewrites only that clone
@@ -40,6 +42,7 @@ history rewrite SOURCE --output DIRECTORY [--apply]
 --in-place          Atomically replace the input file (redact only)
 --native-only       Disable Secretlint; selected local detectors remain required
 --credentials-only  Preserve personal/account details; redact credentials only
+--known-only        Replace only knownPersonal/knownSecrets and reused map values
 --env-secrets       Include values of all credential-named environment variables
 --gh-config         Include tokens from the local gh hosts.yml credential file
 --paranoid          Add entropy detection (can redact innocent identifiers)
@@ -56,7 +59,13 @@ history rewrite SOURCE --output DIRECTORY [--apply]
 --json              Sanitize JSON strings and keys; preserve session metadata
 --jsonl             Sanitize JSONL records; combine with --stream for sessions
 --identity-mask     First/last 2 identity mask (publication profile default)
---profile NAME      Publication profile (redact default; config can override)
+--profile NAME      publication (redact default) or documents (CV/entity rules)
+--placeholder       Typed numbered placeholders; requires --map or --no-map
+--map PATH          Private JSON/.lino restore map; reuse it across files/runs
+--no-map            Discard placeholder mapping after full anonymization
+--placeholder-format TEMPLATE  Default {Type}-{n}; also [{TYPE}_{n}]
+--map-format FORMAT json or lino (otherwise inferred from .lino extension)
+--map-credentials   Explicitly keep credentials in the private restore map
 --max-record-bytes N Maximum record bytes (text: total limit; JSONL: 8388608)
 --hive-mask         Opt-in first/last 3 mask for values longer than 12 characters
 --preserve-encoding Re-encode sanitized encoded payloads with round-trip checks
@@ -80,6 +89,7 @@ function parseArgs(argv) {
     ['--in-place', 'inPlace'],
     ['--native-only', 'nativeOnly'],
     ['--credentials-only', 'credentialsOnly'],
+    ['--known-only', 'knownOnly'],
     ['--env-secrets', 'envSecrets'],
     ['--gh-config', 'ghConfig'],
     ['--paranoid', 'paranoid'],
@@ -96,6 +106,9 @@ function parseArgs(argv) {
     ['--gh-auth', 'ghAuth'],
     ['--verify-public', 'verifyPublic'],
     ['--apply', 'apply'],
+    ['--placeholder', 'placeholder'],
+    ['--no-map', 'noMap'],
+    ['--map-credentials', 'mapCredentials'],
   ]);
   const valued = new Map([
     ['--config', 'config'],
@@ -109,6 +122,9 @@ function parseArgs(argv) {
     ['--worker-timeout-ms', 'workerTimeoutMs'],
     ['--filter-repo', 'filterRepo'],
     ['--profile', 'profile'],
+    ['--map', 'map'],
+    ['--map-format', 'mapFormat'],
+    ['--placeholder-format', 'placeholderFormat'],
   ]);
   let hasPath = false;
   for (let i = rewrite ? 2 : 1; i < argv.length; i++) {
@@ -134,7 +150,7 @@ function parseArgs(argv) {
 function validateArgs(config) {
   config.maxBytes = Number(config.maxBytes ?? defaultByteLimit(config));
   if (
-    !['redact', 'scan', 'history'].includes(config.command) ||
+    !['redact', 'scan', 'restore', 'history'].includes(config.command) ||
     !Number.isSafeInteger(config.maxBytes) ||
     config.maxBytes <= 0
   ) {
@@ -143,7 +159,7 @@ function validateArgs(config) {
   if (
     (config.output && config.inPlace) ||
     ((config.output || config.inPlace) &&
-      config.command !== 'redact' &&
+      !['redact', 'restore'].includes(config.command) &&
       !config.rewrite) ||
     (config.inPlace && config.path === '-') ||
     (config.command === 'history' && config.path === '-')
@@ -252,19 +268,8 @@ export async function runCli(
       return 0;
     }
     const config = parseArgs(argv);
-    const options = await loadOptions(config);
-    const engine = createSanitizer(options);
     const context = { stdin, stdout };
-    if (config.command === 'history') {
-      return await historyCommand(config, engine, context);
-    }
-    if (config.stream) {
-      return await streamCommand(config, engine, options, context);
-    }
-    if (config.command === 'redact') {
-      return await redactCommand(config, engine, context);
-    }
-    return await scanCommand(config, engine, context);
+    return await dispatchCommand(config, context);
   } catch (error) {
     const location =
       Number.isSafeInteger(error.record) && Number.isSafeInteger(error.offset)
@@ -277,6 +282,27 @@ export async function runCli(
   }
 }
 
+async function dispatchCommand(config, context) {
+  if (config.command === 'restore') {
+    return await restoreCommand(config, context);
+  }
+  const options = await loadOptions(config);
+  const engine = createSanitizer(options);
+  if (config.command === 'history') {
+    return await historyCommand(config, engine, context);
+  }
+  if (config.stream) {
+    return await streamCommand(config, engine, options, {
+      ...context,
+      beforePublish: () => saveMap(config),
+    });
+  }
+  if (config.command === 'redact') {
+    return await redactCommand(config, engine, context);
+  }
+  return await scanCommand(config, engine, context);
+}
+
 async function loadOptions(config) {
   let options = {};
   if (config.config) {
@@ -300,6 +326,7 @@ async function loadOptions(config) {
     options.paranoid = true;
   }
   await featureOptions(config, options);
+  await placeholderOptions(config, options);
   options.detectors = selectedDetectors(config, options.detectors);
   options.maxInputLength = Math.min(
     options.maxInputLength ?? config.maxBytes,
@@ -314,6 +341,9 @@ async function loadOptions(config) {
 
 async function featureOptions(config, options) {
   await localCredentials(config, options);
+  if (config.knownOnly) {
+    options.knownOnly = true;
+  }
   if (config.credentialsOnly) {
     options.credentialsOnly = true;
   }
@@ -391,6 +421,7 @@ async function redactCommand(config, engine, { stdin, stdout }) {
   const result = await engine.sanitize(
     await inputText(config.path, config, stdin)
   );
+  await saveMap(config);
   if (config.output || config.inPlace) {
     await atomicWrite(
       config.output ?? config.path,

package/bin/stream.js

@@ -9,7 +9,7 @@ export async function streamCommand(
   config,
   engine,
   options,
-  { stdin, stdout }
+  { stdin, stdout, beforePublish }
 ) {
   let spool;
   try {
@@ -42,6 +42,7 @@ export async function streamCommand(
           : { sanitizer: engine, sanitizerOptions: options }),
       });
     }
+    await beforePublish?.();
     if (spool) {
       for await (const chunk of createReadStream(target)) {
         if (stdout.write(chunk) === false) {

package/docs/API.md

@@ -19,27 +19,136 @@ Import the ESM root entry; complete declarations are in `src/index.d.ts`. Inputs
 
 ## Options
 
-| Option             | Default / meaning                                                                             |
-| ------------------ | --------------------------------------------------------------------------------------------- |
-| `profile`          | Off; `'publication'` sets a 0.3 personal threshold, identity masking and strict fake policy   |
-| `knownSecrets`     | `[]`; exact literal credential values, regardless of length or format                         |
-| `knownPersonal`    | `[]`; `{type, value}` literals with Unicode case-insensitive matching                         |
-| `publicEntities`   | `[]`; exact PERSON/ORGANIZATION/EMAIL exception with HTTPS source and review date             |
-| `findings`         | `[]`; validated detections for the original input, supplied by the caller                     |
-| `detectors`        | `[]`; additional required callbacks in the asynchronous engine                                |
-| `secretlint`       | `true` in the asynchronous engine                                                             |
-| `decode`           | `true`; bounded base64/base64url, hex and percent decoding                                    |
-| `paranoid`         | `false`; entropy-based supplemental credential heuristic                                      |
-| `maxInputLength`   | 33,554,432 UTF-16 units                                                                       |
-| `maxFindings`      | 100,000 detector hits before deduplication                                                    |
-| `minConfidence`    | 0.5; personal findings below this score remain visible to inspect but are not replaced        |
-| `threshold`        | Alias for minConfidence; both options must agree when supplied                                |
-| `debug`            | Optional trusted callback for value-free counts, timing and event metadata                    |
-| `identityMask`     | `false`; identity types keep 2+2 Unicode characters with fixed `***`, or redact below five    |
-| `fakeIdentity`     | Off; `'specimen-and-synthetic'` retains explicitly fake identity values                       |
-| `fakeValues`       | `[]`; exact caller-reviewed identity values to retain, regardless of fakeIdentity             |
-| `structured`       | Off; `'json'` or `'jsonl'` validates and sanitizes string keys/values separately              |
-| `structuralFields` | `[]`; declared property names suppress weak name/ID/entropy heuristics in their string values |
+### Replace only known values
+
+Use `knownOnly: true` to preserve fictional examples while replacing selected
+private values. This applies to sync/async, JSON/JSONL, streams and fake mode.
+It skips automatic credential detection too; supply `knownSecrets` explicitly
+for credentials that must be removed. `credentialsOnly` can further exclude
+personal values. CLI: `--known-only` with a `--config` containing the known lists.
+
+```js
+const result = sanitize('Анна Смирнова; example Jane Doe', {
+  knownOnly: true,
+  knownPersonal: [{ type: 'PERSON', value: 'Анна Смирнова' }],
+  transformation: { mode: 'placeholder' },
+});
+// result.text: 'Person-1; example Jane Doe'
+restore(result.text, result.map); // exact original
+```
+
+### Reversible placeholders
+
+`transformation: {mode: 'placeholder'}` emits typed tokens such as `Person-1`,
+`Email-1`, `Phone-1`, `Organization-1`, `Education-1`, `Location-1` and `Date-1`.
+Numbers start at one per type and follow the first occurrence in the input.
+`DATE_OF_BIRTH` uses the `Date` label; other detector types retain their type
+name in title case. Per-type `transformations` also support placeholder mode;
+all placeholder transformations in an operation must share one map and format.
+
+The result has a private `map` alongside `text`, `findings` and `redactions`.
+The map holds token entries, every original surface form, name aliases, and
+replacement positions indexed by the SHA-256 digest of the sanitized document.
+It does not store the original full document. `restore(text, map)` restores
+the exact bytes represented by the original JavaScript string, including JSON
+escaping and whitespace, when the document digest matches. A derived response
+that quotes tokens uses the entry's canonical original spelling instead.
+Restoration uses a single pass so restored originals are never interpreted as
+more tokens. Unknown tokens and larger words containing token-like fragments
+are left alone.
+
+`format` is a template with exactly one type field (`{Type}`, `{TYPE}` or
+`{type}`) and one `{n}` field. Examples: `{Type}-{n}`, `[{TYPE}_{n}]`,
+`{{{type}_{n}}}`. Sanitization refuses input containing any token in the chosen
+namespace for built-in and supplied type labels, including numbers not allocated yet.
+Unicode letters, marks, digits and underscores bound those tokens. Ordinary
+technical names such as GPT-4, ISO-9001 and Windows-10 are not reserved. The map's format cannot change
+on reuse. A malformed map or ambiguous exact restoration blocks output.
+
+`createRestoreMap({format?})` creates an empty reusable map. Pass a map as
+`transformation.map` to continue a corpus; the operation updates that same
+object. A `createSanitizer()` engine also keeps its registry across calls.
+Callers must serialize access to a shared engine/map; parallel independent
+registries cannot assign consistent first-appearance numbers. For streams,
+pass an explicit map object and keep it outside the output stream. Placeholder
+JSONL uses the coordinator in source order, even if several workers were
+requested. File APIs also keep this registry in the caller process.
+
+`serializeRestoreMap(map, 'json' | 'lino')` and `parseRestoreMap(text)` round
+trip the same schema. Lino uses the upstream `links-notation` parser and
+formatter: a named `sensitive-data-restore-map` link carries the escaped JSON
+schema as a reference, preserving all metadata and unusual original strings.
+`readRestoreMap(path)` and `writeRestoreMap(path, map, {format?, replace?})`
+use bounded file reads and the existing atomic `0600` writer. The default
+serialization is JSON, or Lino for a `.lino` output path. Existing files require
+`replace: true`; symlinks are refused. `inspect`, `sanitize`, scanner union and
+CLI publication paths reject marked map content with `ERR_PRIVATE_MAP`.
+Keep maps out of Git, logs, model requests and publication directories. The map
+is plaintext personal data, not encrypted storage; protect it as the original.
+
+`credentials: true` explicitly opts credentials into `Credential-n` entries.
+Otherwise they remain `[REDACTED]` and cannot be recovered, including through
+occurrence metadata. Placeholder results include `irreversibleRedactions`, the
+number of replacements excluded from the restore map (including mixed policies).
+Check that this is zero before relying on exact restoration. A positive count
+means `restore()` cannot reconstruct all of the input. `map: false` returns only the anonymized text and ordinary
+value-free finding metadata. The temporary numbering registry is discarded
+after an operation (or the complete stream); no map file is created. Residual verification
+still runs, including every required engine for `createSanitizer`.
+
+Name components, unique initial-plus-surname forms, existing transliteration
+aliases and selected Russian `-ов`/`-ев` inflections share an entity token.
+Explicit `knownPersonal` and reused map entries also match bounded Russian noun,
+adjective, feminine surname and given-name case endings, two-part person names
+in reverse order, and organization cores without legal forms/quotes. Inflected
+forms consume whole Unicode words; minimum stem lengths limit overmatching.
+This is conservative heuristic identity linking, not general coreference:
+ambiguous surnames/initials and unrelated people are not intentionally merged.
+Every replaced occurrence retains its exact original surface privately. With
+one identical token, a derived answer cannot encode the original grammatical
+case; it receives the canonical spelling. Two distinct originals that produce
+the same entire sanitized document cannot both be distinguished by that text
+and a shared map; such conflicting occurrence metadata is refused. Choose
+separate maps for those documents if exact independent restoration is needed.
+
+JSON/JSONL keys and values participate equally in placeholder mode, including
+ordinary identifier keys and declared structural fields. Parseability and
+duplicate-key checks remain enforced. Plain redact/fake policies retain their
+existing metadata/key behavior. Use `structured` for valid structured input.
+The normal encoding limits and credential redaction policy continue to apply.
+
+CLI: `redact FILE --placeholder --map private.json` creates or continues a map;
+`--no-map` explicitly discards it. A CLI placeholder operation requires one of
+these choices, to avoid losing a map silently. `--placeholder-format`,
+`--map-format json|lino` and `--map-credentials` configure the transformation.
+`restore safe.txt --map private.lino [--output restored.txt]` also works on a
+derived model answer. Input, output and map paths must be separate. Maps are
+saved separately before stdout publication. `--profile documents` enables the
+new document recognizers; `documentEntities: false` turns them off explicitly.
+
+| Option             | Default / meaning                                                                                                                                           |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `documentEntities` | Off; bounded organization, education and location rules; enabled by the documents profile                                                                   |
+| `profile`          | Off; `'publication'` sets a 0.3 threshold and identity masking; `'documents'` enables document entities                                                     |
+| `knownOnly`        | `false`; disable all automatic detection (including credentials, Secretlint and custom detectors); use only explicit known values and reused map identities |
+| `knownSecrets`     | `[]`; exact literal credential values, regardless of length or format                                                                                       |
+| `knownPersonal`    | `[]`; `{type, value}` values with whole-word Unicode case-insensitive matching and bounded Russian case forms                                               |
+| `publicEntities`   | `[]`; exact PERSON/ORGANIZATION/EDUCATION/LOCATION/EMAIL exception with HTTPS evidence and review date                                                      |
+| `findings`         | `[]`; validated detections for the original input, supplied by the caller                                                                                   |
+| `detectors`        | `[]`; additional required callbacks in the asynchronous engine                                                                                              |
+| `secretlint`       | `true` in the asynchronous engine                                                                                                                           |
+| `decode`           | `true`; bounded base64/base64url, hex and percent decoding                                                                                                  |
+| `paranoid`         | `false`; entropy-based supplemental credential heuristic                                                                                                    |
+| `maxInputLength`   | 33,554,432 UTF-16 units                                                                                                                                     |
+| `maxFindings`      | 100,000 detector hits before deduplication                                                                                                                  |
+| `minConfidence`    | 0.5; personal findings below this score remain visible to inspect but are not replaced                                                                      |
+| `threshold`        | Alias for minConfidence; both options must agree when supplied                                                                                              |
+| `debug`            | Optional trusted callback for value-free counts, timing and event metadata                                                                                  |
+| `identityMask`     | `false`; identity types keep 2+2 Unicode characters with fixed `***`, or redact below five                                                                  |
+| `fakeIdentity`     | Off; `'specimen-and-synthetic'` retains explicitly fake identity values                                                                                     |
+| `fakeValues`       | `[]`; exact caller-reviewed identity values to retain, regardless of fakeIdentity                                                                           |
+| `structured`       | Off; `'json'` or `'jsonl'` validates and sanitizes string keys/values separately                                                                            |
+| `structuralFields` | `[]`; declared property names suppress weak name/ID/entropy heuristics in their string values                                                               |
 
 Unknown options and invalid limits are errors. `knownSecretsFromEnv(env, names?)` discovers credential-named variables (excluding auth configuration names) when names are omitted, or uses an explicit selection, deduplicating nonempty values. It never invokes shell commands or reads auth files. `personalVariants(entries)` generates numeric and ISO/day-first date spellings; name case variants are already handled by detection. Neither helper invents transliterations.
 

package/docs/COVERAGE.md

@@ -14,6 +14,56 @@ Broader unquoted entropy scanning is opt-in (`paranoid: true`), uses Shannon ent
 
 ## Personal data and languages
 
+### Document entities
+
+`profile: 'documents'` (or `documentEntities: true`) opts into the following
+additional rules. They are off under the existing default and publication
+profiles, preserving credential/log fixture behavior and avoiding extra company
+name redactions in stack traces. Existing contextual organization detection
+remains available under those profiles.
+
+| Type           | Coverage                                                                                                                              | Confidence |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `ORGANIZATION` | Proper names next to legal forms in either order, optionally quoted: Inc, LLC, Ltd, GmbH, AG, S.A., ООО, АО, ПАО, ИП and locale forms | 0.70       |
+| `EDUCATION`    | Proper names next to University, College, Institute, school and locale equivalents, in either order                                   | 0.65       |
+| `LOCATION`     | Exact city/region entries from a bounded offline vocabulary                                                                           | 0.60       |
+| `LOCATION`     | Bounded proper names after location labels, including based in, located in, relocated from, г., город and locale equivalents          | 0.75       |
+
+Russian document rules also accept legal-form quoted names with lowercase words,
+digits and hyphens (up to 160 characters), organization Group/Групп/Holding/Холдинг
+markers, adjectival institution names with lowercase connectors and optional
+`имени` tails, education acronyms in context, residence labels and city/country
+phrasing. A known given name after `Меня зовут` or `С уважением` scores 0.70.
+Detected organization cores propagate within a document and across confirmed
+stream records. Russian regional cities include Ярославль and Кострома; the
+vocabulary remains finite. Default profiles do not enable these document rules.
+
+These confidence values indicate heuristic strength, not calibrated
+probabilities. `minConfidence` still controls replacement. Findings retain
+their confidence even below threshold. `publicEntities` supports exact reviewed
+exceptions for all three types; `knownPersonal` always forces removal of a
+listed private value. All types support placeholder mode; fake mode uses stable,
+visibly synthetic organization/school/location labels.
+
+`src/document-vocabulary.js` is the complete authored vocabulary: English,
+Spanish, French, German, Portuguese, Russian, Japanese, Simplified/Traditional
+Chinese, Korean, Arabic, Hebrew, Hindi, Turkish, Indonesian, Vietnamese and
+Thai each have list-form employer, school and city fixtures. Proper-name
+rules are finite (up to six capitalized words, or four words in scripts without
+case); they do not implement grammatical parsing. Other lowercase connectors,
+unusual typography, unsupported legal forms and unfamiliar institutions can be
+missed. Legal-form words and uncased scripts can also yield false positives.
+
+The gazetteer has only the cities/regions explicitly listed in that module,
+including Springfield and Riverton. It is not a worldwide geocoder. Location
+labels can find unlisted proper names; unlabelled places outside the vocabulary
+need `knownPersonal` or an additional detector such as the Presidio bridge.
+Name linking is also heuristic, especially for shared surnames, transliterations
+and inflected forms. Employers, schools, locations, dates and other
+quasi-identifiers can re-identify a person when detection misses them. Neither
+placeholder mode nor no-map mode promises universal anonymity. A restore map
+contains personal data and must remain private; see [API.md](API.md#reversible-placeholders).
+
 Native rules cover international/Unicode emails, international and selected national-format phones, Luhn-valid payment cards, US SSNs, IPv4/IPv6, checksum-validated IBAN/CPF/Spanish DNI/US NPI, Indian PAN, UK NI, wallet shapes, MACs, messenger handles, home usernames, labelled PII and selected postal address grammars. A bundled 17-locale name gazetteer supplies default free-text detection, including selected inflections/transliterations. Each locale has credential prose and eight labelled PII fixtures. This finite dictionary/grammar is not unrestricted statistical NER; unfamiliar names and unsupported national formats require known values or additional recognizers.
 
 Credential labels have fixtures for 17 language variants:

package/examples/reversible-placeholders.mjs

@@ -0,0 +1,35 @@
+import {
+  sanitize,
+  restore,
+  createRestoreMap,
+  serializeRestoreMap,
+} from '../src/index.js';
+
+// Keep this map private. Publish only result.text, never the map or result.
+const map = createRestoreMap();
+const options = {
+  profile: 'documents',
+  transformation: { mode: 'placeholder', map },
+};
+const text = 'Jane Doe worked at Acme Ltd in Springfield.';
+const result = sanitize(text, options);
+console.log(result.text);
+console.log('Exact private round trip:', restore(result.text, map) === text);
+console.log(
+  'Derived answer restored privately:',
+  restore('Ask Person-1 about Organization-1.', map)
+);
+console.log(
+  'Private map serialization available:',
+  typeof serializeRestoreMap(map, 'lino') === 'string'
+);
+const anonymous = sanitize(text, {
+  ...options,
+  transformation: { mode: 'placeholder', map: false },
+});
+console.log(
+  'No-map output:',
+  anonymous.text,
+  'Map returned:',
+  Object.hasOwn(anonymous, 'map')
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-foundation/sensitive-data-sanitizer",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "description": "Offline sensitive-text sanitization with credential, multilingual personal-data and scanner union detection",
   "type": "module",
   "main": "src/index.js",
@@ -23,7 +23,8 @@
     "CHANGELOG.md",
     "LICENSE",
     "README.md",
-    "examples/shared-tool-logs.mjs"
+    "examples/shared-tool-logs.mjs",
+    "examples/reversible-placeholders.mjs"
   ],
   "exports": {
     ".": {
@@ -119,6 +120,7 @@
     "@secretlint/profiler": "13.0.7",
     "@secretlint/secretlint-rule-preset-recommend": "13.0.7",
     "libphonenumber-js": "1.13.14",
+    "links-notation": "0.30.0",
     "re2-wasm": "1.0.2",
     "re2js": "^2.9.0",
     "yaml": "^2.9.1"