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

package/src/context.js

@@ -8,6 +8,7 @@ import { plausiblePerson } from './names.js';
 // unrelated words such as passport. Verb forms cover the supported locales.
 export const credentialVerbs = [
   'is',
+  'are',
   'was',
   'equals',
   'es',
@@ -45,12 +46,11 @@ export const credentialVerbs = [
   'คือ',
 ];
 const verbs = credentialVerbs.map(escapePattern).join('|');
-const key = `(?:[\\p{L}\\p{N}]+[_.-])*(?:auth|authorization)(?:[_.-][\\p{L}\\p{N}]+)*|[\\p{L}\\p{N}_.-]{0,32}(?:${labels.credential
+const label = labels.credential
   .filter((word) => !['auth', 'authorization'].includes(word))
   .map(escapePattern)
-  .join(
-    '|'
-  )})[\\p{L}\\p{N}_.-]{0,32}|(?:[\\p{L}\\p{N}_.-]{1,32}[_-])?(?:pass|pw)(?:[_-][\\p{L}\\p{N}_.-]{1,32})?`;
+  .join('|');
+const key = `(?:[\\p{L}\\p{N}]+[_.-])*(?:auth|authorization|PGPASSWORD|${label}|pass|pw)(?:[_.-][\\p{L}\\p{N}]+)*`;
 // A qualifier such as "for staging" stays on one logical line: it never
 // crosses an escaped line break, an escape sequence or an enclosing quote.
 // Verbs are whole words, so "request" does not end in the verb "est".
@@ -60,8 +60,6 @@ const credentialPrefix = new RegExp(
 );
 // Bare generic labels are common English nouns. After a verb they need a
 // value that looks generated; "the token is valid" is prose, not a secret.
-const genericLabel =
-  /^(?:token|sig|sas|secret|auth|authorization|cookie|секрет|токен)$/iu;
 function generatedWord(text, range) {
   const word = /^[^\s]+/u
     .exec(text.slice(range.start, range.end))?.[0]
@@ -170,7 +168,7 @@ export function authorizationRange(text, start) {
   for (; end < text.length; end++) {
     const char = text[end];
     const code = text.charCodeAt(end);
-    if (code < 32 || code === 127 || /[\s"'\\,]/.test(char)) {
+    if (authorizationDelimiter(char, code)) {
       break;
     }
     if (char === '<' && end !== tokenStart && !brackets.length) {
@@ -185,7 +183,13 @@ export function authorizationRange(text, start) {
     }
   }
   const token = text.slice(tokenStart, end);
-  return !token || credentialPlaceholder(token) ? undefined : { start, end };
+  return usableAuthorization(token) ? { start, end } : undefined;
+}
+function usableAuthorization(token) {
+  return Boolean(token) && !credentialPlaceholder(token);
+}
+function authorizationDelimiter(char, code) {
+  return code < 32 || code === 127 || /[\s"'\\,]/.test(char);
 }
 function quotedRange(text, start, opening, maxLength) {
   const depth = opening[1].length,
@@ -323,6 +327,13 @@ function backslashes(text, index) {
   return count;
 }
 
+function sourceReference(label, tail) {
+  return (
+    /\.(?:[cm]?[jt]sx?|py|go|rs|c|cpp|h|java|cs|rb|sh)$/iu.test(label) &&
+    /^\d+(?:[):]|\b)/u.test(tail)
+  );
+}
+
 function detectCredentials(text, emit) {
   const details = { category: 'credential', type: 'SECRET', rule: 'context' };
   for (const match of text.matchAll(credentialPrefix)) {
@@ -341,9 +352,12 @@ function detectCredentials(text, emit) {
     let range = /^(?:proxy-)?authorization$/i.test(match[1])
       ? authorizationRange(text, start)
       : valueRange(text, start, mode);
-    if (range && mode === 'prose' && genericLabel.test(match[1])) {
+    if (range && mode === 'prose') {
       range = generatedWord(text, range);
     }
+    if (sourceReference(match[1], text.slice(start))) {
+      continue;
+    }
     if (range) {
       emitValue(text, range.start, range.end, emit, details, match[1]);
     }

package/src/detection.js

@@ -13,6 +13,8 @@ import {
   credentialPlaceholder,
 } from './credentials.js';
 import { localAddress } from './public.js';
+import { detectKnownPersonal } from './personal-variants.js';
+import { detectDocumentEntities } from './document-entities.js';
 
 export const REDACTED = '[REDACTED]';
 export const failure = (code = 'ERR_SANITIZATION', location = {}) =>
@@ -132,6 +134,29 @@ function detectCookies(text, emit) {
 
 export function nativeDetect(text, options, emit) {
   const credential = { type: 'SECRET', category: 'credential' };
+  for (const value of options.knownSecrets ?? []) {
+    collectMatches(text, new RegExp(escapePattern(value), 'g'), emit, {
+      ...credential,
+      rule: 'known-secret',
+    });
+  }
+  detectKnownPersonal(
+    text,
+    options.knownPersonal,
+    'known-personal',
+    emit,
+    options
+  );
+  detectKnownPersonal(
+    text,
+    options.confirmedPersonal,
+    'confirmed-personal',
+    emit,
+    options
+  );
+  if (options.knownOnly) {
+    return;
+  }
   detectGitleaks(
     text,
     emit,
@@ -142,34 +167,10 @@ export function nativeDetect(text, options, emit) {
   for (const [rule, pattern] of serviceRules) {
     collectMatches(text, pattern, emit, { ...credential, rule });
   }
-  for (const value of options.knownSecrets ?? []) {
-    collectMatches(text, new RegExp(escapePattern(value), 'g'), emit, {
-      ...credential,
-      rule: 'known-secret',
-    });
-  }
-  for (const entry of options.knownPersonal ?? []) {
-    collectMatches(text, new RegExp(escapePattern(entry.value), 'giu'), emit, {
-      type: entry.type,
-      category: 'personal',
-      rule: 'known-personal',
-    });
-  }
-  for (const entry of options.confirmedPersonal ?? []) {
-    const pattern = new RegExp(
-      `(?<![\\p{L}\\p{N}])${personalPattern(entry.value)}(?![\\p{L}\\p{N}])`,
-      'giu'
-    );
-    collectMatches(text, pattern, emit, {
-      type: entry.type,
-      category: 'personal',
-      rule: 'confirmed-personal',
-      confidence: 0.9,
-    });
-  }
   detectContext(text, emit, options.credentialsOnly);
   if (!options.credentialsOnly) {
     detectPersonal(text, emit);
+    detectDocumentEntities(text, emit, options);
     detectCatalog(text, emit);
     detectIdentity(text, emit);
     detectNational(text, emit);

package/src/document-entities.js

@@ -0,0 +1,110 @@
+import { collectMatches, escapePattern } from './detection.js';
+import { firstNames } from './names.js';
+import { organizationCore, personalRegex } from './personal-variants.js';
+import { documentVocabulary } from './document-vocabulary.js';
+
+const words = (column) =>
+  [...new Set(documentVocabulary.flatMap((row) => row[column].split('|')))]
+    .sort((a, b) => b.length - a.length)
+    .map(escapePattern)
+    .join('|');
+const legal = words(1),
+  school = words(2);
+const proper = "[\\p{Lu}][\\p{L}\\p{M}’'&.-]{1,47}";
+const latinName = `${proper}(?:[ \\t]+${proper}){0,5}`;
+// Scripts without letter case need a bounded script-specific name instead.
+const uncased =
+  '[\\p{Script=Han}\\p{Script=Hiragana}\\p{Script=Katakana}\\p{Script=Hangul}\\p{Script=Arabic}\\p{Script=Hebrew}\\p{Script=Devanagari}\\p{Script=Thai}\\p{M}]{2,48}';
+const name = `(?:${latinName}|${uncased}(?:[ \\t]+${uncased}){0,3})`;
+const quoted = `(?:«[^«»\\r\\n]{1,160}»|“[^“”\\r\\n]{1,160}”|"[^"\\r\\n]{1,160}"|「[^「」\\r\\n]{1,160}」|『[^『』\\r\\n]{1,160}』|${name})`;
+const boundary = '[\\p{L}\\p{M}\\p{N}_]';
+const organizations = new RegExp(
+  `(?<!${boundary})(?:(?:${legal})[ \\t]*${quoted}|${quoted}[ \\t]*(?:${legal}))(?!${boundary})`,
+  'gu'
+);
+const schools = new RegExp(
+  `(?<!${boundary})(?:(?:${school})[ \\t]*${quoted}|${quoted}[ \\t]*(?:${school}))(?!${boundary})`,
+  'gu'
+);
+const places = new RegExp(
+  `(?<!${boundary})(?:${words(3)})(?!${boundary})`,
+  'gu'
+);
+const labelledPlace = new RegExp(
+  `(?<!${boundary})(?:[Bb]ased in|[Ll]ocated in|[Rr]elocated from|город|г\\.|местоположение|ubicado en|situé à|ansässig in|localizado em|所在地|位于|位於|위치|يقيم في|ממוקם ב|स्थित|merkezi|berlokasi di|đặt tại|ตั้งอยู่ที่)[ \\t]+(${name})(?!${boundary})`,
+  'gu'
+);
+
+const ruWord = '[А-ЯЁа-яё][А-ЯЁа-яё-]{1,47}';
+const ruSchool = new RegExp(
+  `(?<!${boundary})[А-ЯЁ][а-яё]{2,30}(?:-[А-ЯЁа-яё][а-яё]{1,30})?(?:[ \t]+[а-яё-]{2,40}){0,4}[ \t]+(?:университет|институт|колледж|школа|академия)(?:[ \t]+имени[ \t]+${ruWord}(?:[ \t]+[А-ЯЁ][а-яё-]{2,40}){0,2})?(?!${boundary})`,
+  'gu'
+);
+const ruAcronym =
+  /(?<![\p{L}\p{N}_])(?:НИУ[ \t]+[А-ЯЁ]{2,12}|(?:МГУ|СПбГУ|МГТУ|РГГУ|ВШЭ)(?=[, \t]+(?:магистратура|бакалавриат|университет|обучение)))(?![\p{L}\p{N}_])/gu;
+const ruResidence =
+  /(?:[Гг]ород|[Пп]роживаю|[Пп]роживание|[Мм]есто жительства)[ \t]*:[ \t]*([А-ЯЁ][а-яё-]{2,47})|([А-ЯЁ][а-яё-]{2,47})(?=,[ \t]*(?:готов[а]?[ \t]+к[ \t]+переезду|Россия|Беларусь|Казахстан|Украина))/gu;
+const ruIntroduction = new RegExp(
+  `(?:[Мм]еня зовут|[Сс] уважением)[, \t]+(${firstNames.ru.split(' ').join('|')})(?!${boundary})`,
+  'gu'
+);
+const groupOrganization = new RegExp(
+  `(?<!${boundary})${latinName}[ \t]+(?:Групп|Group|Холдинг|Holding)(?!${boundary})`,
+  'gu'
+);
+
+export function detectDocumentEntities(text, emit, options) {
+  if (!options.documentEntities) {
+    return;
+  }
+  const found = [];
+  const capture = (finding) => {
+    found.push(finding);
+    emit(finding);
+  };
+  for (const [type, rule, pattern, group, confidence] of [
+    ['ORGANIZATION', 'organization-group', groupOrganization, 0, 0.7],
+    ['EDUCATION', 'education-russian', ruSchool, 0, 0.65],
+    ['EDUCATION', 'education-acronym', ruAcronym, 0, 0.65],
+    ['PERSON', 'document-introduction', ruIntroduction, 1, 0.7],
+    ['ORGANIZATION', 'organization-legal-form', organizations, 0, 0.7],
+    ['EDUCATION', 'education-type', schools, 0, 0.65],
+    ['LOCATION', 'location-gazetteer', places, 0, 0.6],
+    ['LOCATION', 'location-label', labelledPlace, 1, 0.75],
+  ]) {
+    collectMatches(
+      text,
+      pattern,
+      capture,
+      { type, rule, category: 'personal', confidence },
+      group
+    );
+  }
+  for (const match of text.matchAll(ruResidence)) {
+    const value = match[1] ?? match[2];
+    const start = match.index + match[0].lastIndexOf(value);
+    emit({
+      start,
+      end: start + value.length,
+      type: 'LOCATION',
+      rule: 'location-residence',
+      category: 'personal',
+      confidence: 0.75,
+    });
+  }
+  // Organization cores are confirmed only by a bounded legal-form finding.
+  for (const finding of found.filter((f) => f.type === 'ORGANIZATION')) {
+    const core = organizationCore(text.slice(finding.start, finding.end));
+    if (core.length < 3 || core.length > 256) {
+      continue;
+    }
+    for (const match of text.matchAll(personalRegex(core, 'ORGANIZATION'))) {
+      emit({
+        ...finding,
+        start: match.index,
+        end: match.index + match[0].length,
+        rule: 'organization-core',
+      });
+    }
+  }
+}

package/src/document-vocabulary.js

@@ -0,0 +1,71 @@
+// Authored, deliberately finite vocabulary; no network or model downloads.
+// Each row follows localeVocabulary: locale, legal forms, school types, places.
+export const documentVocabulary = [
+  [
+    'en',
+    'Inc|LLC|Ltd|PLC|Corporation',
+    'University|College|Institute|School',
+    'Springfield|Riverton|London|New York|California',
+  ],
+  [
+    'es',
+    'S.A.|S.L.|S.L.U.',
+    'Universidad|Colegio|Instituto|Escuela',
+    'Madrid|Barcelona|Andalucía',
+  ],
+  [
+    'fr',
+    'SARL|SAS|SA|S.A.',
+    'Université|Collège|Institut|École',
+    'Paris|Lyon|Bretagne',
+  ],
+  [
+    'de',
+    'GmbH|AG|KG|UG',
+    'Universität|Hochschule|Institut|Schule',
+    'Berlin|München|Bayern',
+  ],
+  [
+    'pt',
+    'Ltda|S.A.|Unipessoal',
+    'Universidade|Faculdade|Instituto|Escola',
+    'Lisboa|São Paulo|Algarve',
+  ],
+  [
+    'ru',
+    'ООО|АО|ПАО|ИП|ЗАО',
+    'Университет|университет|Институт|институт|Школа|школа',
+    'Москва|Санкт-Петербург|Казань|Татарстан|Ярославль|Кострома|Новосибирск|Екатеринбург|Нижний Новгород|Самара|Омск|Челябинск|Ростов-на-Дону|Уфа|Красноярск|Пермь|Воронеж|Волгоград|Саратов|Тюмень|Тольятти|Ижевск|Барнаул|Иркутск|Хабаровск|Владивосток|Махачкала|Томск|Оренбург|Кемерово|Рязань|Астрахань|Пенза|Липецк|Киров|Чебоксары|Тула|Калининград|Курск|Улан-Удэ|Ставрополь|Сочи|Тверь|Брянск|Белгород|Владимир|Архангельск|Калуга|Смоленск|Вологда|Саранск|Орёл',
+  ],
+  ['ja', '株式会社|有限会社|合同会社', '大学|学院|学校', '東京|大阪|北海道'],
+  ['zh', '有限公司|股份有限公司', '大学|学院|学校', '北京|上海|广东'],
+  ['zh-Hant', '有限公司|股份有限公司', '大學|學院|學校', '臺北|台北|高雄|臺灣'],
+  ['ko', '주식회사|유한회사', '대학교|대학|학교', '서울|부산|경기도'],
+  ['ar', 'ذ.م.م|شركة', 'جامعة|معهد|مدرسة', 'القاهرة|دبي|الرياض'],
+  [
+    'he',
+    'בע״מ|בע"מ|חברה',
+    'אוניברסיטת|אוניברסיטה|מכללת|מכון',
+    'ירושלים|תל אביב|חיפה',
+  ],
+  [
+    'hi',
+    'प्राइवेट लिमिटेड|लिमिटेड',
+    'विश्वविद्यालय|महाविद्यालय|संस्थान',
+    'दिल्ली|मुंबई|महाराष्ट्र',
+  ],
+  [
+    'tr',
+    'A.Ş.|Ltd. Şti.',
+    'Üniversitesi|Üniversite|Enstitüsü|Okulu',
+    'İstanbul|Ankara|İzmir',
+  ],
+  ['id', 'PT|CV|Tbk', 'Universitas|Institut|Sekolah', 'Jakarta|Bandung|Bali'],
+  ['vi', 'TNHH|CTCP', 'Đại học|Trường|Học viện', 'Hà Nội|Hồ Chí Minh|Đà Nẵng'],
+  [
+    'th',
+    'บริษัท|จำกัด',
+    'มหาวิทยาลัย|วิทยาลัย|โรงเรียน',
+    'กรุงเทพมหานคร|เชียงใหม่|ภูเก็ต',
+  ],
+];

package/src/engines.js

@@ -16,6 +16,12 @@ import {
 import { failure, internalFailure } from './detection.js';
 import { projectText } from './projection.js';
 import { decodedRuns } from './encoded.js';
+import {
+  initializePlaceholders,
+  placeholderKnown,
+  hasPlaceholders,
+  discardPlaceholderState,
+} from './placeholders.js';
 import {
   structuredBatches,
   mapStructuredFindings,
@@ -149,14 +155,19 @@ async function analyzeStructured(
 export function createSanitizer(options = {}) {
   options = applyProfile(options);
   validateOptions(options);
+  options = initializePlaceholders(options);
   for (const detector of options.detectors ?? []) {
     if (!detector || typeof detector.detect !== 'function') {
       throw failure('ERR_CONFIG');
     }
   }
   const engines =
-    options.secretlint === false ? [] : [{ detect: secretlintDetect }];
-  engines.push(...(options.detectors ?? []));
+    options.secretlint === false || options.knownOnly
+      ? []
+      : [{ detect: secretlintDetect }];
+  if (!options.knownOnly) {
+    engines.push(...(options.detectors ?? []));
+  }
   let prepared;
   async function analyze(
     text,
@@ -165,7 +176,7 @@ export function createSanitizer(options = {}) {
     scopedOptions = options,
     nativeFindings
   ) {
-    const options = scopedOptions;
+    const options = placeholderKnown(scopedOptions);
     validateInput(text, options);
     if (options.structured && !plain) {
       return analyzeStructured(text, initial, options, nativeFindings, analyze);
@@ -203,20 +214,8 @@ export function createSanitizer(options = {}) {
   }
 
   const sanitizer = {
-    inspect: async (...args) => {
-      try {
-        return await analyze(...args);
-      } catch (error) {
-        throw internalFailure(error);
-      }
-    },
-    sanitize: async (...args) => {
-      try {
-        return await sanitizeText(...args);
-      } catch (error) {
-        throw internalFailure(error);
-      }
-    },
+    inspect: guarded(analyze),
+    sanitize: guarded(sanitizeText, () => discardPlaceholderState(options)),
     sanitizeJsonl: (text) =>
       createSanitizer({ ...options, structured: 'jsonl' }).sanitize(text),
   };
@@ -297,15 +296,40 @@ export function createSanitizer(options = {}) {
     if (options.structured && !plain) {
       verifyStructured(result.text, options);
     }
+    if (await placeholderResidual(result.text, options, plain, analyze)) {
+      throw failure('ERR_RESIDUAL');
+    }
     return { ...result, findings: auditFaked(findings, options, result) };
   }
 }
 
+function guarded(callback, cleanup = () => {}) {
+  return async (...args) => {
+    try {
+      return await callback(...args);
+    } catch (error) {
+      throw internalFailure(error);
+    } finally {
+      cleanup();
+    }
+  };
+}
+async function placeholderResidual(text, options, plain, analyze) {
+  return (
+    hasPlaceholders(options) &&
+    (await analyze(text, [], plain, options)).some((f) =>
+      actionable(f, options)
+    )
+  );
+}
+
 function eligiblePublic(text, finding, findings) {
   return (
     finding.category !== 'credential' &&
     !['known-personal', 'confirmed-personal'].includes(finding.rule) &&
-    ['PERSON', 'ORGANIZATION', 'EMAIL'].includes(finding.type) &&
+    ['PERSON', 'ORGANIZATION', 'EDUCATION', 'LOCATION', 'EMAIL'].includes(
+      finding.type
+    ) &&
     !findings.some(
       (f) =>
         (f.category === 'credential' ||

package/src/entities.js

@@ -36,6 +36,13 @@ for (const [vendor, catalog] of Object.entries(entityCatalogs)) {
     entries.set(name.toUpperCase(), entry);
   }
 }
+export const catalogTypes = () => [
+  ...new Set(
+    [...entries.values()]
+      .filter((entry) => entry.category === 'personal')
+      .map((entry) => (entry.type === 'DATE_OF_BIRTH' ? 'DATE' : entry.type))
+  ),
+];
 // All documented names are native labelled recognizers; automatic format
 // recognizers are separate and do not claim the vendors' model behavior.
 const prefix = new RegExp(

package/src/fake-names.js

@@ -146,6 +146,58 @@ function scriptLocale(value) {
 }
 export function fakeName(value, key) {
   indexNames();
+  const words = value.match(/[\p{L}\p{M}]+/gu) ?? [];
+  const roles = new Map();
+  let nameSex;
+  if (
+    /\p{Script=Cyrillic}/u.test(value) &&
+    words.length >= 2 &&
+    words.length <= 3
+  ) {
+    const middle = words.findIndex((w) =>
+      /(?:ович|евич|ична|овна|евна)$/iu.test(w)
+    );
+    const surname = words.findIndex(
+      (w, i) =>
+        i !== middle &&
+        /(?:ов|ев|ин|ский|ова|ева|ина|ская)$/iu.test(w) &&
+        !given.has(latinName(w))
+    );
+    const genderWord = words[middle >= 0 ? middle : surname];
+    if (genderWord) {
+      nameSex = /(?:ова|ева|ина|ская|овна|евна|ична)$/iu.test(genderWord)
+        ? 'female'
+        : 'male';
+    }
+    if (middle > 0) {
+      words.forEach((w, i) =>
+        roles.set(
+          w,
+          i === middle
+            ? 'middleName'
+            : i === middle - 1
+              ? 'firstName'
+              : 'lastName'
+        )
+      );
+    } else if (surname >= 0) {
+      words.forEach((w, i) =>
+        roles.set(w, i === surname ? 'lastName' : 'firstName')
+      );
+    } else {
+      // Ambiguous spans receive a complete name with the same token count.
+      words.forEach((w, i) =>
+        roles.set(
+          w,
+          i === 0
+            ? 'firstName'
+            : i === words.length - 1
+              ? 'lastName'
+              : 'middleName'
+        )
+      );
+    }
+  }
   return value.replace(/[\p{L}\p{M}]+/gu, (word) => {
     for (const locale of ['ja', 'zh', 'ko']) {
       const family = firstNames[locale]
@@ -158,7 +210,7 @@ export function fakeName(value, key) {
         );
       }
     }
-    return fakeWord(word, key);
+    return fakeWord(word, key, roles.get(word), undefined, nameSex);
   });
 }
 function wordProfile(word, forcedRole, forcedLocale) {
@@ -188,12 +240,14 @@ function wordProfile(word, forcedRole, forcedLocale) {
         : 'lastName');
   return { canonical, locale, sex, role };
 }
-function fakeWord(word, key, forcedRole, forcedLocale) {
-  const { canonical, locale, sex, role } = wordProfile(
-    word,
-    forcedRole,
-    forcedLocale
-  );
+function fakeWord(word, key, forcedRole, forcedLocale, forcedSex) {
+  const {
+    canonical,
+    locale,
+    sex: detectedSex,
+    role,
+  } = wordProfile(word, forcedRole, forcedLocale);
+  const sex = forcedSex ?? detectedSex;
   const faker = new Faker({ locale: [locales[locale] ?? en, en] });
   faker.seed(
     createHmac('sha256', key)

package/src/fake.js

@@ -501,6 +501,13 @@ export function realisticFake(value, finding, transform) {
       .slice(0, 8)}!`;
   } else if (finding.type === 'PERSON') {
     output = fakeName(value, transform.key);
+  } else if (['ORGANIZATION', 'EDUCATION', 'LOCATION'].includes(finding.type)) {
+    const label = {
+      ORGANIZATION: 'Organization',
+      EDUCATION: 'School',
+      LOCATION: 'Location',
+    }[finding.type];
+    output = `Example ${label} ${digest(value, transform.key, finding.type).readUInt32BE(0)}`;
   } else if (/DATE|BIRTH/.test(finding.type)) {
     output = fakeDate(value, transform.key);
   } else if (finding.type === 'PASSPORT_MRZ') {

package/src/index.d.ts

@@ -27,7 +27,7 @@ export interface PersonalValue {
   value: string;
 }
 export interface PublicEntity {
-  type: 'PERSON' | 'ORGANIZATION' | 'EMAIL';
+  type: 'PERSON' | 'ORGANIZATION' | 'EDUCATION' | 'LOCATION' | 'EMAIL';
   value: string;
   /** Organization-controlled HTTPS evidence, reviewed by the policy author. */
   source: string;
@@ -42,7 +42,11 @@ export interface Detector {
 export interface SanitizerOptions {
   /** Preserve all personal/account data; credential findings still redact. */
   credentialsOnly?: boolean;
-  profile?: 'publication';
+  /** Replace only knownPersonal/knownSecrets and reused map values; skip automatic detectors. */
+  knownOnly?: boolean;
+  profile?: 'publication' | 'documents';
+  /** Opt in to bounded employer, school, city/region heuristics. */
+  documentEntities?: boolean;
   confirmedPersonal?: Array<{ value: string; type: string }>;
   knownSecrets?: string[];
   knownPersonal?: PersonalValue[];
@@ -95,6 +99,10 @@ export interface SanitizedText {
   findings: Finding[];
   /** Number of disjoint replacements after overlapping detections are merged. */
   redactions: number;
+  /** Placeholder-mode replacements absent from the restore map (e.g. credentials). */
+  irreversibleRedactions?: number;
+  /** Private personal data. Absent for map:false and non-placeholder modes. */
+  map?: RestoreMap;
 }
 export interface Sanitizer {
   inspect(text: string): Promise<Finding[]>;
@@ -220,6 +228,12 @@ export declare function auditGitHistory(
 ): Promise<HistoryAudit>;
 export type Transformation =
   | { mode: 'redact' | 'hive-mask' }
+  | {
+      mode: 'placeholder';
+      map?: RestoreMap | false;
+      format?: string;
+      credentials?: boolean;
+    }
   | {
       mode: 'mask';
       keepStart?: number;
@@ -239,6 +253,45 @@ export type Transformation =
     }
   | { mode: 'date-shift'; days: number }
   | { mode: 'bucket'; size: number };
+
+/** Contains original personal data; never publish this object or its files. */
+export interface RestoreMap {
+  kind: 'sensitive-data-restore-map';
+  version: 1;
+  format: string;
+  entries: Array<{
+    token: string;
+    type: string;
+    number: number;
+    values: string[];
+    aliases: string[];
+  }>;
+  documents: Array<{
+    digest: string;
+    occurrences: Array<{
+      start: number;
+      end: number;
+      token: string;
+      raw: string;
+    }>;
+  }>;
+}
+export declare function createRestoreMap(options?: {
+  format?: string;
+}): RestoreMap;
+export declare function serializeRestoreMap(
+  map: RestoreMap,
+  format?: 'json' | 'lino'
+): string;
+export declare function parseRestoreMap(text: string): RestoreMap;
+export declare function readRestoreMap(path: string): Promise<RestoreMap>;
+export declare function writeRestoreMap(
+  path: string,
+  map: RestoreMap,
+  options?: { format?: 'json' | 'lino'; replace?: boolean }
+): Promise<void>;
+/** Exact original-document restoration; derived text uses canonical surfaces. */
+export declare function restore(text: string, map: RestoreMap): string;
 export interface StreamOptions extends SanitizerOptions {
   /** Treat NUL as a log byte; default false. Incompatible with JSON/JSONL. */
   allowBinary?: boolean;

package/src/index.js

@@ -38,3 +38,11 @@ export { knownSecretsFromGitHubAuth } from './known.js';
 export { knownSecretsFromGitHubConfig } from './known.js';
 export { decodeLogBytes, encodeLogText } from './log-bytes.js';
 export { rewriteGitHistory } from './history-rewrite.js';
+export {
+  restore,
+  createRestoreMap,
+  serializeRestoreMap,
+  parseRestoreMap,
+  readRestoreMap,
+  writeRestoreMap,
+} from './restore-map.js';