@link-foundation/sensitive-data-sanitizer 0.20.0 → 0.21.1

package/src/features.js

@@ -0,0 +1,29 @@
+// Personal-data features that the main entry registers through
+// `personal-features.js`. The `./credentials` entry never imports that module,
+// so it does not load the personal detectors, faker or libphonenumber
+// (issue 137). This module must stay free of imports.
+const registered = {};
+
+export function registerFeatures(entries) {
+  Object.assign(registered, entries);
+}
+
+/** Runs the registered implementation, or returns `fallback` without one. */
+export function withFeature(name, fallback, ...args) {
+  const value = registered[name];
+  return value ? value(...args) : fallback;
+}
+
+/** The registered implementation; fails closed when it is unavailable. */
+export function feature(name) {
+  const value = registered[name];
+  if (!value) {
+    throw Object.assign(
+      new Error(
+        'This option needs the personal-data modules of the main entry.'
+      ),
+      { code: 'ERR_CONFIG' }
+    );
+  }
+  return value;
+}

package/src/html-tags.js

@@ -0,0 +1,8 @@
+// HTML formatting tags split tokens (`SECRET_</span><span>REST`). Inline tags
+// are dropped and block tags become line breaks. Only presentation attributes
+// are allowed, so other attribute values (URLs, data-*) stay in the view.
+export const inlineTags =
+  'abbr|b|cite|code|del|em|font|i|ins|kbd|mark|q|s|samp|small|span|strong|sub|sup|tt|u|var';
+const blockTags =
+  'blockquote|br|dd|div|dt|h[1-6]|hr|li|ol|p|pre|table|tbody|td|th|thead|tr|ul';
+export const htmlTag = String.raw`<\/?(?:${inlineTags}|${blockTags})(?:\s+(?:class|dir|lang|style)="[^"<>=]*")*\s*\/?>`;

package/src/identity-types.js

@@ -0,0 +1,63 @@
+// Identity-document finding types, shared by the transforms and the
+// identity detectors without loading the detectors themselves.
+export const identityTypes = new Set([
+  'SSN',
+  'US_SSN',
+  'BRAZIL_CPF_NUMBER',
+  'INDIA_PAN_INDIVIDUAL',
+  'UK_NATIONAL_INSURANCE_NUMBER',
+  'SPAIN_DNI_NUMBER',
+  'US_HEALTHCARE_NPI',
+  'DRIVER_LICENSE',
+  'DRIVERS_LICENSE',
+  'NATIONAL_ID',
+  'CHINA_RESIDENT_ID_NUMBER',
+  'HONG_KONG_ID_NUMBER',
+  'SOUTH_AFRICA_ID_NUMBER',
+  'TAIWAN_ID_NUMBER',
+  'TURKEY_ID_NUMBER',
+  'GOVERNMENT_ID',
+  'DOD_ID_NUMBER',
+  'JAPAN_INDIVIDUAL_NUMBER',
+  'INDIA_GST_INDIVIDUAL',
+  'US_MEDICARE_BENEFICIARY_ID_NUMBER',
+  'ID',
+  'PASSPORT_NUMBER',
+  'PASSPORT_MRZ',
+  'BOOKING_REFERENCE',
+  'TICKET_NUMBER',
+  'VISA_NUMBER',
+  'UK_NHS',
+  'KR_RRN',
+  'IT_FISCAL_CODE',
+  'SG_NRIC_FIN',
+  'PL_PESEL',
+  'SE_PERSONNUMMER',
+  'ZA_ID_NUMBER',
+  'AU_TFN',
+  'CA_SIN',
+  'RU_SNILS',
+  'RU_INN',
+  'US_ITIN',
+  'US_DRIVER_LICENSE',
+  'UK_DRIVING_LICENCE',
+  'ES_NIE',
+  'IN_AADHAAR',
+  'IN_VOTER',
+  'IN_PASSPORT',
+  'FI_PERSONAL_IDENTITY_CODE',
+  'TH_TNIN',
+  'AU_MEDICARE',
+  'DE_TAX_ID',
+  'AE_EMIRATES_ID',
+  'SA_NATIONAL_ID',
+  'IL_ID_NUMBER',
+]);
+export function isIdentityType(type) {
+  return (
+    identityTypes.has(type) ||
+    /PASSPORT|(?:DRIVERS?|DRIVING)_?LICENSE|IDENTITY|NATIONAL_?(?:ID|IDENTIFICATION)|PERSONAL_?(?:ID|IDENTIFICATION)|UNIQUE_?IDENTIFICATION|SOCIAL_?(?:SECURITY|INSURANCE|IDENTIFICATION)|RESIDENT_?REGISTRATION|(?:TAX|TAXPAYER).*?(?:IDENTIFICATION|NUMBER|REFERENCE)|AADHAAR|FISCAL_CODE|PESEL|RRN|NHS|SNILS|INN_NUMBER/.test(
+      type
+    )
+  );
+}

