@pharmatools/redacta 1.1.1

package/README.md

@@ -0,0 +1,61 @@
+# @pharmatools/redacta
+
+Pseudonymise patient identifiers and PII in text — and restore them. A
+dependency-free TypeScript engine you can embed in any Node or browser pipeline.
+
+```bash
+npm install @pharmatools/redacta
+```
+
+```ts
+import { Redactor, reinstate, selfCheck } from "@pharmatools/redacta";
+
+const redactor = new Redactor(["clinical", "general"]);
+const { text } = redactor.redactText(
+  "Dear Mrs Patricia Hartley, NHS Number: 943 476 5919"
+);
+// text -> "Dear [PATIENT_NAME_1], NHS Number: [NHS_NUMBER_1]"
+
+// same Redactor keeps a token map across many strings (consistent tokens)
+const original = reinstate(text, redactor.tokenMap).text;
+// original -> "Dear Mrs Patricia Hartley, NHS Number: 943 476 5919"
+
+// second-pass safety check on already-redacted text
+const leftovers = selfCheck(text); // ResidualFinding[]
+```
+
+## What it detects
+
+Deterministic, checksum-validated patterns — NHS numbers (Modulus-11), UK
+National Insurance numbers, dates of birth (keyword-anchored; appointment dates
+preserved), UK postcodes, US SSN/ZIP, hospital/MRN numbers, emails, phones —
+plus general PII (URLs, IPs, Luhn-validated payment cards, IBANs, account
+numbers, UK vehicle regs) and keyword-anchored patient / relative / carer names
+(clinician names preserved by design). Names in free prose are not caught.
+
+Same value → same token across a `Redactor` instance; the `tokenMap` reverses
+the redaction. No DOM, no network, no storage.
+
+## API
+
+- `new Redactor(categories: ("clinical" | "general")[])` — `.redactText(s)`,
+  `.report`, `.tokenMap`
+- `reinstate(text, tokenMap)` → `{ text, changed }`
+- `selfCheck(text)` → `ResidualFinding[]`
+- `isValidNhs`, `isValidNi`, `isValidLuhn`, `isValidTokenMap`
+
+This is the same engine that powers the
+[Redacta for Miro app](https://www.pharmatools.ai/redacta) and the
+[`redacta-mcp` server](https://www.npmjs.com/package/redacta-mcp). For an
+agent-skill build with LLM reasoning over free-text names, see the
+[Redacta skill](https://clawhub.ai/nickjlamb/redacta).
+
+## Limits
+
+Deterministic + keyword-anchored detection only — not a guarantee, not a
+substitute for formal data-protection processes. Review the output, and treat the
+token map as the key that reverses the redaction.
+
+## License
+
+MIT-0. Built by [PharmaTools.AI](https://www.pharmatools.ai/redacta).

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./redact.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./redact.js";

package/dist/redact.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Redacta — deterministic pattern engine.
+ *
+ * Pure TypeScript: no DOM, no network, no storage. Replaces fixed-format
+ * identifiers and PII with labelled tokens, catches keyword-anchored names
+ * (patients, relatives, carers — clinician names preserved), self-checks the
+ * output, and reverses the process from a token map.
+ */
+export type Category = "clinical" | "general";
+/** Validate a 10-digit NHS number using the Modulus-11 check digit. */
+export declare function isValidNhs(digits: string): boolean;
+/** Validate the two-letter prefix of a UK National Insurance number. */
+export declare function isValidNi(prefix: string): boolean;
+/** Luhn checksum for payment card numbers. */
+export declare function isValidLuhn(digits: string): boolean;
+export interface RedactionResult {
+    text: string;
+    changed: boolean;
+}
+export interface ResidualFinding {
+    label: string;
+    sample: string;
+}
+/**
+ * A Redactor keeps one Tokeniser across many texts, so the same identifier
+ * gets the same token on every sticky note on the board.
+ */
+export declare class Redactor {
+    private tok;
+    private passes;
+    constructor(categories: Category[]);
+    redactText(input: string): RedactionResult;
+    /** {token_type: number_of_distinct_values} */
+    get report(): Record<string, number>;
+    /** {token: original_value} — for review / re-identification. Handle with care. */
+    get tokenMap(): Record<string, string>;
+}
+/**
+ * Re-scan already-redacted text for anything that still looks like an
+ * identifier, so the UI can warn the user to check manually. Returns one
+ * finding per distinct sample (deduplicated, capped). A clean result is not a
+ * guarantee — it's a second pair of eyes, not a proof.
+ */
+/**
+ * Re-identification: replace tokens with their original values, using a token
+ * map produced by an earlier redaction. The inverse of redaction — for putting
+ * real data back into AI output before it returns to the board.
+ *
+ * Tokens always end in "]", so "[NAME_1]" never matches inside "[NAME_10]";
+ * plain string replacement is safe.
+ */
+export declare function reinstate(text: string, tokenMap: Record<string, string>): RedactionResult;
+/** Validate that a parsed object is a usable token map ([TOKEN] -> string). */
+export declare function isValidTokenMap(value: unknown): value is Record<string, string>;
+export declare function selfCheck(redactedText: string): ResidualFinding[];

package/dist/redact.js

@@ -0,0 +1,377 @@
+/**
+ * Redacta — deterministic pattern engine.
+ *
+ * Pure TypeScript: no DOM, no network, no storage. Replaces fixed-format
+ * identifiers and PII with labelled tokens, catches keyword-anchored names
+ * (patients, relatives, carers — clinician names preserved), self-checks the
+ * output, and reverses the process from a token map.
+ */
+// ---------------------------------------------------------------------------
+// Validators
+// ---------------------------------------------------------------------------
+/** Validate a 10-digit NHS number using the Modulus-11 check digit. */
+export function isValidNhs(digits) {
+    if (!/^\d{10}$/.test(digits))
+        return false;
+    if (digits === digits[0].repeat(10))
+        return false;
+    const weights = [10, 9, 8, 7, 6, 5, 4, 3, 2];
+    const total = weights.reduce((sum, w, i) => sum + Number(digits[i]) * w, 0);
+    let check = 11 - (total % 11);
+    if (check === 11)
+        check = 0;
+    if (check === 10)
+        return false;
+    return check === Number(digits[9]);
+}
+const NI_INVALID_PREFIX = new Set(["BG", "GB", "NK", "KN", "TN", "NT", "ZZ"]);
+const NI_PREFIX1_BAD = new Set("DFIQUV");
+const NI_PREFIX2_BAD = new Set("DFIOQUV");
+/** Validate the two-letter prefix of a UK National Insurance number. */
+export function isValidNi(prefix) {
+    const p = prefix.toUpperCase();
+    if (p.length !== 2 || NI_INVALID_PREFIX.has(p))
+        return false;
+    return !NI_PREFIX1_BAD.has(p[0]) && !NI_PREFIX2_BAD.has(p[1]);
+}
+/** Luhn checksum for payment card numbers. */
+export function isValidLuhn(digits) {
+    if (!/^\d{13,19}$/.test(digits))
+        return false;
+    let sum = 0;
+    let dbl = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let d = Number(digits[i]);
+        if (dbl) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        dbl = !dbl;
+    }
+    return sum % 10 === 0;
+}
+// ---------------------------------------------------------------------------
+// Tokeniser: same value -> same token, distinct values -> new numbers
+// ---------------------------------------------------------------------------
+class Tokeniser {
+    byKey = new Map();
+    counters = new Map();
+    tokenMap = {};
+    tokenFor(type, original, key) {
+        const k = `${type}::${key ?? original}`;
+        const existing = this.byKey.get(k);
+        if (existing)
+            return existing;
+        const n = (this.counters.get(type) ?? 0) + 1;
+        this.counters.set(type, n);
+        const token = `[${type}_${n}]`;
+        this.byKey.set(k, token);
+        this.tokenMap[token] = original;
+        return token;
+    }
+}
+// ---------------------------------------------------------------------------
+// Patterns
+// ---------------------------------------------------------------------------
+const MONTHS = "January|February|March|April|May|June|July|August|September|" +
+    "October|November|December|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sept?|Oct|Nov|Dec";
+const DATE = [
+    String.raw `\d{1,2}[/.\-]\d{1,2}[/.\-]\d{2,4}`,
+    String.raw `\d{4}-\d{2}-\d{2}`,
+    String.raw `\d{1,2}(?:st|nd|rd|th)?\s+(?:${MONTHS})\s+\d{4}`,
+    String.raw `(?:${MONTHS})\s+\d{1,2}(?:st|nd|rd|th)?,?\s+\d{4}`,
+]
+    .map((s) => `(?:${s})`)
+    .join("|");
+// A date only counts as a DOB when anchored to a DOB keyword, so clinical and
+// appointment dates are left intact.
+const DOB_RE = new RegExp(String.raw `(\b(?:date\s+of\s+birth|d\.?o\.?b\.?|born(?:\s+on)?)[\s:.]*)((?:${DATE}))`, "gi");
+const NHS_RE = /\b(\d{3}[\s-]?\d{3}[\s-]?\d{4})\b/g;
+const NI_RE = /\b([A-Za-z]{2})\s?(\d{2})\s?(\d{2})\s?(\d{2})\s?([A-Da-d])\b/g;
+const SSN_FMT_RE = /(?<!\d)(?!000|666|9\d\d)(\d{3})([-\s])(\d{2})\2(\d{4})(?!\d)/g;
+const SSN_KW_RE = /((?:SSN|Social\s*Security(?:\s*(?:Number|No\.?|#))?)[\s:]*)((?!000|666|9\d\d)\d{9})(?!\d)/gi;
+const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+const MRN_RE = /((?:MRN|Hospital\s*(?:No\.?|Number)|Hosp\.?\s*(?:No\.?|Number)|Patient\s*ID|Unit\s*(?:No\.?|Number))[\s:]*)([A-Z0-9-]{4,15})/gi;
+const POSTCODE_RE = /\b(GIR\s?0AA|[A-Z]{1,2}\d[A-Z\d]?\s?\d[A-Z]{2})\b/gi;
+const US_STATES = "AL|AK|AZ|AR|CA|CO|CT|DE|FL|GA|HI|ID|IL|IN|IA|KS|KY|LA|ME|MD|MA|MI|MN|MS|MO|" +
+    "MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PA|RI|SC|SD|TN|TX|UT|VT|VA|WA|WV|WI|WY|DC";
+const ZIP_KW_RE = /((?:ZIP|Zip\s*Code|Postal\s*Code)[\s:]*)(\d{5}(?:-\d{4})?)(?!\d)/gi;
+const ZIP_STATE_RE = new RegExp(String.raw `((?:,?\s)(?:${US_STATES})\s+)(\d{5}(?:-\d{4})?)(?!\d)`, "g");
+// --- General-PII additions -------------------------------------------------
+const URL_RE = /\b(?:https?:\/\/|www\.)[^\s<>"'\])]+/gi;
+const IP_RE = /\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)\b/g;
+// Candidate card numbers (13-19 digits, optionally space/dash separated),
+// confirmed with the Luhn checksum before redacting.
+const CARD_RE = /(?<![\d-])(?:\d[ -]?){12,18}\d(?![\d-])/g;
+const IBAN_RE = /\b[A-Z]{2}\d{2}(?:\s?[A-Z0-9]{4}){2,7}(?:\s?[A-Z0-9]{1,3})?\b/g;
+const ACCOUNT_KW_RE = /((?:Account|Acct\.?|Member\s*ID|Policy\s*(?:No\.?|Number)|Insurance\s*ID)\s*(?:No\.?|Number|#)?[\s:]*)((?=[A-Z0-9-]*\d)[A-Z0-9-]{5,17})/gi;
+const UK_PLATE_RE = /\b[A-Z]{2}\d{2}\s?[A-Z]{3}\b/g;
+// --- Names (keyword-anchored) ----------------------------------------------
+// Names need contextual judgement, which a client-side deterministic engine
+// can't fully do. We catch the high-confidence cases — names introduced by a
+// courtesy title, a salutation, or a label — and deliberately PRESERVE names
+// carrying a clinical title (Dr, Consultant, Nurse, ...), matching the Redacta
+// skill's "don't redact the treating clinician" rule. Names buried in free
+// prose are NOT caught; the UI tells users to review.
+const NAME = String.raw `[A-Z][a-z]+(?:['’\-][A-Za-z]+)?(?:[ \t]+[A-Z][a-z]+(?:['’\-][A-Za-z]+)?){0,2}`;
+// Case-sensitive, anchored version. Used to trim a loosely-captured name down
+// to its leading run of properly capitalised words — necessary because the
+// label/relative regexes carry the `i` flag (for the keyword), which would
+// otherwise let a name match swallow trailing lowercase words ("Sarah is the").
+const STRICT_NAME_RE = new RegExp("^" + NAME);
+/** Split a loosely-captured name into its real leading name and the remainder. */
+function leadingName(s) {
+    const m = s.match(STRICT_NAME_RE);
+    if (!m)
+        return null;
+    return { name: m[0], rest: s.slice(m[0].length) };
+}
+const COURTESY_TITLE = "Mr|Mrs|Ms|Miss|Mx";
+const CLINICAL_TITLE = "Dr|Doctor|Prof|Professor|Consultant|Nurse|Sister|Matron|Surgeon|Registrar";
+// "Mrs Patricia Hartley" → redact title + name together.
+const NAME_TITLE_RE = new RegExp(String.raw `\b(?:${COURTESY_TITLE})\.?\s+(${NAME})`, "g");
+// "Dear Patricia Hartley" → keep "Dear", redact the name — unless a clinical title follows.
+const NAME_SALUTATION_RE = new RegExp(String.raw `\b(Dear)\s+(?!(?:${CLINICAL_TITLE})\b)(${NAME})`, "g");
+// "Patient: ...", "Name - ...", "Re: ..." → keep the label, redact the name.
+const NAME_LABEL_RE = new RegExp(String.raw `\b((?:Patient(?:\s+Name)?|Name|Client|Re)\s*[:\-]\s*)(${NAME})`, "gi");
+// Relatives and carers: a relationship word followed by a name. HIPAA Safe
+// Harbor treats relatives' names as identifiers, so "her daughter Sarah" or
+// "NOK: John Hartley" should be redacted too.
+const RELATION = "daughter|son|wife|husband|partner|spouse|mother|father|mum|mom|dad|" +
+    "sister|brother|sibling|grandson|granddaughter|grandmother|grandfather|" +
+    "grandparent|aunt|uncle|niece|nephew|cousin|carer|caregiver|guardian|" +
+    "parent|next\\s+of\\s+kin|nok|relative|widow|widower";
+const RELATIVE_NAME_RE = new RegExp(String.raw `\b(${RELATION})([:,\-]?[ \t]+)(${NAME})`, "gi");
+const digitsOf = (s) => s.replace(/\D/g, "");
+const redactMrn = (text, tok) => text.replace(MRN_RE, (_m, kw, id) => kw + tok.tokenFor("MRN", id, id.toUpperCase()));
+const redactAccount = (text, tok) => text.replace(ACCOUNT_KW_RE, (_m, kw, id) => kw + tok.tokenFor("ACCOUNT_NUMBER", id, id.toUpperCase()));
+const redactDob = (text, tok) => text.replace(DOB_RE, (_m, kw, date) => kw + tok.tokenFor("DATE_OF_BIRTH", date));
+const redactNhs = (text, tok) => text.replace(NHS_RE, (m, raw) => {
+    const d = digitsOf(raw);
+    if (d.length === 10 && isValidNhs(d))
+        return tok.tokenFor("NHS_NUMBER", raw, d);
+    return m;
+});
+const redactNi = (text, tok) => text.replace(NI_RE, (m, p1, p2, p3, p4, p5) => {
+    if (!isValidNi(p1))
+        return m;
+    const key = (p1 + p2 + p3 + p4 + p5).toUpperCase();
+    return tok.tokenFor("NI_NUMBER", m.trim(), key);
+});
+const redactSsn = (text, tok) => {
+    let out = text.replace(SSN_FMT_RE, (m, a, _sep, b, c) => {
+        if (b === "00" || c === "0000")
+            return m;
+        return tok.tokenFor("SSN", m, a + b + c);
+    });
+    out = out.replace(SSN_KW_RE, (m, kw, num) => {
+        if (num.slice(3, 5) === "00" || num.slice(5, 9) === "0000")
+            return m;
+        return kw + tok.tokenFor("SSN", num, num);
+    });
+    return out;
+};
+const redactCard = (text, tok) => text.replace(CARD_RE, (m) => {
+    const d = digitsOf(m);
+    if (d.length >= 13 && d.length <= 19 && isValidLuhn(d)) {
+        return tok.tokenFor("CARD_NUMBER", m.trim(), d);
+    }
+    return m;
+});
+const redactIban = (text, tok) => text.replace(IBAN_RE, (m) => {
+    const clean = m.replace(/\s/g, "");
+    if (clean.length >= 15 && clean.length <= 34) {
+        return tok.tokenFor("IBAN", m, clean.toUpperCase());
+    }
+    return m;
+});
+const redactUrl = (text, tok) => text.replace(URL_RE, (m) => tok.tokenFor("URL", m, m.toLowerCase()));
+const redactEmail = (text, tok) => text.replace(EMAIL_RE, (m) => tok.tokenFor("EMAIL", m, m.toLowerCase()));
+const redactPhone = (text, tok) => {
+    const mk = (m) => tok.tokenFor("PHONE", m.trim(), digitsOf(m));
+    let out = text.replace(/(?<!\d)\+44[\s-]?(?:\(0\))?[\s-]?\d{2,5}[\s-]?\d{3,4}[\s-]?\d{3,4}(?!\d)/g, mk);
+    out = out.replace(/(?<!\d)\+1[\s\-.]?\(?\d{3}\)?[\s\-.]?\d{3}[\s\-.]?\d{4}(?!\d)/g, mk);
+    out = out.replace(/(?<!\d)\(?0\d{2,4}\)?[\s-]?\d{3,4}[\s-]?\d{3,4}(?!\d)/g, (m) => {
+        const len = digitsOf(m).length;
+        return len >= 10 && len <= 11 ? mk(m) : m;
+    });
+    out = out.replace(/(?<!\d)\(?[2-9]\d{2}\)?[\s\-.][2-9]\d{2}[\s\-.]\d{4}(?!\d)/g, mk);
+    return out;
+};
+const redactPostcode = (text, tok) => text.replace(POSTCODE_RE, (m) => {
+    const clean = m.replace(/\s/g, "");
+    if (clean.length >= 5 && clean.length <= 7) {
+        return tok.tokenFor("POSTCODE", m, clean.toUpperCase());
+    }
+    return m;
+});
+const redactZip = (text, tok) => {
+    let out = text.replace(ZIP_KW_RE, (_m, kw, zip) => kw + tok.tokenFor("ZIP", zip));
+    out = out.replace(ZIP_STATE_RE, (_m, pre, zip) => pre + tok.tokenFor("ZIP", zip));
+    return out;
+};
+const redactIp = (text, tok) => text.replace(IP_RE, (m) => tok.tokenFor("IP_ADDRESS", m));
+const redactPlate = (text, tok) => text.replace(UK_PLATE_RE, (m) => tok.tokenFor("VEHICLE_REG", m, m.replace(/\s/g, "").toUpperCase()));
+const redactRelative = (text, tok) => text.replace(RELATIVE_NAME_RE, (m, rel, sep, name) => {
+    // The `i` flag (for the relationship word) relaxes the name's
+    // capitalisation, so trim to the leading capitalised run — this both
+    // rejects "daughter and two sons" and stops "Sarah is the" over-capturing.
+    const split = leadingName(name);
+    if (!split)
+        return m;
+    return (rel + sep +
+        tok.tokenFor("RELATIVE_NAME", split.name, split.name.toLowerCase()) +
+        split.rest);
+});
+const redactName = (text, tok) => {
+    const nameToken = (raw) => tok.tokenFor("PATIENT_NAME", raw.trim(), raw.trim().toLowerCase().replace(/\s+/g, " "));
+    // Courtesy-titled names first. Store the full match (title + name) as the
+    // original so re-identification restores "Mrs Patricia Hartley" verbatim,
+    // but key on the name alone so the same person dedupes across contexts.
+    let out = text.replace(NAME_TITLE_RE, (m, name) => tok.tokenFor("PATIENT_NAME", m.trim(), name.trim().toLowerCase().replace(/\s+/g, " ")));
+    // Salutations without a courtesy title (clinical titles already excluded).
+    out = out.replace(NAME_SALUTATION_RE, (_m, dear, name) => `${dear} ${nameToken(name)}`);
+    // Labelled names — preserve the original label + separator. This regex also
+    // carries the `i` flag (for the label word), so trim the name the same way.
+    out = out.replace(NAME_LABEL_RE, (m, prefix, name) => {
+        const split = leadingName(name);
+        if (!split)
+            return m;
+        return prefix + nameToken(split.name) + split.rest;
+    });
+    return out;
+};
+// Order matters: keyword-anchored and checksum-validated patterns first,
+// weaker heuristics last, so high-confidence matches win any overlap.
+const CLINICAL_PASSES = [
+    redactMrn,
+    redactDob,
+    redactNhs,
+    redactNi,
+    redactSsn,
+    redactEmail,
+    redactPhone,
+    redactPostcode,
+    redactZip,
+    redactRelative,
+    redactName,
+];
+const GENERAL_PASSES = [
+    redactAccount,
+    redactCard,
+    redactIban,
+    redactUrl,
+    redactEmail,
+    redactPhone,
+    redactPostcode,
+    redactZip,
+    redactIp,
+    redactPlate,
+    redactRelative,
+    redactName,
+];
+// Self-check: patterns that should NOT remain in already-redacted text. These
+// are intentionally broad — they flag *possible* leftovers for human review,
+// not confirmed identifiers. Tokens like [NHS_NUMBER_1] are excluded.
+const RESIDUAL_CHECKS = [
+    { label: "long number (10+ digits)", re: /(?<![\d-])\d[\d\s-]{8,}\d(?![\d-])/g },
+    { label: "email address", re: /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g },
+    { label: "UK postcode", re: /\b[A-Z]{1,2}\d[A-Z\d]?\s?\d[A-Z]{2}\b/gi },
+    { label: "URL", re: /\b(?:https?:\/\/|www\.)\S+/gi },
+];
+/**
+ * A Redactor keeps one Tokeniser across many texts, so the same identifier
+ * gets the same token on every sticky note on the board.
+ */
+export class Redactor {
+    tok = new Tokeniser();
+    passes;
+    constructor(categories) {
+        const seen = new Set();
+        const passes = [];
+        if (categories.includes("clinical")) {
+            for (const p of CLINICAL_PASSES)
+                if (!seen.has(p))
+                    (seen.add(p), passes.push(p));
+        }
+        if (categories.includes("general")) {
+            for (const p of GENERAL_PASSES)
+                if (!seen.has(p))
+                    (seen.add(p), passes.push(p));
+        }
+        this.passes = passes;
+    }
+    redactText(input) {
+        // Normalise non-breaking spaces so spaced identifiers still match.
+        let text = input.replace(/[   ]/g, " ");
+        for (const pass of this.passes)
+            text = pass(text, this.tok);
+        return { text, changed: text !== input };
+    }
+    /** {token_type: number_of_distinct_values} */
+    get report() {
+        const report = {};
+        for (const token of Object.keys(this.tok.tokenMap)) {
+            const type = token.slice(1, -1).replace(/_\d+$/, "");
+            report[type] = (report[type] ?? 0) + 1;
+        }
+        return report;
+    }
+    /** {token: original_value} — for review / re-identification. Handle with care. */
+    get tokenMap() {
+        return { ...this.tok.tokenMap };
+    }
+}
+/**
+ * Re-scan already-redacted text for anything that still looks like an
+ * identifier, so the UI can warn the user to check manually. Returns one
+ * finding per distinct sample (deduplicated, capped). A clean result is not a
+ * guarantee — it's a second pair of eyes, not a proof.
+ */
+/**
+ * Re-identification: replace tokens with their original values, using a token
+ * map produced by an earlier redaction. The inverse of redaction — for putting
+ * real data back into AI output before it returns to the board.
+ *
+ * Tokens always end in "]", so "[NAME_1]" never matches inside "[NAME_10]";
+ * plain string replacement is safe.
+ */
+export function reinstate(text, tokenMap) {
+    let out = text;
+    for (const [token, original] of Object.entries(tokenMap)) {
+        if (token)
+            out = out.split(token).join(original);
+    }
+    return { text: out, changed: out !== text };
+}
+/** Validate that a parsed object is a usable token map ([TOKEN] -> string). */
+export function isValidTokenMap(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return false;
+    return entries.every(([k, v]) => /^\[[A-Z_]+_\d+\]$/.test(k) && typeof v === "string");
+}
+export function selfCheck(redactedText) {
+    const seen = new Set();
+    const findings = [];
+    for (const { label, re } of RESIDUAL_CHECKS) {
+        for (const match of redactedText.matchAll(re)) {
+            const sample = match[0].trim();
+            // Ignore our own tokens, e.g. [NHS_NUMBER_1].
+            if (/^\[[A-Z_]+_\d+\]$/.test(sample))
+                continue;
+            const key = `${label}:${sample.toLowerCase()}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            findings.push({ label, sample });
+            if (findings.length >= 20)
+                return findings;
+        }
+    }
+    return findings;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@pharmatools/redacta",
+  "version": "1.1.1",
+  "description": "Pseudonymise patient identifiers and PII in text (and restore them) — a dependency-free TypeScript engine. Names, relatives, general PII, self-check, re-identification.",
+  "license": "MIT-0",
+  "author": "Nick Lamb (PharmaTools.AI)",
+  "homepage": "https://www.pharmatools.ai/redacta",
+  "repository": { "type": "git", "url": "https://github.com/nickjlamb/redacta" },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "redaction",
+    "pseudonymisation",
+    "de-identification",
+    "anonymisation",
+    "pii",
+    "phi",
+    "healthcare",
+    "nhs",
+    "privacy",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}