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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.16.1
+
+### Patch Changes
+
+- 4dfe2b7: Scan standalone and embedded JSON string values with their own line boundaries. Extend the documents profile's contact, identity, name, attribute, employer, school and residence rules, and preserve ordinary relative URLs, operational timestamps and context-free SHA-1-shaped values consistently.
+
 ## 0.16.0
 
 ### Minor Changes

package/docs/COVERAGE.md

@@ -202,3 +202,71 @@ Structured JSONL streaming supports 8 MiB records and ordered record workers;
 and reproducible throughput measurement. Realistic fake mode preserves supported
 scripts/formats/checksums and uses reserved contact ranges where available.
 Generated identities are pseudonyms; valid arithmetic does not prove non-issuance.
+
+## Document forms reviewed in issues 77–83
+
+Structured JSON/JSONL scans each decoded string at its own line start as well as
+with its field label. This includes array elements, multiline strings and up to
+two embedded JSON container layers. Both the synchronous API and asynchronous
+engine union use these views. Source offsets include original JSON escapes;
+unchanged values and whitespace remain byte-identical. Numeric primitives still
+require a caller schema policy. `debug` can observe `structured-value` events
+with finding counts, without logging the string contents.
+
+The `documents` profile additionally recognizes:
+
+- Russian mobile numbers with dashed, dotted, spaced or parenthesized forms,
+  including ten-digit `9xx` forms and domestic `8` prefixes; `тел.`, `моб.` and
+  WhatsApp labels; `wa.me` contact links.
+- Obfuscated email separators `(at)`, `[at]`, `собака`, and English `dot`/`at`.
+  This is a finite spelling grammar, not arbitrary email deobfuscation.
+- Personal paths on LinkedIn (`/in/`), GitHub, VK, Instagram and Telegram,
+  including scheme-less links; Telegram/телеграм/tg/skype/ник labels without `@`.
+  A provider root such as `https://github.com/` remains unchanged. These rules
+  cannot distinguish a person from an organization account on the same service.
+- Russian passport series/number phrases, ОГРНИП, subdivision codes, dated
+  ОВД/УВД/МВД issuer phrases, Russian/English driving licence labels, ОМС/полис,
+  Russian account numbers and numbered diplomas. These contextual patterns do
+  not validate issuance; digits are protected even with invalid checksums.
+- Numbered schools, gymnasiums, lyceums and colleges; school acronyms after
+  Образование/ВУЗ/Университет/окончил/окончила, with optional `им. Баумана`-style
+  suffixes. Acronym detection is contextual rather than a complete school list.
+- Surname/initial shapes in Cyrillic and selected Latin Slavic forms, known
+  given-name plus initial, Russian surname/given-name pairs using finite case
+  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.
+- 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,
+  employment prose and year-range employer lines; residence/metro/district
+  labels and contextual six-digit postal codes.
+- Russian street-plus-house/flat structures at line start or after
+  `проживает по адресу`. Public-place prose such as
+  `Музей находится на ул. Ленина, д. 5, кв. 12` stays unchanged. Public addresses
+  presented alone have the same shape as personal addresses and may be flagged;
+  inspect and review standalone public addresses before publication.
+
+Explicit limits accepted for the ambiguous examples in #82/#83:
+`Спасибо, Анна!`, `Анна, добрый день!`, `Менеджер Анна` and `Лютик, менеджер`
+remain unchanged without known values or additional context. Bare given names
+and unmarked employer/title fragments cannot reliably establish identity.
+`зарплата 150 000 руб.` and `Salary: 150000` also remain unchanged: salary is
+outside the native document rules. Supply `knownPersonal` or an additional
+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
+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
+and personal paths still redact. Context-free 40-character hexadecimal values
+are treated as SHA-1-shaped identifiers in both text and structured modes,
+including quoted values. This does not prove they are harmless: actual bare
+40-hex secrets require `knownSecrets` or credential context. Credential labels,
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-foundation/sensitive-data-sanitizer",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "Offline sensitive-text sanitization with credential, multilingual personal-data and scanner union detection",
   "type": "module",
   "main": "src/index.js",

package/src/context.js

