@link-foundation/sensitive-data-sanitizer 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.17.0
+
+### Minor Changes
+
+- Add synchronous sensitiveFields schema redaction and consistent document field aliases. Protect percent-encoded URL contacts, personal paths, opaque share links, CV employers and contextual company names; preserve multiline empty attributes and redact escaped fragments without losing structured records.
+
+  Install and verify a checksum-pinned GitHub CLI in the preview screenshot container, and exercise the same publishing tools on pull requests before generated images reach main.
+
+  Check maintained Python helpers with Ruff and CodeQL, and audit every tracked Python requirements file, including transitive benchmark dependencies, without installing NLP packages.
+
+## 0.16.2
+
+### Patch Changes
+
+- Make CI security and validation gates fail on incomplete evidence, recover transient release push failures, preserve validated release dependencies, and prevent quadratic scanning of PuTTY headers, travel identifiers and postal-address whitespace.
+
+  Preserve durations, stack frames, empty document fields and local bind addresses; protect personal URL paths and additional document forms. Reduce repeated label-pattern construction and document structured JSON per-call costs.
+
 ## 0.16.1
 
 ### Patch Changes

package/docs/API.md

@@ -176,6 +176,7 @@ new document recognizers; `documentEntities: false` turns them off explicitly.
 | `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                                                                            |
+| `sensitiveFields`  | `[]`; exact JSON/JSONL property names whose complete values become a redaction string; supports synchronous calls                                           |
 | `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.
@@ -474,3 +475,33 @@ restores IP detection; explicit `knownSecrets` and `knownPersonal` retain
 priority. No shell command or workflow expression is executed.
 
 Authorization headers (including Proxy-Authorization) redact the scheme and one credential token. Whitespace, C0 controls (including NUL), DEL, quotes, backslashes and commas end the value, preserving subsequent log text in shell and escaped JSON prompts. Matching brackets opened within a token are included in its redaction; unmatched closing brackets remain part of the surrounding log. Already-redacted tokens and known credential references remain exempt after an optional scheme, including `<token>` placeholders. The debug callback receives value-free `gitleaks-rule` events with rule ID, input length and elapsed milliseconds; tracing is off by default.
+
+## Caller-declared sensitive fields
+
+In structured JSON/JSONL, `sensitiveFields: string[]` matches exact,
+case-sensitive property names at any depth. The complete property value becomes
+`"[REDACTED]"`, including empty strings, numbers, booleans, null, arrays and
+objects. This deliberate schema policy can change value types. It takes
+priority over `structuralFields` and transformations, preserves property names
+and surrounding whitespace, and works in both `sanitize` and `createSanitizer`.
+It has no effect without `structured`. The personal-data switch
+`credentialsOnly` still suppresses personal findings.
+
+```js
+sanitize('{"privateNote":"arbitrary free text","count":2}', {
+  structured: 'json',
+  sensitiveFields: ['privateNote'],
+}).text;
+// {"privateNote":"[REDACTED]","count":2}
+
+sanitize('Lyutik работал', {
+  profile: 'documents',
+  knownPersonal: [{ type: 'ORGANIZATION', value: 'Lyutik' }],
+}).text;
+// [REDACTED] работал
+```
+
+`knownPersonal` is the synchronous custom-value list, including names without
+context. For computed synchronous detection, callers can supply validated
+`findings` for the exact input. `detectors` remains an asynchronous-engine
+option; `sanitize` does not invoke these callbacks.

package/docs/COVERAGE.md

@@ -236,7 +236,8 @@ The `documents` profile additionally recognizes:
   forms and lower case, and surnames after г-жа/господин/госпожа.
 - Birth years with д.р./г.р./год рождения/родился/родилась/Born in context;
   Russian age expressions and Пол labels, English Sex, and gender beside age.
-  Age-in-years expressions can also describe nonpersonal durations.
+  Bare age-in-years expressions are ambiguous and remain unchanged without
+  affirmative personal-age context; durations are preserved.
 - Labelled citizenship, marital status, children, nationality, religion,
   disability and criminal record, including the reported English labels.
 - Company/employer/workplace labels, capitalized company/holding/bank names,