package/src/identity.js

@@ -1,66 +1,8 @@
 import { collectMatches } from './detection.js';
 
-export const identityTypes = new Set([
-  'SSN',
-  'US_SSN',
-  'BRAZIL_CPF_NUMBER',
-  'INDIA_PAN_INDIVIDUAL',
-  'UK_NATIONAL_INSURANCE_NUMBER',
-  'SPAIN_DNI_NUMBER',
-  'US_HEALTHCARE_NPI',
-  'DRIVER_LICENSE',
-  'DRIVERS_LICENSE',
-  'NATIONAL_ID',
-  'CHINA_RESIDENT_ID_NUMBER',
-  'HONG_KONG_ID_NUMBER',
-  'SOUTH_AFRICA_ID_NUMBER',
-  'TAIWAN_ID_NUMBER',
-  'TURKEY_ID_NUMBER',
-  'GOVERNMENT_ID',
-  'DOD_ID_NUMBER',
-  'JAPAN_INDIVIDUAL_NUMBER',
-  'INDIA_GST_INDIVIDUAL',
-  'US_MEDICARE_BENEFICIARY_ID_NUMBER',
-  'ID',
-  'PASSPORT_NUMBER',
-  'PASSPORT_MRZ',
-  'BOOKING_REFERENCE',
-  'TICKET_NUMBER',
-  'VISA_NUMBER',
-  'UK_NHS',
-  'KR_RRN',
-  'IT_FISCAL_CODE',
-  'SG_NRIC_FIN',
-  'PL_PESEL',
-  'SE_PERSONNUMMER',
-  'ZA_ID_NUMBER',
-  'AU_TFN',
-  'CA_SIN',
-  'RU_SNILS',
-  'RU_INN',
-  'US_ITIN',
-  'US_DRIVER_LICENSE',
-  'UK_DRIVING_LICENCE',
-  'ES_NIE',
-  'IN_AADHAAR',
-  'IN_VOTER',
-  'IN_PASSPORT',
-  'FI_PERSONAL_IDENTITY_CODE',
-  'TH_TNIN',
-  'AU_MEDICARE',
-  'DE_TAX_ID',
-  'AE_EMIRATES_ID',
-  'SA_NATIONAL_ID',
-  'IL_ID_NUMBER',
-]);
-export function isIdentityType(type) {
-  return (
-    identityTypes.has(type) ||
-    /PASSPORT|(?:DRIVERS?|DRIVING)_?LICENSE|IDENTITY|NATIONAL_?(?:ID|IDENTIFICATION)|PERSONAL_?(?:ID|IDENTIFICATION)|UNIQUE_?IDENTIFICATION|SOCIAL_?(?:SECURITY|INSURANCE|IDENTIFICATION)|RESIDENT_?REGISTRATION|(?:TAX|TAXPAYER).*?(?:IDENTIFICATION|NUMBER|REFERENCE)|AADHAAR|FISCAL_CODE|PESEL|RRN|NHS|SNILS|INN_NUMBER/.test(
-      type
-    )
-  );
-}
+import { isIdentityType } from './identity-types.js';
+
+export { identityTypes, isIdentityType } from './identity-types.js';
 const personal = (type, rule, confidence = 0.85) => ({
   type,
   rule,

package/src/index.d.ts

@@ -17,6 +17,8 @@ export interface Finding {
   kept?: 'fake';
   /** Returned finding replaced with, or recognized as, a generated fake. */
   faked?: true;
+  /** For `JSON_VALUE`: the field's personal type, e.g. `AGE`, when known. */
+  valueType?: string;
 }
 export interface PersonalValue {
   type: string;
@@ -31,7 +33,9 @@ export type Vocabulary = Partial<
     | 'organizationCues'
     | 'educationCues'
     | 'personalLabels'
-    | 'personalFields',
+    | 'personalFields'
+    /** Word stems for the strict special-category rule; needs `strict: true`. */
+    | 'personalAttributes',
     VocabularyList
   >
 >;
@@ -114,6 +118,19 @@ export interface SanitizerOptions {
    * same rules as allowList.
    */
   inlineAllow?: boolean;
+  /**
+   * Keeps a finding the caller's policy knows is not sensitive. Runs after
+   * detection and before transformation, once per finding, with the text the
+   * offsets refer to; it must return a boolean (`true` keeps the span as-is).
+   * Verification of the output consults it again per span, so the same value
+   * elsewhere is still caught. Declared knownSecrets/knownPersonal/
+   * confirmedPersonal values and JSON_VALUE denials are never offered.
+   * createSyncSanitizer and sanitize() require a synchronous hook.
+   */
+  exempt?: (
+    finding: Readonly<Finding & { value: string }>,
+    text: string
+  ) => boolean | Promise<boolean>;
   /** Explicit network/callback verification; credentials never qualify. */
   verifyPublic?: (candidate: {
     type: PublicEntity['type'];
@@ -243,7 +260,11 @@ export declare function fromOffsetReport(
 ): Finding[];
 export declare function knownSecretsFromEnv(
   env?: Record<string, string | undefined>,
-  names?: string[]
+  names?: string[],
+  options?: {
+    /** Skip values shorter than this many characters (default 1). */
+    minLength?: number;
+  }
 ): string[];
 /** Reversible UTF-8 view: invalid bytes use unpaired U+DC80..U+DCFF. */
 export declare function decodeLogBytes(bytes: Uint8Array): string;
@@ -300,6 +321,12 @@ export type Transformation =
       map?: RestoreMap | false;
       format?: string;
       credentials?: boolean;
+      /**
+       * Tokens of the namespace already in the input: `'error'` (default)
+       * throws `ERR_PLACEHOLDER_COLLISION`; `'keep'` leaves them as they are
+       * and numbers new values after the highest kept number per type.
+       */
+      existing?: 'error' | 'keep';
     }
   | {
       mode: 'mask';
@@ -378,6 +405,18 @@ export declare function writeRestoreMap(
 ): Promise<void>;
 /** Exact original-document restoration; derived text uses canonical surfaces. */
 export declare function restore(text: string, map: RestoreMap): string;
+/** Sorted, frozen list of the types built-in rules turn into `Type-n` tokens. */
+export declare function reservedPlaceholderTypes(): readonly string[];
+/** Whether `text` is one whole token of the placeholder namespace. */
+export declare function isPlaceholderToken(
+  text: string,
+  options?: {
+    /** Placeholder format, default `'{Type}-{n}'`. */
+    format?: string;
+    /** Extra custom types, e.g. those of `createPatternDetector`. */
+    types?: readonly string[];
+  }
+): boolean;
 export interface StreamOptions extends SanitizerOptions {
   /** Treat NUL as a log byte; default false. Incompatible with JSON/JSONL. */
   allowBinary?: boolean;

package/src/index.js

@@ -1,5 +1,7 @@
 /** Sensitive text detection and verified publication APIs. */
 
+import './personal-features.js';
+
 export { inspect, sanitize, redact } from './sanitizer.js';
 export { createSanitizer } from './engines.js';
 export { compileKnown } from './compiled-known.js';
@@ -58,3 +60,7 @@ export {
   readRestoreMap,
   writeRestoreMap,
 } from './restore-map.js';
+export {
+  reservedPlaceholderTypes,
+  isPlaceholderToken,
+} from './placeholder-types.js';

package/src/known.js

@@ -71,28 +71,44 @@ function configTokens(config) {
   return [...values];
 }
 
+// Credential keywords between `_` boundaries, plus suffixes that are written
+// without one (`PGPASSWORD`, `GITHUBTOKEN`, `SESSIONCOOKIE`).
 const secretEnvName =
-  /(?:^|_)(?:TOKEN|(?:API|ACCESS|PRIVATE)?KEY|SECRET|PASSWORD|PASSWD|CREDENTIALS?|AUTH|PAT)(?:_|$)/i;
-// Configuration suffixes describe how authentication works. Explicit names
-// bypass this filter; credential suffixes such as AUTH_MODE_TOKEN still win.
-const authConfigurationName =
-  /(?:^|_)AUTH_(?:TRANSPORT|MODE|METHOD|TYPE|URL|URI|HOST|HOSTNAME|PATH|ENABLED|DISABLED|PORT|PROTOCOL|SCHEME)$/i;
+  /(?:^|_)(?:TOKEN|(?:API|ACCESS|PRIVATE)?KEY|SECRET|PASSWORD|PASSWD|CREDENTIALS?|O?AUTH|PAT|COOKIE)(?:_|$)|(?:PASSWORD|PASSWD|TOKEN|COOKIE)$/i;
+// Configuration suffixes describe a credential (how authentication works,
+// counters, limits, locations, names, identifiers and guard flags), not the
+// credential itself. Explicit names bypass this filter; credential suffixes
+// such as AUTH_MODE_TOKEN still win.
+const configurationName =
+  /_(?:TRANSPORT|MODE|METHOD|TYPE|URL|URI|HOST|HOSTNAME|PATH|ENABLED|DISABLED|PORT|PROTOCOL|SCHEME|GUARD|COUNT|LIMIT|FILE|FILENAME|DIR|DIRECTORY|NAME|ID)$|^GIT_CONFIG_KEY_\d+$|^GOOGLE_APPLICATION_CREDENTIALS$/i;
+// `GIT_CONFIG_KEY_<n>` names a git setting; `GIT_CONFIG_VALUE_<n>` holds the
+// value, which is a credential for headers, passwords and tokens.
+const gitCredentialSetting =
+  /(?:^|\.)(?:extraheader|password|token|secret|cookiefile|auth[a-z]*)$/i;
+
+function discoveredNames(env) {
+  return Object.keys(env).filter((name) => {
+    const git = name.match(/^GIT_CONFIG_VALUE_(\d+)$/);
+    if (git) {
+      return gitCredentialSetting.test(env[`GIT_CONFIG_KEY_${git[1]}`] ?? '');
+    }
+    return secretEnvName.test(name) && !configurationName.test(name);
+  });
+}
+
 /** Opt-in literal values from credential-named keys, or an explicit selection. */
-export function knownSecretsFromEnv(env = process.env, names) {
+export function knownSecretsFromEnv(env = process.env, names, options = {}) {
+  const { minLength = 1 } = options ?? {};
   if (names === undefined) {
-    names =
-      env && typeof env === 'object'
-        ? Object.keys(env).filter(
-            (name) =>
-              secretEnvName.test(name) && !authConfigurationName.test(name)
-          )
-        : [];
+    names = env && typeof env === 'object' ? discoveredNames(env) : [];
   }
   if (
     !env ||
     typeof env !== 'object' ||
     !Array.isArray(names) ||
-    names.some((name) => typeof name !== 'string')
+    names.some((name) => typeof name !== 'string') ||
+    !Number.isSafeInteger(minLength) ||
+    minLength < 1
   ) {
     throw failure('ERR_CONFIG');
   }
@@ -100,7 +116,9 @@ export function knownSecretsFromEnv(env = process.env, names) {
     ...new Set(
       names
         .map((name) => env[name])
-        .filter((value) => typeof value === 'string' && value.length)
+        .filter(
+          (value) => typeof value === 'string' && value.length >= minLength
+        )
     ),
   ];
 }

package/src/personal-features.js

@@ -0,0 +1,39 @@
+// Registers the personal-data detectors and fake generators. The main entry
+// imports this module for its side effect; the `./credentials` entry does not,
+// which keeps faker, libphonenumber and these detectors out of its start-up.
+import { registerFeatures } from './features.js';
+import { detectPersonal } from './personal.js';
+import { detectCatalog } from './entities.js';
+import { detectIdentity, fakeIdentityValue } from './identity.js';
+import { detectNational } from './national.js';
+import { detectPersonalContext } from './personal-context.js';
+import { detectPersonalEvidence } from './personal-evidence.js';
+import { detectDocumentEntities } from './document-entities.js';
+import {
+  detectProseAndDocuments,
+  validateProperNames,
+} from './proper-names.js';
+import { detectStrict } from './strict.js';
+import { realisticFake } from './fake.js';
+import { prepareFakeText } from './fake-entities.js';
+import { fakeDocumentSpans } from './specimens.js';
+
+function detectPersonalData(text, emit, options) {
+  detectPersonal(text, emit);
+  detectProseAndDocuments(text, emit, options, detectDocumentEntities);
+  detectCatalog(text, emit);
+  detectIdentity(text, emit);
+  detectNational(text, emit);
+  detectPersonalContext(text, emit);
+  detectPersonalEvidence(text, emit);
+  detectStrict(text, emit, options);
+}
+
+registerFeatures({
+  detectPersonalData,
+  validateProperNames,
+  realisticFake,
+  prepareFakeText,
+  fakeDocumentSpans,
+  fakeIdentityValue,
+});

package/src/personal.js

@@ -3,6 +3,7 @@ import { firstNames } from './names.js';
 import { labels } from './rules.js';
 import { transliteratedGivenNames } from './transliteration.js';
 import { serviceAccounts } from './public.js';
+import { isCommonProseWord } from './prose-words.js';
 const labelWords = new Set(Object.values(labels).flat());
 
 const details = (type, rule, confidence = 0.85) => ({
@@ -193,14 +194,39 @@ const possessiveWord =
 function slavicPairEvidence(value) {
   const words = value.split(/[ \t]+/);
   return !words.some(
-    (word) => possessiveWord.test(word) || /^\p{Lu}{2,4}$/u.test(word)
+    (word) =>
+      possessiveWord.test(word) ||
+      /^\p{Lu}{2,4}$/u.test(word) ||
+      isCommonProseWord(word)
   );
 }
+// A rejected pair is retried from its second word, so `Кандидат Петров Иван`
+// still finds `Петров Иван` after the cue word.
+function detectSlavicPairs(text, emit) {
+  const pattern = new RegExp(slavicPairs.source, 'gu');
+  let match;
+  while ((match = pattern.exec(text))) {
+    const value = match[0];
+    if (
+      value !== 'REDACTED' &&
+      !placeWord.test(value.split(/[ \t]+/).at(-1)) &&
+      slavicPairEvidence(value)
+    ) {
+      emit({
+        start: match.index,
+        end: match.index + value.length,
+        ...details('PERSON', 'name-identity', 0.9),
+      });
+    } else {
+      pattern.lastIndex = match.index + value.search(/[ \t]/u) + 1;
+    }
+  }
+}
 export function detectPersonal(text, emit) {
   detectDocumentNames(text, emit);
+  detectSlavicPairs(text, emit);
   for (const pattern of [
     latinPairs,
-    slavicPairs,
     russianFull,
     /(?<![\p{L}])(?:[А-ЯЁ][а-яё]{2,30}[ \t]+)[А-ЯЁ][а-яё]{2,30}(?:вич|вна|ична)[ \t]+[А-ЯЁ][а-яё]{2,30}(?![\p{L}])/gu,
   ]) {
@@ -210,9 +236,7 @@ export function detectPersonal(text, emit) {
       emit,
       details('PERSON', 'name-identity', 0.9),
       0,
-      (value) =>
-        !placeWord.test(value.split(/[ \t]+/).at(-1)) &&
-        (pattern !== slavicPairs || slavicPairEvidence(value))
+      (value) => !placeWord.test(value.split(/[ \t]+/).at(-1))
     );
   }
   for (const pattern of names) {

package/src/placeholder-types.js

@@ -1,34 +1,194 @@
 import { catalogTypes } from './entities.js';
+import { escapePattern, failure } from './detection.js';
+import { jsonStringLiterals } from './json-string-runs.js';
+import { placeholderToken, validatePlaceholderFormat } from './restore-map.js';
 
-// Native unlabelled types supplement the shared vendor-label catalog.
-export const reservedPlaceholderTypes = () => [
-  ...catalogTypes(),
+// Native types that the shared vendor-label catalog does not already list. The
+// national identifier types are spelled out here so that this module does not
+// load the national rules.
+const nativeTypes = [
+  'ABA_ROUTING_NUMBER',
   'ADDRESS',
+  'AE_EMIRATES_ID',
+  'AGE',
+  'AU_ABN',
+  'AU_ACN',
+  'AU_MEDICARE',
   'AU_TFN',
   'BRAZIL_CPF_NUMBER',
+  'CA_SIN',
   'CREDENTIAL',
   'CREDIT_CARD',
   'DATE',
+  'DE_TAX_ID',
   'EDUCATION',
   'EMAIL',
   'ENCODED_SENSITIVE',
+  'ES_NIE',
+  'EU_VAT_NUMBER',
+  'FI_PERSONAL_IDENTITY_CODE',
+  'GENDER',
   'IBAN',
   'ID',
+  'IL_ID_NUMBER',
+  'IMEI',
+  'IN_AADHAAR',
+  'IN_GSTIN',
+  'IN_PASSPORT',
+  'IN_VOTER',
   'IP_ADDRESS',
+  'IT_FISCAL_CODE',
+  'IT_VAT_CODE',
   'KR_RRN',
   'LOCATION',
   'MAC_ADDRESS',
+  'MEDICAL_LICENSE',
   'ORGANIZATION',
   'PASSPORT_MRZ',
   'PASSPORT_NUMBER',
   'PERSON',
-  'PROPER_NAME',
+  'PERSONAL_ATTRIBUTE',
   'PHONE',
   'PL_PESEL',
+  'POSTAL_CODE',
+  'PROPER_NAME',
   'RU_INN',
   'RU_SNILS',
+  'SA_NATIONAL_ID',
+  'SENSITIVE',
+  'SE_PERSONNUMMER',
   'SG_NRIC_FIN',
+  'SG_UEN',
   'STATE',
+  'STEAM_ID',
+  'SWIFT_CODE',
+  'TH_TNIN',
+  'TRACKING_NUMBER',
+  'UK_DRIVING_LICENCE',
+  'UK_NATIONAL_INSURANCE_NUMBER',
+  'UK_NHS',
+  'UK_POSTCODE',
+  'URL',
   'USERNAME',
+  'US_BANK_NUMBER',
+  'US_DRIVER_LICENSE',
   'US_HEALTHCARE_NPI',
+  'US_ITIN',
+  'VIN',
+  'ZA_ID_NUMBER',
 ];
+let reserved;
+// Every type that a built-in rule can turn into a `Type-n` token.
+export function reservedPlaceholderTypes() {
+  reserved ??= Object.freeze(
+    [...new Set([...catalogTypes(), ...nativeTypes])].sort()
+  );
+  return reserved;
+}
+
+const defaultFormat = '{Type}-{n}';
+const patterns = new Map();
+const patternCacheSize = 64;
+// The namespace pattern depends only on the format and on the types beyond the
+// reserved list, so it is compiled once per format and cached.
+export function namespacePattern(format = defaultFormat, extraTypes = []) {
+  const base = new Set(reservedPlaceholderTypes());
+  const extra = [...new Set(extraTypes)].filter((type) => !base.has(type));
+  const key = `${format}\0${extra.sort().join('\0')}`;
+  const cached = patterns.get(key);
+  if (cached) {
+    return cached;
+  }
+  const [before, after] = format.split('{n}');
+  const typed = before.match(/\{(?:Type|TYPE|type)\}/) ? before : after;
+  const types = new Map();
+  for (const type of [...base, ...extra]) {
+    const part = placeholderToken(type, 1, typed);
+    types.set(part, [...(types.get(part) ?? []), type]);
+  }
+  const alternation = [...types.keys()]
+    .sort((a, b) => b.length - a.length || a.localeCompare(b))
+    .map(escapePattern)
+    .join('|');
+  const number = '([1-9][0-9]*)';
+  const source =
+    typed === before
+      ? `(${alternation})${number}${escapePattern(after)}`
+      : `${escapePattern(before)}${number}(${alternation})`;
+  const pattern = {
+    source: `(?<![\\p{L}\\p{M}\\p{N}_])(?:${source})(?![\\p{L}\\p{M}\\p{N}_])`,
+    typedFirst: typed === before,
+    types,
+  };
+  if (patterns.size >= patternCacheSize) {
+    patterns.delete(patterns.keys().next().value);
+  }
+  patterns.set(key, pattern);
+  return pattern;
+}
+// Tokens of the namespace with the types each spelling can stand for.
+export function placeholderTokens(text, pattern) {
+  const tokens = [];
+  if (!/[1-9]/u.test(text)) {
+    return tokens;
+  }
+  for (const match of text.matchAll(new RegExp(pattern.source, 'gu'))) {
+    const [part, number] = pattern.typedFirst
+      ? [match[1], match[2]]
+      : [match[2], match[1]];
+    tokens.push({
+      start: match.index,
+      end: match.index + match[0].length,
+      number: Number(number),
+      types: pattern.types.get(part),
+    });
+  }
+  return tokens;
+}
+export function containsPlaceholder(text, pattern) {
+  return /[1-9]/u.test(text) && new RegExp(pattern.source, 'u').test(text);
+}
+// Tokens spelled with JSON escapes inside string literals, such as
+// `Person-1`, decoded so that they cannot hide from the namespace check.
+export function escapedPlaceholderTokens(text, pattern) {
+  const tokens = [];
+  // Without an escape every literal has already been checked in the raw text.
+  if (!text.includes('\\')) {
+    return tokens;
+  }
+  for (const literal of jsonStringLiterals(text)) {
+    if (!literal.includes('\\')) {
+      continue;
+    }
+    try {
+      tokens.push(...placeholderTokens(JSON.parse(literal), pattern));
+    } catch {
+      // Ordinary free text may include strings that are not JSON literals.
+    }
+  }
+  return tokens;
+}
+
+// Public check for a whole `Type-n` token of the library namespace.
+export function isPlaceholderToken(text, options = {}) {
+  if (
+    options === null ||
+    typeof options !== 'object' ||
+    (options.types !== undefined &&
+      (!Array.isArray(options.types) ||
+        options.types.some(
+          (type) =>
+            typeof type !== 'string' || !/^[A-Z][A-Z0-9_]{0,63}$/.test(type)
+        )))
+  ) {
+    throw failure('ERR_CONFIG');
+  }
+  if (typeof text !== 'string') {
+    return false;
+  }
+  const pattern = namespacePattern(
+    validatePlaceholderFormat(options.format ?? defaultFormat),
+    options.types ?? []
+  );
+  return new RegExp(`^(?:${pattern.source})$`, 'u').test(text);
+}