@@ -228,6 +228,9 @@ function quotedRange(text, start, opening, maxLength) {
 }
 
 function plausibleLabel(value, type) {
+  if (operationalValue(value, type)) {
+    return false;
+  }
   if (type === 'PERSON') {
     return plausiblePerson(value.replace(/[,;\d].*$/s, '').trim());
   }
@@ -240,6 +243,20 @@ function plausibleLabel(value, type) {
   return true;
 }
 
+function operationalValue(value, type) {
+  return (
+    (type === 'URL' &&
+      /^\/(?!\/)[^\s?@#]*$/.test(value) &&
+      !/(?:^|\/)(?:users?|profiles?|people|members?|home)\/[^/]+/i.test(
+        value
+      )) ||
+    (type === 'TIME' &&
+      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(
+        value
+      ))
+  );
+}
+
 // Shared by native labels and the vendor catalogs. Code expressions and
 // line escapes are not personal field values, even when a key is familiar.
 export function personalValueAllowed(text, range, type, labelStart) {

package/src/detection.js

@@ -185,7 +185,9 @@ export function nativeDetect(text, options, emit) {
     emit,
     { ...credential, rule: 'quoted-entropy' },
     1,
-    (value) => entropy(value) >= (/^[a-f0-9]+$/i.test(value) ? 3 : 4.5)
+    (value) =>
+      !/^[a-f0-9]{40}$/i.test(value) &&
+      entropy(value) >= (/^[a-f0-9]+$/i.test(value) ? 3 : 4.5)
   );
   collectMatches(
     text,

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 { detectDocumentPatterns } from './document-patterns.js';
 
 const words = (column) =>
   [...new Set(documentVocabulary.flatMap((row) => row[column].split('|')))]
@@ -87,6 +88,7 @@ export function detectDocumentEntities(text, emit, options) {
   if (!options.documentEntities) {
     return;
   }
+  detectDocumentPatterns(text, emit);
   const found = [];
   const capture = (finding) => {
     found.push(finding);

package/src/document-patterns.js

@@ -0,0 +1,224 @@
+import { firstNames } from './names.js';
+import { isNameForm } from './russian-names.js';
+
+const boundary = '[\\p{L}\\p{N}_]';
+const word = '[А-ЯЁ][а-яё-]{1,47}';
+const surname =
+  '[А-ЯЁа-яё][А-ЯЁа-яё-]{1,28}(?:ов|ев|ин|ын|ск|цк)(?:а|ой|ою|у|ым|ом|е|ы|и|их|ий|ая|ого|ому|ую|ие)?';
+const initials = '(?:[А-ЯЁA-Z]\\.[ \\t]*){1,2}';
+const latinSurname = '[A-Z][a-z]{1,28}(?:ova|eva|ov|ev|in|ina|sky|ski|skaya)';
+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})`,
+  'gu'
+);
+const namePairs = new RegExp(
+  `(?<!${boundary})(${surname})[ \\t]+([А-ЯЁа-яё]{2,32})|(?<!${boundary})([А-ЯЁа-яё]{2,32})[ \\t]+(${surname})(?!${boundary})`,
+  'gu'
+);
+// Every rule is finite and requires either an identifying structure or a label.
+// Public locations/ambiguous bare words are not inferred from arbitrary prose.
+const rules = [
+  [
+    'PHONE',
+    'document-phone',
+    /(?<![\p{L}\p{N}_])(?:[78][ .-]?)?9\d{2}(?:[ .-]\d{3}[ .-]\d{2}[ .-]\d{2})(?!\d)|(?<![\p{L}\p{N}_])8[ .-]?\(9\d{2}\)[ .-]?\d{3}[ .-]?\d{2}[ .-]?\d{2}(?!\d)/gu,
+    0,
+  ],
+  [
+    'PHONE',
+    'document-phone-label',
+    /(?<![\p{L}\p{N}_])(?:тел\.?|моб\.?|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,
+    0,
+  ],
+  [
+    'USERNAME',
+    'personal-profile-url',
+    /(?<![\p{L}\p{N}_./-])(?:https?:\/\/)?(?:www\.)?(?:linkedin\.com\/in|github\.com|vk\.com|instagram\.com|t\.me|wa\.me)\/[\p{L}\p{N}_][\p{L}\p{N}_.-]{1,100}(?:\/[\p{L}\p{N}_.-]{1,100}){0,4}(?![\p{L}\p{N}_])/giu,
+    0,
+  ],
+  [
+    '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,
+    1,
+  ],
+  [
+    'PASSPORT_NUMBER',
+    'passport-series',
+    /(?<![\p{L}\p{N}_])(?:серия|series)[ \t]+(\d{2}[ \t]?\d{2}[ \t]+(?:№|No|номер|number|#)[ \t]*\d{6})(?!\d)/giu,
+    1,
+  ],
+  [
+    '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,
+    -1,
+  ],
+  [
+    'ID',
+    'passport-issuer',
+    /(?<![\p{L}\p{N}_])выдан[ \t]+((?:ОВД|УВД|МВД)[ \t]+[^\r\n";|]{1,120}?\d{2}\.\d{2}\.\d{4})(?!\d)/giu,
+    1,
+  ],
+  [
+    'EDUCATION',
+    'numbered-school',
+    /(?<![\p{L}\p{N}_])(?:школа|гимназия|лицей|колледж)[ \t]*(?:№|No|#|:)[ \t]*\d{1,4}(?!\d)/giu,
+    0,
+  ],
+  [
+    'EDUCATION',
+    'school-acronym-context',
+    /(?<![\p{L}\p{N}_])(?:образование|ВУЗ|университет|окончил[аи]?)(?:[ \t]*:[ \t]*|[ \t]+)([А-ЯЁ]{2,12}(?:[ \t]+им\.[ \t]+[А-ЯЁ][а-яё-]{2,40})?)(?![\p{L}\p{N}_])/giu,
+    1,
+  ],
+  ['PERSON', 'name-initials', nameInitials, 0],
+  [
+    'PERSON',
+    'name-title',
+    new RegExp(
+      `(?<!${boundary})(?:г-жа|господин|госпожа)[ \\t]+(${word})(?!${boundary})`,
+      'gu'
+    ),
+    1,
+  ],
+  [
+    '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,
+    -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,
+    -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,
+    -1,
+  ],
+  [
+    'PERSONAL_ATTRIBUTE',
+    'profile-attribute',
+    /(?<![\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'
+    ),
+    1,
+  ],
+  [
+    'ORGANIZATION',
+    'employer-prose',
+    new RegExp(
+      `(?<!${boundary})(?:компания|работал[аи]?[ \\t]+в|холдинг|[Бб]анк)[ \\t]+(«[^«»\\r\\n]{1,120}»|${word})(?!${boundary})`,
+      'gu'
+    ),
+    1,
+  ],
+  [
+    'ORGANIZATION',
+    'employer-years',
+    new RegExp(
+      `(?:^|\\n)[ \\t]*(?:19|20)\\d{2}[–—-](?:19|20)\\d{2}[ \\t]+(${word})(?!${boundary})`,
+      'gu'
+    ),
+    1,
+  ],
+  [
+    'LOCATION',
+    'residence-prose',
+    new RegExp(
+      `(?<!${boundary})(?:живу[ \\t]+в|из|м\\.|метро|район)[ \\t]+(${word})(?!${boundary})`,
+      'gu'
+    ),
+    1,
+  ],
+  [
+    'LOCATION',
+    'postal-code',
+    /(?<![\p{L}\p{N}_])индекс[ \t]+(\d{6})(?!\d)|(?<!\d)(\d{6})(?=,[ \t]*[А-ЯЁ][а-яё-]{2,47})/gu,
+    -1,
+  ],
+];
+
+export function detectDocumentPatterns(text, emit) {
+  for (const [type, rule, pattern, group] of rules) {
+    for (const match of text.matchAll(pattern)) {
+      const value =
+        group === -1
+          ? match.slice(1).find((part) => part !== undefined)
+          : match[group].trim();
+      if (!documentValueAllowed(rule, value)) {
+        continue;
+      }
+      const start =
+        match.index + (group === 0 ? 0 : match[0].lastIndexOf(value));
+      emit({
+        start,
+        end: start + value.length,
+        type,
+        rule,
+        category: 'personal',
+        confidence: group === -1 ? 0.85 : 0.75,
+      });
+    }
+  }
+  for (const match of text.matchAll(namePairs)) {
+    if (isNameForm(match[2] ?? match[3])) {
+      emit({
+        start: match.index,
+        end: match.index + match[0].length,
+        type: 'PERSON',
+        rule: 'name-case',
+        category: 'personal',
+        confidence: 0.8,
+      });
+    }
+  }
+  // An address at line start or in explicit residence context is personal.
+  // Public-place prose with a street address does not supply that context.
+  const street =
+    /(?:^|\n)[ \t]*((?:ул\.|улица)[ \t]+[А-ЯЁ][а-яё-]{1,40},[ \t]*(?:(?:д\.|дом)[ \t]*)?\d{1,5}(?:[ \t]*,[ \t]*кв\.[ \t]*\d{1,5})?)|проживает по адресу[ \t]+((?:ул\.|улица)[ \t]+[А-ЯЁ][а-яё-]{1,40},[ \t]*(?:(?:д\.|дом)[ \t]*)?\d{1,5}(?:[ \t]*,[ \t]*кв\.[ \t]*\d{1,5})?)/gu;
+  for (const match of text.matchAll(street)) {
+    const value = match[1] ?? match[2];
+    const start = match.index + match[0].lastIndexOf(value);
+    emit({
+      start,
+      end: start + value.length,
+      type: 'ADDRESS',
+      rule: 'document-street',
+      category: 'personal',
+      confidence: 0.85,
+    });
+  }
+}
+
+function documentValueAllowed(rule, value) {
+  return (
+    Boolean(value) &&
+    value !== '[REDACTED]' &&
+    !(
+      rule === 'school-acronym-context' &&
+      !/^[А-ЯЁ]{2,12}(?![А-ЯЁа-яё])/.test(value)
+    ) &&
+    !(rule === 'messenger-label' && /^(?:недоступен|unavailable)$/i.test(value))
+  );
+}

package/src/engines.js

@@ -24,6 +24,7 @@ import {
 } from './placeholders.js';
 import {
   structuredBatches,
+  structuredValueViews,
   mapStructuredFindings,
   verifyStructured,
 } from './structured.js';
@@ -143,6 +144,21 @@ async function analyzeStructured(
     )) {
       findings.push(finding);
     }
+    for (const view of structuredValueViews(batch, options)) {
+      const detected = await analyze(
+        view.text,
+        [],
+        true,
+        { ...options, structured: undefined },
+        nativeFindings === undefined ? undefined : []
+      );
+      for (const finding of detected) {
+        const mapped = view.map(finding);
+        if (mapped) {
+          findings.push(mapped);
+        }
+      }
+    }
   }
   // Native structured inspection validates, locates and reapplies the
   // same fake-value/public policy to source offsets from all engines.

package/src/sanitizer.js

@@ -31,6 +31,7 @@ import {
 } from './placeholders.js';
 import {
   structuredBatches,
+  inspectStructuredValues,
   mapStructuredFindings,
   preserveIdentifierKeys,
   structuredValueRanges,
@@ -392,8 +393,8 @@ function inspectText(text, options = {}) {
   validateOptions(options);
   validateInput(text, options);
   if (options.structured) {
-    const findings = structuredBatches(text, options).flatMap((batch) =>
-      mapStructuredFindings(
+    const findings = structuredBatches(text, options).flatMap((batch) => [
+      ...mapStructuredFindings(
         batch,
         inspect(batch.text, {
           ...options,
@@ -401,8 +402,11 @@ function inspectText(text, options = {}) {
           findings: [],
         }),
         options
-      )
-    );
+      ),
+      ...inspectStructuredValues(batch, options, (value) =>
+        inspect(value, { ...options, structured: undefined, findings: [] })
+      ),
+    ]);
     return inspectFindingsOnly(text, findings, options);
   }
   const findings = [];

package/src/structured.js

@@ -280,3 +280,87 @@ export function verifyStructured(text, options) {
     }
   }
 }
+
+// Scan decoded strings at their own line start, retaining a map through every
+// JSON escape. Both native and asynchronous engines consume these same views.
+export function* structuredValueViews(
+  batch,
+  options,
+  depth = 0,
+  outerMap = (f) => f
+) {
+  for (const entry of batch.entries) {
+    const value = JSON.parse(entry.raw);
+    const offsets = stringOffsets(entry.raw);
+    const map = (finding) => {
+      const raw = {
+        ...finding,
+        start: offsets ? offsets.starts[finding.start] : finding.start + 1,
+        end: offsets ? offsets.ends[finding.end - 1] : finding.end + 1,
+      };
+      if (
+        preserveStructuredEntry(
+          entry,
+          {
+            ...raw,
+            start: entry.batchStart + raw.start,
+            end: entry.batchStart + raw.end,
+          },
+          batch.text,
+          options
+        )
+      ) {
+        return undefined;
+      }
+      return outerMap({
+        ...raw,
+        start: entry.start + raw.start,
+        end: entry.start + raw.end,
+      });
+    };
+    yield { text: value, map };
+    // Match the encoded detector's finite depth; arbitrary nesting is a limit.
+    if (depth < 2 && /^[ \t\r\n]*[[{]/.test(value)) {
+      let batches;
+      try {
+        batches = structuredBatches(value, { ...options, structured: 'json' });
+      } catch (error) {
+        if (error.code !== 'ERR_JSON') {
+          throw error;
+        }
+        batches = [];
+      }
+      for (const nested of batches) {
+        yield* structuredValueViews(nested, options, depth + 1, map);
+      }
+    }
+  }
+}
+export function inspectStructuredValues(batch, options, inspectValue) {
+  const result = [];
+  for (const view of structuredValueViews(batch, options)) {
+    const findings = inspectValue(view.text);
+    options.debug?.({ event: 'structured-value', count: findings.length });
+    for (const finding of findings) {
+      const mapped = view.map(finding);
+      if (mapped) {
+        result.push(mapped);
+      }
+    }
+  }
+  return result;
+}
+function stringOffsets(raw) {
+  if (!raw.includes('\\')) {
+    return undefined;
+  }
+  const starts = [],
+    ends = [];
+  for (let i = 1; i < raw.length - 1; ) {
+    const start = i;
+    i += raw[i] === '\\' ? (raw[i + 1] === 'u' ? 6 : 2) : 1;
+    starts.push(start);
+    ends.push(i);
+  }
+  return { starts, ends };
+}