@@ -258,7 +259,7 @@ recognizer when these fields must be removed. Initial/name rules do not cover
 all surnames, languages, cases or arbitrary lower-case names.
 
 Operational value policy (#79): a single-slash relative URL with no query,
-fragment, userinfo or explicit user/profile/member/home path stays unchanged
+fragment, userinfo or explicit u/in/user/profile/member/home/people path stays unchanged
 under `url`; other detectors and known values still apply. An ISO-style
 `YYYY-MM-DDTHH:mm:ss[.fraction](Z|±HH:mm)` timestamp under `time` stays unchanged.
 This exemption is syntactic, not date validation. Userinfo, token-bearing URLs
@@ -270,3 +271,134 @@ provider-specific rules and required external scanners remain authoritative.
 
 The [complete requirement inventory and alternatives](case-studies/issue-84/README.md)
 links every reported text row to its regression case.
+
+## Document context refinements (issues 87–88)
+
+Age requires a label (`возраст 41`, `Age 41`), personal pronoun (`мне 29 лет`),
+birthday verb (`исполнилось 34`) or gender followed by age (`Женщина, 34 года`).
+Bare `34 года` remains unchanged as an ambiguous limit. Work experience, tenure,
+contract lengths and elapsed/future durations stay unchanged. `Дети: нет` and
+`Гражданство: не указано` are treated as empty fields; negative disability and
+criminal-record statements remain sensitive attributes.
+
+Additional document forms include `контактный телефон` and `сот.` phone labels,
+parenthesized `(собака)` email separators, `телега`/`Zoom` messenger labels,
+dated `ТП УФМС`/`УФМС` passport issuers, `р/с` account numbers, `г-н` surname
+titles, `1985 года рождения` and `г.р. 1985`, abbreviated/single-letter gender
+values (`Пол: Ж`, `Пол: М`, `пол: жен.`, `пол муж.`), `гражданин РФ`,
+`есть двое детей`, `проживаю в Перми`, and English `Employer`, `Company` and
+`Education` labels. A capitalized Cyrillic word followed by two initials is
+recognized regardless of surname ending (`Цой В. Р.`, `Ким Д. С.`,
+`Шевченко Т. Г.`). This structural rule can flag non-name text with the same
+shape; it does not provide a complete surname dictionary.
+
+JSON escape boundaries cannot start an obfuscated-email local part, preserving
+stack newlines and frames after IP:port. Relative `/u/<name>` and `/in/<name>`
+URLs are personal paths under `url`, like the existing user/profile paths.
+Exact `0.0.0.0` is an operational unspecified bind address, like loopback/local
+addresses. `publicKnowledge: false` and explicit private known values still
+redact it.
+
+## Structured JSON cost (issue 86)
+
+Structured sanitization scans labelled raw strings and each decoded string with
+its own line boundaries, then verifies sanitized output. This preserves detection
+in arrays, CV fragments and embedded JSON, but adds fixed work per string/key.
+Costs depend on string count, enabled engines, content, runtime and hardware;
+line length alone cannot predict synchronous main-thread delay.
+
+A finite serial measurement on Linux x64, Node 26.13.0, using the documents
+profile and structured JSON, produced these median milliseconds per `sanitize`
+call (100 warm-ups, three 100-call trials):
+
+| Fixture                                   | 0.16.0 | 0.16.1 | This change |
+| ----------------------------------------- | -----: | -----: | ----------: |
+| Short JSON (89 characters)                |   1.21 |   8.44 |        4.67 |
+| Exact issue reproduction (264 characters) |   1.81 |  19.71 |       11.15 |
+| Longer synthetic JSON (9,396 characters)  |  10.04 |  37.88 |       28.32 |
+
+The short and longer synthetic rows approximate the issue's unpublished
+100/9,453-character inputs; only the 264-character input was provided in full.
+These results are evidence for this container, not a universal latency guarantee
+or an Apple Silicon comparison. The issue reporter measured 0.16.1 at
+2.31/5.61/34.85 ms on their short/264-character/9 KiB rows and 1.10 ms for the
+264-character text-mode control. The remaining structured overhead is **above
+2x** of 0.16.0 here; documenting that cost fulfills the issue's alternative
+acceptance criterion. No detection view is removed to meet a timing target.
+
+Personal-label patterns are now constructed once instead of for every scan, and
+redundant explicit RegExp cloning is avoided when `matchAll` supplies isolation.
+Reproduce with `node --max-old-space-size=256 experiments/issue-89/benchmark.mjs`
+and optionally pass a released checkout's `src/index.js`. For latency-sensitive
+logging, measure the real workload before synchronously sanitizing every line;
+the existing JSONL record-worker API/CLI can move record scanning off the main
+thread (see [API.md](API.md)). External engines and more sensitive values can add
+further work. These numbers do not describe `createSanitizer` with Secretlint.
+
+The [complete issue 89 requirement inventory](case-studies/issue-89/README.md)
+records every row, root cause, alternative and regression mapping.
+
+## Document URL and field refinements (issues 91 and 94)
+
+The document profile detects `email=` and `phone=` query values in absolute and
+relative URLs and access-log text, retaining the label while percent-decoding.
+It replaces the same complete value for plain and percent-encoded contacts,
+without reserializing unaffected URL bytes. Invalid percent escapes do not
+qualify through this decoding rule. Personal `/u/`, `/in/`, `/user(s)/`,
+`/profile(s)/`, `/people/`, `/member(s)/` and `/home/` paths apply independently
+of the containing field label. These paths can also describe public accounts;
+the rule cannot establish identity or access permissions.
+
+An absolute HTTP(S) URL with a 24–128-character ASCII alphanumeric/underscore/
+hyphen path segment is treated as a possible share link and replaced, including
+Google Drive/Docs and generic `/s/<opaque-id>` links. This is a conservative
+shape rule, not a check of sharing permissions or entropy; public URLs with
+long segments may also match. Ordinary documentation paths and provider roots
+remain unchanged. Personal site roots such as
+`портфолио https://ivan-petrov.example.org/` remain a documented limit: a root
+alone cannot establish that the site belongs to a person.
+
+Structured document field aliases remove `_`/`-` and ignore case before matching
+this explicit vocabulary: `firstName`, `lastName`, `middleName`, `patronymic`,
+`birthday`, `birthDate`, `sex`, `citizenship`, `nationality`, `company`,
+`companyName`, `employer`, `university`, `school`, `contact`, `resumeUrl`,
+`alternateUrl`, `profileUrl`, `companyUrl`. Their nonempty string values are
+sensitive in full, including ISO birth timestamps. Thus `first_name` and
+`firstName`, or `birth_date` and `birthDate`, follow the same policy. These are
+schema assumptions: `contact` or `company` can hold operational data too.
+Existing native labels still apply. Unlisted URL-named fields have ordinary
+content detection; arbitrary names do not imply sensitivity. Declare them with
+[`sensitiveFields`](API.md#caller-declared-sensitive-fields) to replace complete
+values, including non-string values. Generic numeric primitives otherwise keep
+the existing type-preservation policy.
+
+Employer labels consume multi-word values to a comma or line/quote boundary.
+Dated CV entries additionally support compound titles, title parentheses/slashes,
+quoted group names, legal-form/location suffixes, empty/`null` range ends,
+multiple entries, employer-first role entries and pipe-separated entries.
+The supplemental grammar uses finite title cues and bounded entries. Undated
+`Менеджер, Ромашка Лютик`, `- Ромашка Лютик 5 лет` and
+`Последнее место работы Ромашка Лютик` remain explicit ambiguous limits, as
+permitted by #94. Use known values or schema declarations for them.
+
+Company prose recognizes `компании «…»`, `опыт в`, `Роль в`, `проекты для`,
+capitalized lists after those cues, `опыт (Company Name)`, and names followed
+by `(2 года)`/`(3 года)`-style durations. Arbitrary uncued company words remain
+ambiguous; synchronous callers can supply `knownPersonal` lists or precomputed
+`findings`. Custom `detectors` callbacks are still used by `createSanitizer`
+only. No model or network service is required for these native rules.
+
+`контакт:` and `пишите,` introduce domestic mobile numbers. A complete line
+consisting of an 11-digit `79…` or `89…` mobile shape is also sensitive. Arbitrary
+prose numbers such as `order 89161234567 shipped` and `id 79161234567` remain
+unchanged. This shape rule does not prove that a number is assigned.
+
+Additional forms cover Cyrillic acronyms after `Education:`, `учился в`,
+`Соискатель:`/`Сотрудник:` names and split-line `С уважением,` signatures.
+`Дети: нет` remains an empty attribute with later JSON string lines preserved.
+When mapped escaped fragments lose detecting context on recursive decoding,
+redaction replaces the fragment instead of repeating an unchanged result until
+`ERR_RESIDUAL`; the surrounding JSON remains parseable.
+
+The [requirement inventory and research](case-studies/issue-100/README.md)
+records the complete scope and regression evidence.

package/examples/presidio-bridge.py

@@ -5,28 +5,34 @@ Example: python -m pip install presidio-analyzer
 Configure NlpEngineProvider here for other installed language models.
 This script does not download models or contact a remote analysis service.
 """
+
 import argparse
 import json
 import sys
 
+import spacy
 from presidio_analyzer import AnalyzerEngine
 from presidio_analyzer.nlp_engine import NlpEngineProvider
-import spacy
 
 parser = argparse.ArgumentParser()
-parser.add_argument('--language', default='en')
-parser.add_argument('--model', default='en_core_web_lg')
+parser.add_argument("--language", default="en")
+parser.add_argument("--model", default="en_core_web_lg")
 options = parser.parse_args()
 if not spacy.util.is_package(options.model):
-    raise SystemExit('Install the selected model before running this offline bridge.')
+    raise SystemExit("Install the selected model before running this offline bridge.")
 
 text = sys.stdin.read(10 * 1024 * 1024 + 1)
 if len(text) > 10 * 1024 * 1024:
     raise SystemExit(2)
-nlp = NlpEngineProvider(nlp_configuration={
-    'nlp_engine_name': 'spacy',
-    'models': [{'lang_code': options.language, 'model_name': options.model}],
-}).create_engine()
+nlp = NlpEngineProvider(
+    nlp_configuration={
+        "nlp_engine_name": "spacy",
+        "models": [{"lang_code": options.language, "model_name": options.model}],
+    }
+).create_engine()
 analyzer = AnalyzerEngine(nlp_engine=nlp, supported_languages=[options.language])
 results = analyzer.analyze(text=text, language=options.language)
-json.dump([{"start":r.start,"end":r.end,"entity_type":r.entity_type} for r in results], sys.stdout)
+json.dump(
+    [{"start": r.start, "end": r.end, "entity_type": r.entity_type} for r in results],
+    sys.stdout,
+)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-foundation/sensitive-data-sanitizer",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Offline sensitive-text sanitization with credential, multilingual personal-data and scanner union detection",
   "type": "module",
   "main": "src/index.js",
@@ -92,7 +92,7 @@
   },
   "devDependencies": {
     "@changesets/cli": "^3.0.3",
-    "eslint": "^9.38.0",
+    "eslint": "^10.13.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "husky": "^9.1.7",
@@ -101,7 +101,10 @@
     "mrz": "^5.0.2",
     "prettier": "^3.6.2",
     "secretlint": "13.0.7",
-    "test-anywhere": "^0.8.48"
+    "test-anywhere": "^0.8.48",
+    "@eslint/js": "^10.0.1",
+    "command-stream": "2.4.0",
+    "lino-arguments": "0.4.0"
   },
   "lint-staged": {
     "*.{js,mjs,cjs}": [
@@ -112,6 +115,17 @@
     "*.md": [
       "prettier --write",
       "prettier --check"
+    ],
+    "*.sh": [
+      "pipx run --spec shellcheck-py==0.11.0.1 shellcheck"
+    ],
+    "*.py": [
+      "pipx run --spec ruff==0.17.3 ruff check --fix --force-exclude",
+      "pipx run --spec ruff==0.17.3 ruff format --force-exclude",
+      "pipx run --spec ruff==0.17.3 ruff format --check --force-exclude"
+    ],
+    ".husky/*": [
+      "pipx run --spec shellcheck-py==0.11.0.1 shellcheck"
     ]
   },
   "dependencies": {
@@ -124,5 +138,11 @@
     "re2-wasm": "1.0.2",
     "re2js": "^2.9.0",
     "yaml": "^2.9.1"
+  },
+  "allowScripts": {
+    "node-pty": false
+  },
+  "overrides": {
+    "minimatch@>=7 <11": "^11.0.4"
   }
 }

package/src/context.js

@@ -247,7 +247,7 @@ function operationalValue(value, type) {
   return (
     (type === 'URL' &&
       /^\/(?!\/)[^\s?@#]*$/.test(value) &&
-      !/(?:^|\/)(?:users?|profiles?|people|members?|home)\/[^/]+/i.test(
+      !/(?:^|\/)(?:u|in|users?|profiles?|people|members?|home)\/[^/]+/i.test(
         value
       )) ||
     (type === 'TIME' &&
@@ -393,19 +393,24 @@ function detectCredentials(text, emit) {
   }
 }
 
-function detectPersonalLabels(text, emit) {
-  for (const [type, words] of Object.entries(labels)) {
-    if (type === 'credential') {
-      continue;
-    }
+const personalPrefixes = Object.entries(labels)
+  .filter(([type]) => type !== 'credential')
+  .map(([type, words]) => {
     const separator =
       type === 'ID'
         ? `(?:[:=：]|(?:${verbs})(?![\\p{L}\\p{N}_]))?[ \\t]+|[:=：][ \\t]*`
         : `(?:[:=：]|(?:${verbs})(?![\\p{L}\\p{N}_]))[ \\t]*`;
-    const prefix = new RegExp(
-      `(?<![\\p{L}\\p{N}_])(?:\\\\*["'])?(?:${words.map(escapePattern).join('|')})(?![\\p{L}\\p{N}_])(?:\\\\*["'])?[ \\t]*(?:${separator})`,
-      'giu'
-    );
+    return [
+      type,
+      new RegExp(
+        `(?<![\\p{L}\\p{N}_])(?:\\\\*["'])?(?:${words.map(escapePattern).join('|')})(?![\\p{L}\\p{N}_])(?:\\\\*["'])?[ \\t]*(?:${separator})`,
+        'giu'
+      ),
+    ];
+  });
+
+function detectPersonalLabels(text, emit) {
+  for (const [type, prefix] of personalPrefixes) {
     for (const match of text.matchAll(prefix)) {
       const identity = type === 'ID';
       const suffix = identity
@@ -416,7 +421,11 @@ function detectPersonalLabels(text, emit) {
       const range = valueRange(
         text,
         match.index + match[0].length + suffix.length,
-        identity ? 'token' : 'line',
+        /[?&]$/.test(text.slice(0, match.index))
+          ? 'query'
+          : identity
+            ? 'token'
+            : 'line',
         512
       );
       if (range && personalValueAllowed(text, range, type, match.index)) {

package/src/credentials.js

@@ -45,10 +45,26 @@ export function detectCredentialFormats(text, emit) {
     (value) =>
       !credentialPlaceholder(value) && value !== 'put your unique phrase here'
   );
-  collectMatches(
-    text,
-    /PuTTY-User-Key-File-[23]:[^\r\n]*(?:\r\n|\r|\n)[\s\S]*?(?:Private-MAC:[ \t]*[a-fA-F0-9]+|$)/g,
-    emit,
-    details('putty-private-key')
-  );
+  detectPuttyPrivateKeys(text, emit);
+}
+
+// Scan each consumed range once. A regex combining an unbounded header line
+// and a lazy body rescans every repeated header when the newline is missing.
+function detectPuttyPrivateKeys(text, emit) {
+  const headers = /PuTTY-User-Key-File-[23]:/g;
+  const lineEnd = /[\r\n]/g;
+  const mac = /Private-MAC:[ \t]*[a-fA-F0-9]+/g;
+  let header;
+  while ((header = headers.exec(text))) {
+    lineEnd.lastIndex = headers.lastIndex;
+    const newline = lineEnd.exec(text);
+    if (!newline) {
+      break;
+    }
+    mac.lastIndex = newline.index + 1;
+    const terminator = mac.exec(text);
+    const end = terminator ? mac.lastIndex : text.length;
+    emit({ start: header.index, end, ...details('putty-private-key') });
+    headers.lastIndex = end;
+  }
 }

package/src/detection.js

@@ -58,11 +58,14 @@ export function collectMatches(
   group = 0,
   accept = () => true
 ) {
-  // Clone expressions so concurrent callers never share lastIndex.
-  const pattern = new RegExp(
-    regex.source,
-    regex.flags.includes('g') ? regex.flags : `${regex.flags}g`
-  );
+  // matchAll clones global expressions and leaves their lastIndex untouched.
+  const pattern =
+    regex.global && regex.lastIndex === 0
+      ? regex
+      : new RegExp(
+          regex.source,
+          regex.global ? regex.flags : `${regex.flags}g`
+        );
   for (const match of text.matchAll(pattern)) {
     const raw = match[group];
     const value = details.category === 'personal' ? raw?.trim() : raw;
@@ -270,7 +273,19 @@ function detectPersonalFormats(text, options, emit) {
   collectMatches(
     text,
     /(?<!\d)\+\d[\d ()-]{6,24}\d(?!\d)/g,
-    emit,
+    (finding) => {
+      if (
+        /[?&]phone=$/i.test(
+          text.slice(Math.max(0, finding.start - 8), finding.start)
+        )
+      ) {
+        const token = /^[^\s&#]+/.exec(
+          text.slice(finding.start, finding.end)
+        )[0];
+        finding.end = finding.start + token.length;
+      }
+      emit(finding);
+    },
     { type: 'PHONE', category: 'personal', rule: 'international-phone' },
     0,
     (v) => {

package/src/document-entities.js

@@ -3,6 +3,7 @@ import { firstNames } from './names.js';
 import { organizationCore, personalRegex } from './personal-variants.js';
 import { documentVocabulary } from './document-vocabulary.js';
 import { months } from './personal-context.js';
+import { detectDocumentExtras } from './document-extras.js';
 import { detectDocumentPatterns } from './document-patterns.js';
 
 const words = (column) =>
@@ -47,7 +48,7 @@ const ruAcronym =
 const ruResidence =
   /(?:[Гг]ород|[Пп]роживаю|[Пп]роживание|[Мм]есто жительства)[ \t]*:[ \t]*([А-ЯЁ][а-яё-]{2,47})|([А-ЯЁ][а-яё-]{2,47})(?=,[ \t]*(?:готов[а]?[ \t]+к[ \t]+переезду|Россия|Беларусь|Казахстан|Украина))/gu;
 const ruIntroduction = new RegExp(
-  `(?:[Мм]еня зовут|[Сс] уважением)[, \t]+(${firstNames.ru.split(' ').join('|')})(?!${boundary})`,
+  `(?:[Мм]еня зовут|[Сс] уважением)[, \t\r\n]+(${firstNames.ru.split(' ').join('|')})(?!${boundary})`,
   'gu'
 );
 const groupOrganization = new RegExp(
@@ -67,7 +68,7 @@ const rangeOpen = ['по настоящее время', 'настоящее в
   .flatMap((word) => [word, capitalized(word)])
   .map(escapePattern)
   .join('|');
-const range = `${rangeStart}(?:[ \\t]*[-–—][ \\t]*|[ \\t]+(?:по|to)[ \\t]+)(?:${rangeStart}|${rangeOpen})(?!${boundary})`;
+const range = `${rangeStart}(?:[ \\t]*[-–—][ \\t]*|[ \\t]+(?:по|to)[ \\t]+)(?:${rangeStart}|${rangeOpen}|null|(?=\\)))(?!${boundary})`;
 const titleWord = '[\\p{L}\\p{N}][\\p{L}\\p{N}/+#.&-]{0,39}';
 // A segment starts a line or follows `|`. `Опыт:` or `Опыт -` before the title
 // reads like a list marker: the date range remains the anchor of the rule.
@@ -89,6 +90,7 @@ export function detectDocumentEntities(text, emit, options) {
     return;
   }
   detectDocumentPatterns(text, emit);
+  detectDocumentExtras(text, emit, range);
   const found = [];
   const capture = (finding) => {
     found.push(finding);

package/src/document-extras.js

@@ -0,0 +1,170 @@
+import { collectMatches } from './detection.js';
+
+const boundary = '[\\p{L}\\p{N}_]';
+const proper = '[\\p{Lu}][\\p{L}\\p{M}\\p{N}.-]{0,46}[\\p{L}\\p{M}\\p{N}]';
+const name = `${proper}(?:[ \\t]+${proper}){0,5}`;
+const orgList = `(?:«[^«»\\r\\n]{1,160}»|${name})(?:[ \\t]*(?:,|и|and)[ \\t]+${name}){0,5}`;
+const cues = new RegExp(
+  `(?<!${boundary})(?:компании|опыт[ \\t]+в|проекты[ \\t]+для|[Рр]оль[ \\t]+в)[ \\t]+(${orgList})(?!${boundary})`,
+  'gu'
+);
+const duration = new RegExp(
+  `(?<!${boundary})(${name})(?=[ \\t]*\\(\\d{1,2}[ \\t]+(?:год|года|лет|years?)\\))`,
+  'gu'
+);
+// JavaScript's \b is ASCII-only; Cyrillic titles use a Unicode lookahead.
+const role =
+  /^(?:менеджер|директор|руководитель|инженер|аналитик|разработчик)(?![\p{L}])|^(?:manager|director|engineer|developer|senior|qa)\b/iu;
+
+export function detectDocumentExtras(text, emit, range) {
+  for (const [type, rule, pattern, group] of [
+    ['PHONE', 'document-mobile-bare', /^[78]9\d{9}$/gm, 0],
+    [
+      'PHONE',
+      'document-mobile-context',
+      /(?<![\p{L}\p{N}_])(?:пишите|контакт)[:,]?[ \t]+([78]9\d{9})(?!\d)/giu,
+      1,
+    ],
+    [
+      'ORGANIZATION',
+      'organization-experience-prose',
+      new RegExp(`опыт[ \\t]*\\((${name})\\)`, 'gu'),
+      1,
+    ],
+    ['ORGANIZATION', 'organization-duration', duration, 1],
+    [
+      'PERSON',
+      'document-role',
+      /(?<![\p{L}\p{N}_])(?:Соискатель|Сотрудник)[ \t]*:[ \t]*([\p{Lu}][\p{L}-]{1,47}(?:[ \t]+[\p{Lu}][\p{L}-]{1,47}){0,4})/gu,
+      1,
+    ],
+    [
+      'URL',
+      'document-personal-path',
+      /(?<![\p{L}\p{N}_])(?:https?:\/\/[^\s/"<>]+)?\/(?:u|in|users?|profiles?|people|members?|home)\/[^\s?&#"<>\\]{1,128}/giu,
+      0,
+    ],
+    [
+      'URL',
+      'document-share-link',
+      /https?:\/\/[^\s/"<>]+\/(?:[^\s/?#"<>]{1,64}\/){0,5}[A-Za-z0-9_-]{24,128}(?:\/[^\s?&#"<>\\]{0,64})?/gu,
+      0,
+    ],
+  ]) {
+    collectMatches(
+      text,
+      pattern,
+      emit,
+      { type, rule, category: 'personal', confidence: 0.85 },
+      group
+    );
+  }
+  for (const match of text.matchAll(cues)) {
+    const offset = match.index + match[0].lastIndexOf(match[1]);
+    for (const company of match[1].matchAll(
+      new RegExp(`«[^«»\\r\\n]{1,160}»|${name}`, 'gu')
+    )) {
+      emit({
+        start: offset + company.index,
+        end: offset + company.index + company[0].length,
+        type: 'ORGANIZATION',
+        category: 'personal',
+        rule: 'organization-cue',
+        confidence: 0.85,
+      });
+    }
+  }
+  detectQueryContacts(text, emit);
+  detectExperience(text, emit, range);
+}
+
+function detectQueryContacts(text, emit) {
+  // Retain query context while decoding; standalone contacts may be public specimens.
+  for (const match of text.matchAll(
+    /[?&](email|phone)=([^\s&#"<>\\]{1,512})/giu
+  )) {
+    let value;
+    try {
+      value = decodeURIComponent(match[2]);
+    } catch {
+      continue;
+    }
+    const email = match[1].toLowerCase() === 'email';
+    if (
+      !(
+        email ? /^[^\s@]+@[^\s@]+\.[\p{L}]{2,63}$/u : /^\+?[\d () .-]{7,40}$/
+      ).test(value)
+    ) {
+      continue;
+    }
+    if (value === '[REDACTED]') {
+      continue;
+    }
+    const start = match.index + match[0].length - match[2].length;
+    emit({
+      start,
+      end: start + match[2].length,
+      type: email ? 'EMAIL' : 'PHONE',
+      category: 'personal',
+      rule: 'label',
+      confidence: 0.95,
+    });
+  }
+}
+
+function detectExperience(text, emit, range) {
+  // Date anchors bound each entry; do not guess at undated employer/title fragments.
+  collectMatches(
+    text,
+    new RegExp(
+      `(?:^|[\\r\\n])[ \\t]*[^|\\r\\n]{1,120}\\|[ \\t]*(${name})[ \\t]*\\|[ \\t]*${range}`,
+      'gu'
+    ),
+    emit,
+    {
+      type: 'ORGANIZATION',
+      rule: 'organization-experience',
+      category: 'personal',
+      confidence: 0.85,
+    },
+    1
+  );
+  const dated = new RegExp(`([^\\r\\n;|]{1,320}?)\\((${range})\\)`, 'gu');
+  for (const match of text.matchAll(dated)) {
+    const prefix = match[1];
+    const content = prefix
+      .replace(/^.*\(\d[^)]*\)[, \t]*/, '')
+      .replace(/^[, \t]+/, '');
+    const chunks = [...content.matchAll(/[^,]+/g)];
+    const parts = chunks.map((part) => part[0].trim());
+    let value;
+    if (parts.length > 1 && role.test(parts[0])) {
+      let index = 1;
+      while (index < parts.length - 1 && /^[\p{Ll}]/u.test(parts[index])) {
+        index++;
+      }
+      value = content.slice(chunks[index].index).trim();
+    } else if (parts.length === 2 && role.test(parts[1])) {
+      value = parts[0].trim();
+    }
+    if (
+      !value ||
+      !/^[\p{Lu}«“"]/u.test(value) ||
+      value.includes('[REDACTED]')
+    ) {
+      continue;
+    }
+    const start = match.index + prefix.lastIndexOf(value);
+    if (start < match.index) {
+      continue;
+    }
+    emit({
+      start,
+      end: start + value.length,
+      type: 'ORGANIZATION',
+      category: 'personal',
+      rule: 'organization-experience',
+      confidence: 0.85,
+    });
+  }
+}

package/src/document-fields.js

@@ -0,0 +1,19 @@
+// One explicit field vocabulary; camelCase, snake_case and kebab-case normalize alike.
+const groups = {
+  PERSON: ['firstname', 'lastname', 'middlename', 'patronymic'],
+  DATE_OF_BIRTH: ['birthday', 'birthdate'],
+  GENDER: ['sex'],
+  PERSONAL_ATTRIBUTE: ['citizenship', 'nationality'],
+  ORGANIZATION: ['company', 'companyname', 'employer'],
+  EDUCATION: ['university', 'school'],
+  PHONE: ['contact'],
+  URL: ['resumeurl', 'alternateurl', 'profileurl', 'companyurl'],
+};
+const types = new Map(
+  Object.entries(groups).flatMap(([type, fields]) =>
+    fields.map((field) => [field, type])
+  )
+);
+export function documentFieldType(field) {
+  return types.get(field.replace(/[_-]/g, '').toLowerCase());
+}

package/src/document-patterns.js

@@ -11,7 +11,7 @@ const given = [
   ...new Set(Object.values(firstNames).flatMap((s) => s.split(' '))),
 ].join('|');
 const nameInitials = new RegExp(
-  `(?<!${boundary})(?:${surname}[ \\t]+${initials}|${initials}(?:${surname}|${latinSurname})|${latinSurname}[ \\t]+${initials}|(?:${given})[ \\t]+[А-ЯЁA-Z]\\.)(?!${boundary})`,
+  `(?<!${boundary})(?:${word}[ \\t]+(?:[А-ЯЁ]\\.[ \\t]*){2}|${surname}[ \\t]+${initials}|${initials}(?:${surname}|${latinSurname})|${latinSurname}[ \\t]+${initials}|(?:${given})[ \\t]+[А-ЯЁA-Z]\\.)(?!${boundary})`,
   'gu'
 );
 const namePairs = new RegExp(
@@ -30,13 +30,13 @@ const rules = [
   [
     'PHONE',
     'document-phone-label',
-    /(?<![\p{L}\p{N}_])(?:тел\.?|моб\.?|WhatsApp)(?:[ \t]*:[ \t]*|[ \t]+)((?:[78][ () .-]*)?9\d{2}[ () .-]*\d{3}[ .-]*\d{2}[ .-]*\d{2})(?!\d)/giu,
+    /(?<![\p{L}\p{N}_])(?:(?:контактный[ \t]+)?телефон|контакт|тел\.?|моб\.?|сот\.?|WhatsApp)(?:[ \t]*:[ \t]*|[ \t]+)((?:[78][ () .-]*)?9\d{2}[ () .-]*\d{3}[ .-]*\d{2}[ .-]*\d{2})(?!\d)/giu,
     1,
   ],
   [
     'EMAIL',
     'obfuscated-email',
-    /(?<![\p{L}\p{N}_.+-])[\p{L}\p{N}_+-]{1,64}(?:(?:\.|[ \t]{1,8}dot[ \t]{1,8})[\p{L}\p{N}_+-]{1,64}){0,4}(?:[ \t]{0,8}\(at\)[ \t]{0,8}|[ \t]{0,8}\[at\][ \t]{0,8}|[ \t]{1,8}(?:at|собака)[ \t]{1,8})[\p{L}\p{N}-]{1,63}(?:(?:\.|[ \t]{1,8}dot[ \t]{1,8})[\p{L}\p{N}-]{1,63}){1,8}(?![\p{L}\p{N}_])/giu,
+    /(?<![\p{L}\p{N}_.+\\-])[\p{L}\p{N}_+-]{1,64}(?:(?:\.|[ \t]{1,8}dot[ \t]{1,8})[\p{L}\p{N}_+-]{1,64}){0,4}(?:[ \t]{0,8}\((?:at|собака)\)[ \t]{0,8}|[ \t]{0,8}\[at\][ \t]{0,8}|[ \t]{1,8}(?:at|собака)[ \t]{1,8})[\p{L}\p{N}-]{1,63}(?:(?:\.|[ \t]{1,8}dot[ \t]{1,8})[\p{L}\p{N}-]{1,63}){1,8}(?![\p{L}\p{N}_])/giu,
     0,
   ],
   [
@@ -48,7 +48,7 @@ const rules = [
   [
     'USERNAME',
     'messenger-label',
-    /(?<![\p{L}\p{N}_])(?:Telegram|телеграм|tg|skype|ник)(?:[ \t]*:[ \t]*|[ \t]+)(@?[a-z][a-z\d_.-]{2,63})(?![\p{L}\p{N}_])/giu,
+    /(?<![\p{L}\p{N}_])(?:Telegram|телеграм|телега|tg|skype|Zoom|ник)(?:[ \t]*:[ \t]*|[ \t]+)(@?[a-z][a-z\d_.-]{2,63})(?![\p{L}\p{N}_])/giu,
     1,
   ],
   [
@@ -60,13 +60,13 @@ const rules = [
   [
     'ID',
     'identity-number',
-    /(?<![\p{L}\p{N}_])(?:ОГРНИП[ \t]+(\d{15})|код подразделения[ \t]+(\d{3}-\d{3})|(?:водительское удостоверение|в\/у|Driver's licen[cs]e)[ \t]+(\d{2}[ \t]?\d{2}[ \t]?\d{6})|(?:ОМС|полис)[ \t]+(\d{16})|сч[её]т[ \t]+(\d{20})|диплом[ \t]+(?:№|No|#)[ \t]*(\d{6}))(?!\d)/giu,
+    /(?<![\p{L}\p{N}_])(?:ОГРНИП[ \t]+(\d{15})|код подразделения[ \t]+(\d{3}-\d{3})|(?:водительское удостоверение|в\/у|Driver's licen[cs]e)[ \t]+(\d{2}[ \t]?\d{2}[ \t]?\d{6})|(?:ОМС|полис)[ \t]+(\d{16})|(?:сч[её]т|р\/с)[ \t]+(\d{20})|диплом[ \t]+(?:№|No|#)[ \t]*(\d{6}))(?!\d)/giu,
     -1,
   ],
   [
     'ID',
     'passport-issuer',
-    /(?<![\p{L}\p{N}_])выдан[ \t]+((?:ОВД|УВД|МВД)[ \t]+[^\r\n";|]{1,120}?\d{2}\.\d{2}\.\d{4})(?!\d)/giu,
+    /(?<![\p{L}\p{N}_])выдан[ \t]+((?:ОВД|УВД|МВД|(?:ТП[ \t]+)?УФМС)[ \t]+[^\r\n";|]{1,120}?\d{2}\.\d{2}\.\d{4})(?!\d)/giu,
     1,
   ],
   [
@@ -78,15 +78,27 @@ const rules = [
   [
     'EDUCATION',
     'school-acronym-context',
-    /(?<![\p{L}\p{N}_])(?:образование|ВУЗ|университет|окончил[аи]?)(?:[ \t]*:[ \t]*|[ \t]+)([А-ЯЁ]{2,12}(?:[ \t]+им\.[ \t]+[А-ЯЁ][а-яё-]{2,40})?)(?![\p{L}\p{N}_])/giu,
+    /(?<![\p{L}\p{N}_])(?:образование|ВУЗ|университет|учил(?:ся|ась)[ \t]+в|окончил[аи]?)(?:[ \t]*:[ \t]*|[ \t]+)([А-ЯЁ]{2,12}(?:[ \t]+им\.[ \t]+[А-ЯЁ][а-яё-]{2,40})?)(?![\p{L}\p{N}_])/giu,
     1,
   ],
+  [
+    'EDUCATION',
+    'education-label',
+    /(?<![\p{L}\p{N}_])Education[ \t]*:[ \t]*([\p{Lu}][\p{L}.-]{1,47})(?![\p{L}\p{N}_])/gu,
+    1,
+  ],
+  [
+    'PERSONAL_ATTRIBUTE',
+    'profile-prose',
+    /(?<![\p{L}\p{N}_])(?:граждан(?:ин|ка)[ \t]+([А-ЯЁ]{2,4})|есть[ \t]+((?:один|одна|двое|трое|четверо|пятеро|\d{1,2})[ \t]+(?:детей|реб[её]нок|реб[её]нка)))(?![\p{L}\p{N}_])/gu,
+    -1,
+  ],
   ['PERSON', 'name-initials', nameInitials, 0],
   [
     'PERSON',
     'name-title',
     new RegExp(
-      `(?<!${boundary})(?:г-жа|господин|госпожа)[ \\t]+(${word})(?!${boundary})`,
+      `(?<!${boundary})(?:г-жа|г-н|господин|госпожа)[ \\t]+(${word})(?!${boundary})`,
       'gu'
     ),
     1,
@@ -94,34 +106,31 @@ const rules = [
   [
     'DATE_OF_BIRTH',
     'birth-year',
-    /(?<![\p{L}\p{N}_])(?:д\.р\.|год рождения|родил(?:ся|ась)(?:[ \t]+в)?|Born(?:[ \t]+in)?)[ \t]*:?[ \t]*((?:19|20)\d{2})(?!\d)|(?<!\d)((?:19|20)\d{2})(?=[ \t]+г\.р\.)/giu,
+    /(?<![\p{L}\p{N}_])(?:д\.р\.|г\.р\.|год рождения|родил(?:ся|ась)(?:[ \t]+в)?|Born(?:[ \t]+in)?)[ \t]*:?[ \t]*((?:19|20)\d{2})(?!\d)|(?<!\d)((?:19|20)\d{2})(?=[ \t]+(?:г\.р\.|года[ \t]+рождения)(?![\p{L}\p{N}_]))/giu,
     -1,
   ],
   [
     'AGE',
     'age-context',
-    /(?<![\p{L}\p{N}_])(?:возраст[ \t]*:|мне|исполнилось)[ \t]*(\d{1,3})(?!\d)|(?<![\p{L}\p{N}_])(\d{1,3})(?=[ \t]+(?:года|год|лет)(?![\p{L}\p{N}_]))/giu,
+    /(?<![\p{L}\p{N}_])(?:(?:возраст|Age)(?:[ \t]*:[ \t]*|[ \t]+)|(?:мне|исполнилось)[ \t]+)(\d{1,3})(?!\d)|(?<![\p{L}\p{N}_])(?:Женщина|Мужчина),[ \t]*(\d{1,3})(?=[ \t]+(?:года|год|лет)(?![\p{L}\p{N}_]))/giu,
     -1,
   ],
   [
     'GENDER',
     'gender-context',
-    /(?<![\p{L}\p{N}_])(?:Пол|Sex)[ \t]*:[ \t]*(женский|мужской|male|female)(?![\p{L}\p{N}_])|(?<![\p{L}\p{N}_])(Женщина|Мужчина)(?=,[ \t]*\d{1,3}[ \t]+(?:года|год|лет))/giu,
+    /(?<![\p{L}\p{N}_])(?:Пол|Sex)(?:[ \t]*:[ \t]*|[ \t]+)(женский|мужской|жен\.|муж\.|Ж|М|male|female)(?![\p{L}\p{N}_])|(?<![\p{L}\p{N}_])(Женщина|Мужчина)(?=,[ \t]*\d{1,3}[ \t]+(?:года|год|лет))/giu,
     -1,
   ],
   [
     'PERSONAL_ATTRIBUTE',
     'profile-attribute',
-    /(?<![\p{L}\p{N}_])(?:Гражданство|Citizenship|Семейное положение|Marital status|Дети|национальность|Вероисповедание|инвалидность|судимость)[ \t]*:[ \t]*([^\r\n";|]{1,160})/giu,
+    /(?<![\p{L}\p{N}_])(?:Гражданство|Citizenship|Семейное положение|Marital status|Дети|национальность|Вероисповедание|инвалидность|судимость)[ \t]*:[ \t]*([^\\\r\n";|]{1,160})/giu,
     1,
   ],
   [
     'ORGANIZATION',
     'employer-label',
-    new RegExp(
-      `(?<!${boundary})(?:[Кк]омпания|[Рр]аботодатель|[Мм]есто работы)[ \\t]*:[ \\t]*(${word})(?!${boundary})`,
-      'gu'
-    ),
+    /(?<![\p{L}\p{N}_])(?:Компания|Работодатель|Место работы|Company|Employer)[ \t]*:[ \t]*([\p{Lu}][^,;|\\\r\n":]{0,159})/giu,
     1,
   ],
   [
@@ -146,7 +155,7 @@ const rules = [
     'LOCATION',
     'residence-prose',
     new RegExp(
-      `(?<!${boundary})(?:живу[ \\t]+в|из|м\\.|метро|район)[ \\t]+(${word})(?!${boundary})`,
+      `(?<!${boundary})(?:(?:живу|проживаю)[ \\t]+в|из|м\\.|метро|район)[ \\t]+(${word})(?!${boundary})`,
       'gu'
     ),
     1,
@@ -166,7 +175,12 @@ export function detectDocumentPatterns(text, emit) {
         group === -1
           ? match.slice(1).find((part) => part !== undefined)
           : match[group].trim();
-      if (!documentValueAllowed(rule, value)) {
+      if (
+        !documentValueAllowed(rule, value) ||
+        (rule === 'profile-attribute' &&
+          /^Дети[ \t]*:/iu.test(match[0]) &&
+          /^нет$/iu.test(value))
+      ) {
         continue;
       }
       const start =
@@ -219,6 +233,10 @@ function documentValueAllowed(rule, value) {
       rule === 'school-acronym-context' &&
       !/^[А-ЯЁ]{2,12}(?![А-ЯЁа-яё])/.test(value)
     ) &&
+    !(
+      rule === 'profile-attribute' &&
+      /^(?:не указан[оаы]?|not specified|unknown|n\/a)$/iu.test(value)
+    ) &&
     !(rule === 'messenger-label' && /^(?:недоступен|unavailable)$/i.test(value))
   );
 }

package/src/engines.js

@@ -24,6 +24,8 @@ import {
 } from './placeholders.js';
 import {
   structuredBatches,
+  structuredFieldFindings,
+  declaredFieldFindings,
   structuredValueViews,
   mapStructuredFindings,
   verifyStructured,
@@ -131,6 +133,7 @@ async function analyzeStructured(
 ) {
   const findings = [];
   for (const batch of structuredBatches(text, options)) {
+    findings.push(...structuredFieldFindings(batch, options));
     for (const finding of mapStructuredFindings(
       batch,
       await analyze(
@@ -162,10 +165,18 @@ async function analyzeStructured(
   }
   // Native structured inspection validates, locates and reapplies the
   // same fake-value/public policy to source offsets from all engines.
-  return inspectFindingsOnly(text, [...findings, ...(nativeFindings ?? [])], {
-    ...options,
-    findings: initial,
-  });
+  return inspectFindingsOnly(
+    text,
+    [
+      ...findings,
+      ...declaredFieldFindings(text, options),
+      ...(nativeFindings ?? []),
+    ],
+    {
+      ...options,
+      findings: initial,
+    }
+  );
 }
 
 export function createSanitizer(options = {}) {

package/src/identity.js

@@ -181,11 +181,11 @@ function detectPassports(text, emit) {
   });
 }
 const booking =
-  /(?<![\p{L}\p{N}_])(?:booking(?:[ _-]+(?:reference|code))?|reservation(?:[ _-]+code)?|confirmation(?:[ _-]+code)?|бронь|record[ _-]+locator|PNR|код брони|номер брони|бронирование)[ \t]*[:=：]?[ \t]*[`"']?([A-Z0-9]{4,8})(?![\p{L}\p{N}_])/giu;
+  /(?<![\p{L}\p{N}_])(?:booking(?:[ _-]+(?:reference|code))?|reservation(?:[ _-]+code)?|confirmation(?:[ _-]+code)?|бронь|record[ _-]+locator|PNR|код брони|номер брони|бронирование)[ \t]*(?:[:=：][ \t]*)?[`"']?([A-Z0-9]{4,8})(?![\p{L}\p{N}_])/giu;
 const ticket =
-  /(?<![\p{L}\p{N}_])(?:e[ -]?ticket|ticket[ _-]*(?:number|no)?|номер билета|электронный билет)[ \t]*[:=：]?[ \t]*[`"']?(\d{3}[ -]?\d{10})(?![\p{L}\p{N}_])/giu;
+  /(?<![\p{L}\p{N}_])(?:e[ -]?ticket|ticket[ _-]*(?:number|no)?|номер билета|электронный билет)[ \t]*(?:[:=：][ \t]*)?[`"']?(\d{3}[ -]?\d{10})(?![\p{L}\p{N}_])/giu;
 const visa =
-  /(?<![\p{L}\p{N}_])(?:e[ -]?visa|visa|номер визы|виза)(?:[ \t_-]+(?:registration|application|number|no|code|номер|код)){0,3}[ \t]*[:=：]?[ \t]*[`"']?([A-Z0-9][A-Z0-9-]{4,31})(?![\p{L}\p{N}_])/giu;
+  /(?<![\p{L}\p{N}_])(?:e[ -]?visa|visa|номер визы|виза)(?:[ \t_-]+(?:registration|application|number|no|code|номер|код)){0,3}[ \t]*(?:[:=：][ \t]*)?[`"']?([A-Z0-9][A-Z0-9-]{4,31})(?![\p{L}\p{N}_])/giu;
 const placeholder =
   /^(?:NONE|UNKNOWN|NULL|UNDEFINED|REDACTED|EXAMPLE|SAMPLE|PENDING|HOTEL|BOOKING|REFERENCE|REGISTRATION|APPLICATION|NUMBER|CODE|FAILED|ERROR|HTTP|OK|CANCELLED|CONFIRMED|SUCCESS|READY|ACTIVE|CLOSED)$/i;
 function detectTravel(text, emit) {

package/src/index.d.ts

@@ -67,6 +67,8 @@ export interface SanitizerOptions {
   structured?: 'json' | 'jsonl';
   /** Property names whose metadata heuristics may be suppressed. */
   structuralFields?: string[];
+  /** Exact, case-sensitive property names whose entire values are redacted in JSON/JSONL. */
+  sensitiveFields?: string[];
   /** Personal replacement threshold, default 0.5. Inspect retains lower scores. */
   minConfidence?: number;
   /** Alias for minConfidence; specifying both requires equal values. */

package/src/personal.js

@@ -224,7 +224,7 @@ export function detectPersonal(text, emit) {
   );
   collectMatches(
     text,
-    /(?<![\p{L}\p{N}])\d{1,6}[A-Za-z]?[ \t]+(?:[\p{Lu}][\p{L}.'-]*[ \t]+){1,5}(?:Street|St|Road|Rd|Avenue|Ave|Lane|Ln|Drive|Dr|Boulevard|Blvd|Way|Straße|Strasse|Rue|Calle|Rua)\b(?:,[ \t]+(?:[^\r\n<>]{1,80}?[ \t]+(?:[A-Z]{1,2}\d[A-Z\d]?[ \t]+\d[A-Z]{2}|\d{5}(?:-\d{4})?)\b|(?:[\p{Lu}][\p{Ll}.'-]+[ \t]*){1,4}))?/gu,
+    /(?<![\p{L}\p{N}])\d{1,6}[A-Za-z]?[ \t]+(?:[\p{Lu}][\p{L}.'-]*[ \t]+){1,5}(?:Street|St|Road|Rd|Avenue|Ave|Lane|Ln|Drive|Dr|Boulevard|Blvd|Way|Straße|Strasse|Rue|Calle|Rua)\b(?:,[ \t]+(?:(?:[^ \t\r\n<>][^\r\n<>]{0,79}?[ \t]+)?(?:[A-Z]{1,2}\d[A-Z\d]?[ \t]+\d[A-Z]{2}|\d{5}(?:-\d{4})?)\b|(?:[\p{Lu}][\p{Ll}.'-]+[ \t]*){1,4}))?/gu,
     emit,
     details('ADDRESS', 'postal-address')
   );

package/src/public.js

@@ -144,6 +144,7 @@ export function localAddress(value) {
   }
   const [a, b] = value.split('.').map(Number);
   return (
+    value === '0.0.0.0' ||
     a === 127 ||
     a === 10 ||
     (a === 172 && b >= 16 && b <= 31) ||

package/src/sanitizer.js

@@ -31,6 +31,8 @@ import {
 } from './placeholders.js';
 import {
   structuredBatches,
+  structuredFieldFindings,
+  declaredFieldFindings,
   inspectStructuredValues,
   mapStructuredFindings,
   preserveIdentifierKeys,
@@ -71,6 +73,7 @@ const optionNames = new Set([
   'fakeValues',
   'structured',
   'structuralFields',
+  'sensitiveFields',
   'minConfidence',
   'threshold',
   'profile',
@@ -101,12 +104,18 @@ function validateCollections(options) {
     'detectors',
     'fakeValues',
     'structuralFields',
+    'sensitiveFields',
   ]) {
     if (options[key] !== undefined && !Array.isArray(options[key])) {
       throw failure('ERR_CONFIG');
     }
   }
-  for (const key of ['knownSecrets', 'fakeValues', 'structuralFields']) {
+  for (const key of [
+    'knownSecrets',
+    'fakeValues',
+    'structuralFields',
+    'sensitiveFields',
+  ]) {
     if (
       (options[key] ?? []).some((value) => typeof value !== 'string' || !value)
     ) {
@@ -394,6 +403,7 @@ function inspectText(text, options = {}) {
   validateInput(text, options);
   if (options.structured) {
     const findings = structuredBatches(text, options).flatMap((batch) => [
+      ...structuredFieldFindings(batch, options),
       ...mapStructuredFindings(
         batch,
         inspect(batch.text, {
@@ -407,7 +417,11 @@ function inspectText(text, options = {}) {
         inspect(value, { ...options, structured: undefined, findings: [] })
       ),
     ]);
-    return inspectFindingsOnly(text, findings, options);
+    return inspectFindingsOnly(
+      text,
+      [...findings, ...declaredFieldFindings(text, options)],
+      options
+    );
   }
   const findings = [];
   const emit = (f) => {
@@ -602,6 +616,9 @@ export function markFake(text, findings, options) {
     ),
   ];
   return findings.map((f) => {
+    if (f.type === 'JSON_VALUE') {
+      return { ...f, kept: undefined };
+    }
     if (
       trusted.some(
         (span) =>
@@ -660,7 +677,9 @@ function validatedSpans(text, findings, options) {
       if (f.category === 'credential') {
         last.category = 'credential';
       }
-      if (credentialRun) {
+      if (last.type === 'JSON_VALUE' || f.type === 'JSON_VALUE') {
+        last.type = 'JSON_VALUE';
+      } else if (credentialRun) {
         last.type = 'SECRET';
       } else if (preferredType(last.type, f.type, options)) {
         last.type = f.type;
@@ -673,6 +692,12 @@ function validatedSpans(text, findings, options) {
 }
 
 function preferredType(current, candidate, options) {
+  if (current === 'JSON_VALUE') {
+    return false;
+  }
+  if (candidate === 'JSON_VALUE') {
+    return true;
+  }
   if (current === 'ENCODED_SENSITIVE') {
     return false;
   }
@@ -810,7 +835,7 @@ export async function redactResultAsync(
       );
       replacements.set(
         `${span.start}:${span.end}`,
-        encodeRun(run, result.text)
+        encodeRun(run, result.text === run.text ? REDACTED : result.text)
       );
     }
   }

package/src/structured.js

@@ -1,4 +1,5 @@
 import { failure } from './detection.js';
+import { documentFieldType } from './document-fields.js';
 import { hasPlaceholders } from './placeholders.js';
 
 // Session metadata is opt-in at the CLI; library callers choose their own
@@ -114,6 +115,33 @@ export function structuredBatches(text, options) {
   return batches;
 }
 
+// Schema declarations take priority over metadata/public/fake heuristics.
+export function structuredFieldFindings(batch, options) {
+  return batch.entries.flatMap((entry) => {
+    const type = options.documentEntities
+      ? documentFieldType(entry.field)
+      : undefined;
+    if (
+      entry.key ||
+      !type ||
+      entry.raw.length <= 2 ||
+      JSON.parse(entry.raw) === '[REDACTED]'
+    ) {
+      return [];
+    }
+    return [
+      {
+        start: entry.start + 1,
+        end: entry.start + entry.raw.length - 1,
+        type,
+        category: 'personal',
+        rule: 'known-personal',
+        confidence: 1,
+      },
+    ];
+  });
+}
+
 export function structuredValueRanges(text, options) {
   return structuredBatches(text, options).flatMap((batch) =>
     batch.entries
@@ -364,3 +392,70 @@ function stringOffsets(raw) {
   }
   return { starts, ends };
 }
+
+// A caller-declared property replaces its entire JSON value, including containers
+// and primitives. Source token offsets preserve the surrounding record.
+export function declaredFieldFindings(text, options) {
+  if (!options.sensitiveFields?.length) {
+    return [];
+  }
+  const fields = new Set(options.sensitiveFields);
+  const findings = [];
+  for (const token of lexemes(text)) {
+    if (
+      token.index < (findings.at(-1)?.end ?? 0) ||
+      !token.key ||
+      !fields.has(JSON.parse(token.raw))
+    ) {
+      continue;
+    }
+    let start = token.index + token.raw.length;
+    while (/[\s:]/.test(text[start] ?? '') && start < text.length) {
+      start++;
+    }
+    const end = jsonValueEnd(text, start);
+    if (text.slice(start, end) === '"[REDACTED]"') {
+      continue;
+    }
+    findings.push({
+      start,
+      end,
+      type: 'JSON_VALUE',
+      category: 'personal',
+      rule: 'known-personal',
+      confidence: 1,
+    });
+  }
+  return findings;
+}
+function jsonValueEnd(text, start) {
+  let depth = 0,
+    quoted = false;
+  for (let i = start; i < text.length; i++) {
+    const char = text[i];
+    if (quoted) {
+      if (char === '\\') {
+        i++;
+      } else if (char === '"') {
+        quoted = false;
+        if (!depth) {
+          return i + 1;
+        }
+      }
+    } else if (char === '"') {
+      quoted = true;
+    } else if (char === '[' || char === '{') {
+      depth++;
+    } else if (char === ']' || char === '}') {
+      if (!depth) {
+        return i;
+      }
+      if (!--depth) {
+        return i + 1;
+      }
+    } else if (!depth && /[\s,]/.test(char)) {
+      return i;
+    }
+  }
+  return text.length;
+}

package/src/transforms.js

@@ -183,6 +183,9 @@ function transformed(value, finding, transform, options) {
   return `${lower}–${lower + transform.size - 1}`;
 }
 export function renderReplacement(text, finding, options, encodedSanitize) {
+  if (finding.type === 'JSON_VALUE') {
+    return JSON.stringify(REDACTED);
+  }
   const transform =
     options.transformations?.[finding.type] ??
     options.transformation ??
@@ -193,7 +196,10 @@ export function renderReplacement(text, finding, options, encodedSanitize) {
     const raw = text.slice(finding.start, finding.end);
     const run = encodedValue(raw);
     if (run && (options.preserveEncoding || run.encoding === 'json-content')) {
-      return encodeRun(run, encodedSanitize(run.text).text);
+      const sanitized = encodedSanitize(run.text).text;
+      // Mapped escaped fragments can lose their detecting context on decode.
+      // Redact the fragment if recursive scanning makes no progress.
+      return encodeRun(run, sanitized === run.text ? REDACTED : sanitized);
     }
     if (options.preserveEncoding) {
       throw failure('ERR_ENCODING');