@sudobility/sider_types 0.0.10 → 0.0.12

package/dist/index.d.ts

@@ -5,5 +5,6 @@ export * from "./local";
 export * from "./api";
 export * from "./actions";
 export * from "./templating";
+export * from "./personal-data";
 export * from "./recipe-hash";
 export * from "./observe";

package/dist/index.js

@@ -11,5 +11,6 @@ export * from "./local";
 export * from "./api";
 export * from "./actions";
 export * from "./templating";
+export * from "./personal-data";
 export * from "./recipe-hash";
 export * from "./observe";

package/dist/observe.d.ts

@@ -23,12 +23,27 @@ export interface SnapshotLink {
     toUrlPath: string;
     label?: string;
 }
+/**
+ * An anchor on the page pointing at a DIFFERENT origin.
+ *
+ * Kept apart from `SnapshotLink` on purpose: `links` feeds view identity and the
+ * graph's declared transitions, and a cross-origin entry there would churn every
+ * view signature. This is evidence of one thing only — that this site offers a
+ * way to reach that one.
+ */
+export interface SnapshotExternalLink {
+    origin: string;
+    /** Visible text of the link, e.g. "Careers at USF". */
+    label?: string;
+}
 export interface PageSnapshot {
     /** Path with query VALUES dropped and keys kept: /search?q={q} */
     urlPath: string;
     title?: string;
     regions: SnapshotRegion[];
     links: SnapshotLink[];
+    /** Off-site origins this page links to. Absent from older extension builds. */
+    externalLinks?: SnapshotExternalLink[];
     /** Structural text only — headings, control names, link labels, item titles. */
     contentMd?: string;
     /** How the agent arrived here, when known. */

package/dist/personal-data.d.ts

@@ -0,0 +1,37 @@
+/** A payment card, verified by Luhn. */
+export declare function isLuhnValid(digits: string): boolean;
+/**
+ * An IBAN, verified mod-97.
+ *
+ * The four leading characters move to the end, letters become numbers, and the
+ * whole thing modulo 97 must be 1. A string that satisfies that is an IBAN; the
+ * odds of a product code doing so by accident are one in ninety-seven.
+ */
+export declare function looksLikeIban(value: string): boolean;
+/**
+ * A US bank routing number, verified by its ABA check digit.
+ *
+ * Nine digits alone say nothing. This weighting is what a bank uses to reject a
+ * mistyped number, and it rejects roughly nine in ten arbitrary sequences.
+ */
+export declare function looksLikeRoutingNumber(value: string): boolean;
+/** Whether a single value is personal on its own evidence. */
+export declare function isSensitiveValue(value: string): boolean;
+/**
+ * Free text with every recognised personal value replaced.
+ *
+ * Ordered so the most specific rules run first: a card number inside an address
+ * line should be removed as a card, not left behind by a street rule that
+ * matched around it.
+ */
+export declare function redactSensitiveText(text: string, placeholder: string): string;
+/** What a removed value becomes. A string, so an inferred shape is unchanged. */
+export declare const REDACTED = "[redacted]";
+/**
+ * Free text with every recognisable personal value removed.
+ *
+ * The one entry point both sides use: page markdown on its way to the shared
+ * graph, and a user's retained request on its way to the database.
+ */
+export declare function redactPersonalText(text: string): string;
+export declare function redactPersonalText(text: string | undefined): string | undefined;

package/dist/personal-data.js

@@ -0,0 +1,166 @@
+// Recognising a personal value by its SHAPE, not by what a site called it.
+//
+// Shared rather than browser-only, because the two sides need the same answer.
+// The extension redacts what it sends; the server redacts what it KEEPS — a
+// user's typed request has to arrive intact for the agent to act on it, and
+// nothing says the copy retained afterwards must still hold their address.
+// One recogniser, so those two decisions cannot drift apart.
+//
+// Field names are a losing game on their own: a card arrives as `pan`, `cc1` or
+// `number`, and page text has no field names at all. What travels is a body, a
+// URL, the rendered text of the page and the user's own words — and prose is
+// where an order confirmation prints a delivery address that no name list will
+// ever see.
+//
+// Every rule here is CHECKSUMMED or strongly structured, and that is the whole
+// design. A redactor that guesses destroys the content the corpus exists to
+// hold: nine digits are a routing number, an order id, a product code and a
+// timestamp, and a rule that cannot tell them apart is worse than no rule,
+// because it quietly empties the corpus while claiming to protect someone.
+//
+// So: IBAN and routing numbers are verified by their own check digits, cards by
+// Luhn, and the patterns without a checksum (address, ZIP, name) require
+// context a false positive does not have.
+/** An IBAN: country, check digits, then the account, verified mod-97. */
+const IBAN_CANDIDATE = /\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b/g;
+/** Nine digits: a US routing number, or a great many other things. */
+const ROUTING_CANDIDATE = /\b\d{9}\b/g;
+/**
+ * A US SSN, hyphenated only.
+ *
+ * Bare nine digits are deliberately NOT matched: that is an order number as
+ * often as a person, and the hyphens are what make the intent unambiguous.
+ * The excluded ranges are the ones the SSA never issues, which removes the
+ * bulk of lookalike sequences.
+ */
+const SSN_PATTERN = /\b(?!000|666|9\d\d)\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/g;
+/**
+ * A phone number that was WRITTEN as one.
+ *
+ * Separators, parentheses or a country code are required. A bare run of ten
+ * digits is an order id, a SKU or a tracking number far more often than a
+ * phone, and redacting those would gut ordinary commerce pages.
+ */
+const PHONE_PATTERN = /(?:\+\d{1,3}[ .-]?)?(?:\(\d{3}\)[ .-]?|\b\d{3}[ .-])\d{3}[ .-]\d{4}\b/g;
+/** Street suffixes, spelled out or abbreviated. */
+const STREET_SUFFIX = "street|st|avenue|ave|road|rd|boulevard|blvd|lane|ln|drive|dr|court|ct|way|terrace|ter|place|pl|circle|cir|parkway|pkwy|highway|hwy|square|sq";
+/**
+ * A street address: a building number, a name, and a suffix.
+ *
+ * The suffix is what carries the precision. "123 Main Street" is an address;
+ * "123 Main" is a heading, a product name or half a sentence, and requiring the
+ * suffix is what separates them without a dictionary of street names.
+ */
+const STREET_PATTERN = new RegExp(String.raw `\b\d{1,6}\s+(?:[A-Za-z0-9.'-]+\s+){0,4}(?:${STREET_SUFFIX})\b\.?`, "gi");
+/**
+ * A postal code, but only where the page says it is one.
+ *
+ * Five bare digits are a price, a year, a quantity and a part number. The
+ * context words are what make it an address — "Shipping to 94122" on a search
+ * page is the user's own location, printed by the site for them alone.
+ */
+const CONTEXTUAL_POSTAL_PATTERN = /((?:zip|postal\s*code|ship(?:ping|s|ped)?\s*to|deliver(?:y|ed)?\s*to|located\s*in|(?:mi|miles|km)\s*from)\W{0,12})(\d{5}(?:-\d{4})?)\b/gi;
+/**
+ * The name a page greets the signed-in user by.
+ *
+ * Names cannot be found in prose in general, and trying would ruin the text.
+ * A greeting is the exception: "Hi John!" is not a sentence about a person, it
+ * is the site telling us whose session this is — which is exactly the fact that
+ * must not travel. eBay's header prints it on every page.
+ */
+const GREETING_PATTERN = /\b([Hh]i|[Hh]ello|[Hh]ey|[Ww]elcome\s+back|[Ss]igned\s+in\s+as|[Ll]ogged\s+in\s+as|[Gg]ood\s+(?:morning|afternoon|evening))([,!]?\s+)([A-Z][a-z]{1,20})\b/g;
+/** A payment card, verified by Luhn. */
+export function isLuhnValid(digits) {
+    if (!/^\d{13,19}$/.test(digits))
+        return false;
+    let sum = 0;
+    let double = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let d = digits.charCodeAt(i) - 48;
+        if (double) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        double = !double;
+    }
+    return sum % 10 === 0;
+}
+/**
+ * An IBAN, verified mod-97.
+ *
+ * The four leading characters move to the end, letters become numbers, and the
+ * whole thing modulo 97 must be 1. A string that satisfies that is an IBAN; the
+ * odds of a product code doing so by accident are one in ninety-seven.
+ */
+export function looksLikeIban(value) {
+    const compact = value.replace(/\s/g, "").toUpperCase();
+    if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(compact))
+        return false;
+    const rearranged = compact.slice(4) + compact.slice(0, 4);
+    let remainder = 0;
+    for (const ch of rearranged) {
+        const digits = ch >= "A" && ch <= "Z" ? String(ch.charCodeAt(0) - 55) : ch;
+        for (const d of digits)
+            remainder = (remainder * 10 + (d.charCodeAt(0) - 48)) % 97;
+    }
+    return remainder === 1;
+}
+/**
+ * A US bank routing number, verified by its ABA check digit.
+ *
+ * Nine digits alone say nothing. This weighting is what a bank uses to reject a
+ * mistyped number, and it rejects roughly nine in ten arbitrary sequences.
+ */
+export function looksLikeRoutingNumber(value) {
+    const d = value.replace(/[\s-]/g, "");
+    if (!/^\d{9}$/.test(d))
+        return false;
+    const n = [...d].map(c => c.charCodeAt(0) - 48);
+    const sum = 3 * (n[0] + n[3] + n[6]) + 7 * (n[1] + n[4] + n[7]) + (n[2] + n[5] + n[8]);
+    return sum % 10 === 0 && sum > 0;
+}
+/** Whether a single value is personal on its own evidence. */
+export function isSensitiveValue(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return false;
+    if (isLuhnValid(trimmed.replace(/[ -]/g, "")))
+        return true;
+    if (looksLikeIban(trimmed))
+        return true;
+    if (looksLikeRoutingNumber(trimmed))
+        return true;
+    SSN_PATTERN.lastIndex = 0;
+    return SSN_PATTERN.test(trimmed);
+}
+/**
+ * Free text with every recognised personal value replaced.
+ *
+ * Ordered so the most specific rules run first: a card number inside an address
+ * line should be removed as a card, not left behind by a street rule that
+ * matched around it.
+ */
+export function redactSensitiveText(text, placeholder) {
+    return text
+        .replace(/\b\d(?:[ -]?\d){12,18}\b/g, m => (isLuhnValid(m.replace(/[ -]/g, "")) ? placeholder : m))
+        .replace(IBAN_CANDIDATE, m => (looksLikeIban(m) ? placeholder : m))
+        .replace(SSN_PATTERN, placeholder)
+        .replace(ROUTING_CANDIDATE, m => (looksLikeRoutingNumber(m) ? placeholder : m))
+        .replace(PHONE_PATTERN, placeholder)
+        .replace(STREET_PATTERN, placeholder)
+        // The context word is kept and only the value replaced: "Shipping to
+        // [redacted]" still tells a reader what the page was doing there.
+        .replace(CONTEXTUAL_POSTAL_PATTERN, (_m, lead) => `${lead}${placeholder}`)
+        .replace(GREETING_PATTERN, (_m, greet, gap) => `${greet}${gap}${placeholder}`);
+}
+/** What a removed value becomes. A string, so an inferred shape is unchanged. */
+export const REDACTED = "[redacted]";
+/** An email anywhere in free text. */
+const EMAIL_PATTERN = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+export function redactPersonalText(text) {
+    if (!text)
+        return text;
+    return redactSensitiveText(text.replace(EMAIL_PATTERN, REDACTED), REDACTED);
+}

package/dist/personal-data.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/personal-data.test.js

@@ -0,0 +1,103 @@
+import { test, expect } from "bun:test";
+import { isLuhnValid, isSensitiveValue, looksLikeIban, looksLikeRoutingNumber, redactPersonalText, redactSensitiveText, } from "./personal-data";
+const R = "[redacted]";
+const redact = (text) => redactSensitiveText(text, R);
+// --- checksummed: financial -------------------------------------------------
+test("an IBAN is recognised by its own check digits", () => {
+    expect(looksLikeIban("GB82 WEST 1234 5698 7654 32")).toBe(true);
+    expect(looksLikeIban("DE89370400440532013000")).toBe(true);
+});
+test("a string shaped like an IBAN but failing mod-97 is left alone", () => {
+    // The odds of a product code passing by accident are one in ninety-seven,
+    // which is what makes the rule safe to run over an entire page.
+    expect(looksLikeIban("GB82WEST12345698765433")).toBe(false);
+    expect(looksLikeIban("US12ORDERNUMBER1234567")).toBe(false);
+});
+test("a routing number is recognised by its ABA check digit", () => {
+    expect(looksLikeRoutingNumber("021000021")).toBe(true); // JPMorgan Chase
+    expect(looksLikeRoutingNumber("011401533")).toBe(true); // Bank of America
+});
+test("nine digits that are not a routing number survive", () => {
+    // Nine digits are an order id far more often than a bank. Redacting them all
+    // would empty the corpus while protecting nobody.
+    expect(looksLikeRoutingNumber("123456789")).toBe(false);
+    expect(looksLikeRoutingNumber("987654321")).toBe(false);
+});
+test("a card is recognised by Luhn wherever it hides", () => {
+    expect(isLuhnValid("4111111111111111")).toBe(true);
+    expect(isLuhnValid("4111111111111112")).toBe(false);
+});
+// --- text: what actually appeared on the page -------------------------------
+test("removes the name a site greets the user by", () => {
+    // eBay prints this in the header of every page, and the whole page text was
+    // being sent as evidence when an action was blocked.
+    expect(redact("Hi John! Deals Brand Outlet")).toBe(`Hi ${R}! Deals Brand Outlet`);
+    expect(redact("Welcome back, Sarah")).toBe(`Welcome back, ${R}`);
+});
+test("removes a postal code the page says is a postal code", () => {
+    expect(redact("Shipping to 94122")).toBe(`Shipping to ${R}`);
+    expect(redact("Zip 10001-1234")).toBe(`Zip ${R}`);
+});
+test("leaves five bare digits alone", () => {
+    // A price, a year, a quantity, a part number. Without the context word there
+    // is nothing to say this is anyone's address.
+    expect(redact("Only 94122 units sold")).toBe("Only 94122 units sold");
+    expect(redact("$12345 or best offer")).toBe("$12345 or best offer");
+});
+test("removes a street address", () => {
+    expect(redact("Ship to 1600 Amphitheatre Parkway")).toContain(R);
+    expect(redact("742 Evergreen Terrace")).toBe(R);
+});
+test("leaves a house number with no street suffix alone", () => {
+    // "123 Main" is a heading or half a sentence; the suffix is what makes an
+    // address an address without a dictionary of every street name.
+    expect(redact("123 Main")).toBe("123 Main");
+    expect(redact("2000 watts of power")).toBe("2000 watts of power");
+});
+test("removes a written phone number but not an order id", () => {
+    expect(redact("call (415) 555-1234 now")).toBe(`call ${R} now`);
+    expect(redact("+1 415-555-1234")).toBe(R);
+    // Ten bare digits: a tracking number as often as a phone.
+    expect(redact("Tracking 4155551234")).toBe("Tracking 4155551234");
+});
+test("removes an SSN only when written as one", () => {
+    expect(redact("SSN 123-45-6789")).toBe(`SSN ${R}`);
+    // Ranges the SSA never issues, so a lookalike sequence is not a person.
+    expect(redact("000-45-6789")).toBe("000-45-6789");
+    // Bare nine digits stay: that is an order number as often as a person.
+    expect(redact("Order 123456789")).toBe("Order 123456789");
+});
+test("removes a card number from prose", () => {
+    expect(redact("paid with 4111 1111 1111 1111 today")).toBe(`paid with ${R} today`);
+});
+test("keeps ordinary listing text untouched", () => {
+    // The corpus this protects is also the corpus the graph exists to hold.
+    const listing = "Microsoft Surface Pro 9 13in Touch i7 12th Gen 16GB RAM 256GB SSD Win11H Black " +
+        "$520.00 or Best Offer Free delivery Located in United States 99.1% positive (147)";
+    expect(redact(listing)).toBe(listing);
+});
+// --- values -----------------------------------------------------------------
+test("judges a single value on its own evidence", () => {
+    expect(isSensitiveValue("4111111111111111")).toBe(true);
+    expect(isSensitiveValue("GB82 WEST 1234 5698 7654 32")).toBe(true);
+    expect(isSensitiveValue("021000021")).toBe(true);
+    expect(isSensitiveValue("123-45-6789")).toBe(true);
+    expect(isSensitiveValue("Surface Pro 9")).toBe(false);
+    expect(isSensitiveValue("")).toBe(false);
+});
+test("removes a postal code phrased as a distance", () => {
+    // The same postcode survived under different wording: eBay prints "Shipping
+    // to 94122" in one place and "15 mi from 94122" in another, and protecting
+    // only the first phrasing protects nobody.
+    expect(redact("Free pickup: 15 mi from 94122")).toBe(`Free pickup: 15 mi from ${R}`);
+    // Still not a bare number: "from 12345 reviews" is not an address.
+    expect(redact("from 12345 reviews")).toBe("from 12345 reviews");
+});
+test("redactPersonalText is the one entry point both sides use", () => {
+    // The extension redacts what it SENDS; the server redacts what it KEEPS.
+    // One recogniser, so the two cannot drift apart.
+    expect(redactPersonalText("write to me@example.com")).toBe(`write to ${R}`);
+    expect(redactPersonalText("Order this and ship to 1600 Amphitheatre Parkway")).toContain(R);
+    expect(redactPersonalText("Find Apple Lisa computer for sale")).toBe("Find Apple Lisa computer for sale");
+    expect(redactPersonalText(undefined)).toBeUndefined();
+});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sudobility/sider_types",
-	"version": "0.0.10",
+	"version": "0.0.12",
 	"description": "Shared domain types for Sider — AI assistance for generic web apps.",
 	"license": "BUSL-1.1",
 	"publishConfig": {
@@ -15,9 +15,11 @@
 	],
 	"scripts": {
 		"build": "tsc -p tsconfig.json",
-		"typecheck": "tsc --noEmit"
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
 	},
 	"devDependencies": {
+		"@types/bun": "^1.3.14",
 		"typescript": "^5.9.3"
 	}
 }

package/src/index.ts

@@ -12,5 +12,6 @@ export * from "./local";
 export * from "./api";
 export * from "./actions";
 export * from "./templating";
+export * from "./personal-data";
 export * from "./recipe-hash";
 export * from "./observe";

package/src/observe.ts

@@ -35,12 +35,28 @@ export interface SnapshotLink {
   label?: string;
 }
 
+/**
+ * An anchor on the page pointing at a DIFFERENT origin.
+ *
+ * Kept apart from `SnapshotLink` on purpose: `links` feeds view identity and the
+ * graph's declared transitions, and a cross-origin entry there would churn every
+ * view signature. This is evidence of one thing only — that this site offers a
+ * way to reach that one.
+ */
+export interface SnapshotExternalLink {
+  origin: string;
+  /** Visible text of the link, e.g. "Careers at USF". */
+  label?: string;
+}
+
 export interface PageSnapshot {
   /** Path with query VALUES dropped and keys kept: /search?q={q} */
   urlPath: string;
   title?: string;
   regions: SnapshotRegion[];
   links: SnapshotLink[];
+  /** Off-site origins this page links to. Absent from older extension builds. */
+  externalLinks?: SnapshotExternalLink[];
   /** Structural text only — headings, control names, link labels, item titles. */
   contentMd?: string;
   /** How the agent arrived here, when known. */

package/src/personal-data.test.ts

@@ -0,0 +1,132 @@
+import { test, expect } from "bun:test";
+import {
+  isLuhnValid,
+  isSensitiveValue,
+  looksLikeIban,
+  looksLikeRoutingNumber,
+  redactPersonalText,
+  redactSensitiveText,
+} from "./personal-data";
+
+const R = "[redacted]";
+const redact = (text: string) => redactSensitiveText(text, R);
+
+// --- checksummed: financial -------------------------------------------------
+
+test("an IBAN is recognised by its own check digits", () => {
+  expect(looksLikeIban("GB82 WEST 1234 5698 7654 32")).toBe(true);
+  expect(looksLikeIban("DE89370400440532013000")).toBe(true);
+});
+
+test("a string shaped like an IBAN but failing mod-97 is left alone", () => {
+  // The odds of a product code passing by accident are one in ninety-seven,
+  // which is what makes the rule safe to run over an entire page.
+  expect(looksLikeIban("GB82WEST12345698765433")).toBe(false);
+  expect(looksLikeIban("US12ORDERNUMBER1234567")).toBe(false);
+});
+
+test("a routing number is recognised by its ABA check digit", () => {
+  expect(looksLikeRoutingNumber("021000021")).toBe(true); // JPMorgan Chase
+  expect(looksLikeRoutingNumber("011401533")).toBe(true); // Bank of America
+});
+
+test("nine digits that are not a routing number survive", () => {
+  // Nine digits are an order id far more often than a bank. Redacting them all
+  // would empty the corpus while protecting nobody.
+  expect(looksLikeRoutingNumber("123456789")).toBe(false);
+  expect(looksLikeRoutingNumber("987654321")).toBe(false);
+});
+
+test("a card is recognised by Luhn wherever it hides", () => {
+  expect(isLuhnValid("4111111111111111")).toBe(true);
+  expect(isLuhnValid("4111111111111112")).toBe(false);
+});
+
+// --- text: what actually appeared on the page -------------------------------
+
+test("removes the name a site greets the user by", () => {
+  // eBay prints this in the header of every page, and the whole page text was
+  // being sent as evidence when an action was blocked.
+  expect(redact("Hi John! Deals Brand Outlet")).toBe(`Hi ${R}! Deals Brand Outlet`);
+  expect(redact("Welcome back, Sarah")).toBe(`Welcome back, ${R}`);
+});
+
+test("removes a postal code the page says is a postal code", () => {
+  expect(redact("Shipping to 94122")).toBe(`Shipping to ${R}`);
+  expect(redact("Zip 10001-1234")).toBe(`Zip ${R}`);
+});
+
+test("leaves five bare digits alone", () => {
+  // A price, a year, a quantity, a part number. Without the context word there
+  // is nothing to say this is anyone's address.
+  expect(redact("Only 94122 units sold")).toBe("Only 94122 units sold");
+  expect(redact("$12345 or best offer")).toBe("$12345 or best offer");
+});
+
+test("removes a street address", () => {
+  expect(redact("Ship to 1600 Amphitheatre Parkway")).toContain(R);
+  expect(redact("742 Evergreen Terrace")).toBe(R);
+});
+
+test("leaves a house number with no street suffix alone", () => {
+  // "123 Main" is a heading or half a sentence; the suffix is what makes an
+  // address an address without a dictionary of every street name.
+  expect(redact("123 Main")).toBe("123 Main");
+  expect(redact("2000 watts of power")).toBe("2000 watts of power");
+});
+
+test("removes a written phone number but not an order id", () => {
+  expect(redact("call (415) 555-1234 now")).toBe(`call ${R} now`);
+  expect(redact("+1 415-555-1234")).toBe(R);
+  // Ten bare digits: a tracking number as often as a phone.
+  expect(redact("Tracking 4155551234")).toBe("Tracking 4155551234");
+});
+
+test("removes an SSN only when written as one", () => {
+  expect(redact("SSN 123-45-6789")).toBe(`SSN ${R}`);
+  // Ranges the SSA never issues, so a lookalike sequence is not a person.
+  expect(redact("000-45-6789")).toBe("000-45-6789");
+  // Bare nine digits stay: that is an order number as often as a person.
+  expect(redact("Order 123456789")).toBe("Order 123456789");
+});
+
+test("removes a card number from prose", () => {
+  expect(redact("paid with 4111 1111 1111 1111 today")).toBe(`paid with ${R} today`);
+});
+
+test("keeps ordinary listing text untouched", () => {
+  // The corpus this protects is also the corpus the graph exists to hold.
+  const listing =
+    "Microsoft Surface Pro 9 13in Touch i7 12th Gen 16GB RAM 256GB SSD Win11H Black " +
+    "$520.00 or Best Offer Free delivery Located in United States 99.1% positive (147)";
+  expect(redact(listing)).toBe(listing);
+});
+
+// --- values -----------------------------------------------------------------
+
+test("judges a single value on its own evidence", () => {
+  expect(isSensitiveValue("4111111111111111")).toBe(true);
+  expect(isSensitiveValue("GB82 WEST 1234 5698 7654 32")).toBe(true);
+  expect(isSensitiveValue("021000021")).toBe(true);
+  expect(isSensitiveValue("123-45-6789")).toBe(true);
+  expect(isSensitiveValue("Surface Pro 9")).toBe(false);
+  expect(isSensitiveValue("")).toBe(false);
+});
+
+test("removes a postal code phrased as a distance", () => {
+  // The same postcode survived under different wording: eBay prints "Shipping
+  // to 94122" in one place and "15 mi from 94122" in another, and protecting
+  // only the first phrasing protects nobody.
+  expect(redact("Free pickup: 15 mi from 94122")).toBe(`Free pickup: 15 mi from ${R}`);
+  // Still not a bare number: "from 12345 reviews" is not an address.
+  expect(redact("from 12345 reviews")).toBe("from 12345 reviews");
+});
+
+test("redactPersonalText is the one entry point both sides use", () => {
+  // The extension redacts what it SENDS; the server redacts what it KEEPS.
+  // One recogniser, so the two cannot drift apart.
+  expect(redactPersonalText("write to me@example.com")).toBe(`write to ${R}`);
+  expect(redactPersonalText("Order this and ship to 1600 Amphitheatre Parkway")).toContain(R);
+  expect(redactPersonalText("Find Apple Lisa computer for sale")).toBe("Find Apple Lisa computer for sale");
+  expect(redactPersonalText(undefined)).toBeUndefined();
+});

package/src/personal-data.ts

@@ -0,0 +1,189 @@
+// Recognising a personal value by its SHAPE, not by what a site called it.
+//
+// Shared rather than browser-only, because the two sides need the same answer.
+// The extension redacts what it sends; the server redacts what it KEEPS — a
+// user's typed request has to arrive intact for the agent to act on it, and
+// nothing says the copy retained afterwards must still hold their address.
+// One recogniser, so those two decisions cannot drift apart.
+//
+// Field names are a losing game on their own: a card arrives as `pan`, `cc1` or
+// `number`, and page text has no field names at all. What travels is a body, a
+// URL, the rendered text of the page and the user's own words — and prose is
+// where an order confirmation prints a delivery address that no name list will
+// ever see.
+//
+// Every rule here is CHECKSUMMED or strongly structured, and that is the whole
+// design. A redactor that guesses destroys the content the corpus exists to
+// hold: nine digits are a routing number, an order id, a product code and a
+// timestamp, and a rule that cannot tell them apart is worse than no rule,
+// because it quietly empties the corpus while claiming to protect someone.
+//
+// So: IBAN and routing numbers are verified by their own check digits, cards by
+// Luhn, and the patterns without a checksum (address, ZIP, name) require
+// context a false positive does not have.
+
+/** An IBAN: country, check digits, then the account, verified mod-97. */
+const IBAN_CANDIDATE = /\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b/g;
+
+/** Nine digits: a US routing number, or a great many other things. */
+const ROUTING_CANDIDATE = /\b\d{9}\b/g;
+
+/**
+ * A US SSN, hyphenated only.
+ *
+ * Bare nine digits are deliberately NOT matched: that is an order number as
+ * often as a person, and the hyphens are what make the intent unambiguous.
+ * The excluded ranges are the ones the SSA never issues, which removes the
+ * bulk of lookalike sequences.
+ */
+const SSN_PATTERN = /\b(?!000|666|9\d\d)\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/g;
+
+/**
+ * A phone number that was WRITTEN as one.
+ *
+ * Separators, parentheses or a country code are required. A bare run of ten
+ * digits is an order id, a SKU or a tracking number far more often than a
+ * phone, and redacting those would gut ordinary commerce pages.
+ */
+const PHONE_PATTERN =
+  /(?:\+\d{1,3}[ .-]?)?(?:\(\d{3}\)[ .-]?|\b\d{3}[ .-])\d{3}[ .-]\d{4}\b/g;
+
+/** Street suffixes, spelled out or abbreviated. */
+const STREET_SUFFIX =
+  "street|st|avenue|ave|road|rd|boulevard|blvd|lane|ln|drive|dr|court|ct|way|terrace|ter|place|pl|circle|cir|parkway|pkwy|highway|hwy|square|sq";
+
+/**
+ * A street address: a building number, a name, and a suffix.
+ *
+ * The suffix is what carries the precision. "123 Main Street" is an address;
+ * "123 Main" is a heading, a product name or half a sentence, and requiring the
+ * suffix is what separates them without a dictionary of street names.
+ */
+const STREET_PATTERN = new RegExp(
+  String.raw`\b\d{1,6}\s+(?:[A-Za-z0-9.'-]+\s+){0,4}(?:${STREET_SUFFIX})\b\.?`,
+  "gi",
+);
+
+/**
+ * A postal code, but only where the page says it is one.
+ *
+ * Five bare digits are a price, a year, a quantity and a part number. The
+ * context words are what make it an address — "Shipping to 94122" on a search
+ * page is the user's own location, printed by the site for them alone.
+ */
+const CONTEXTUAL_POSTAL_PATTERN =
+  /((?:zip|postal\s*code|ship(?:ping|s|ped)?\s*to|deliver(?:y|ed)?\s*to|located\s*in|(?:mi|miles|km)\s*from)\W{0,12})(\d{5}(?:-\d{4})?)\b/gi;
+
+/**
+ * The name a page greets the signed-in user by.
+ *
+ * Names cannot be found in prose in general, and trying would ruin the text.
+ * A greeting is the exception: "Hi John!" is not a sentence about a person, it
+ * is the site telling us whose session this is — which is exactly the fact that
+ * must not travel. eBay's header prints it on every page.
+ */
+const GREETING_PATTERN =
+  /\b([Hh]i|[Hh]ello|[Hh]ey|[Ww]elcome\s+back|[Ss]igned\s+in\s+as|[Ll]ogged\s+in\s+as|[Gg]ood\s+(?:morning|afternoon|evening))([,!]?\s+)([A-Z][a-z]{1,20})\b/g;
+
+/** A payment card, verified by Luhn. */
+export function isLuhnValid(digits: string): boolean {
+  if (!/^\d{13,19}$/.test(digits)) return false;
+  let sum = 0;
+  let double = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let d = digits.charCodeAt(i) - 48;
+    if (double) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    double = !double;
+  }
+  return sum % 10 === 0;
+}
+
+/**
+ * An IBAN, verified mod-97.
+ *
+ * The four leading characters move to the end, letters become numbers, and the
+ * whole thing modulo 97 must be 1. A string that satisfies that is an IBAN; the
+ * odds of a product code doing so by accident are one in ninety-seven.
+ */
+export function looksLikeIban(value: string): boolean {
+  const compact = value.replace(/\s/g, "").toUpperCase();
+  if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(compact)) return false;
+
+  const rearranged = compact.slice(4) + compact.slice(0, 4);
+  let remainder = 0;
+  for (const ch of rearranged) {
+    const digits = ch >= "A" && ch <= "Z" ? String(ch.charCodeAt(0) - 55) : ch;
+    for (const d of digits) remainder = (remainder * 10 + (d.charCodeAt(0) - 48)) % 97;
+  }
+  return remainder === 1;
+}
+
+/**
+ * A US bank routing number, verified by its ABA check digit.
+ *
+ * Nine digits alone say nothing. This weighting is what a bank uses to reject a
+ * mistyped number, and it rejects roughly nine in ten arbitrary sequences.
+ */
+export function looksLikeRoutingNumber(value: string): boolean {
+  const d = value.replace(/[\s-]/g, "");
+  if (!/^\d{9}$/.test(d)) return false;
+  const n = [...d].map(c => c.charCodeAt(0) - 48);
+  const sum =
+    3 * (n[0]! + n[3]! + n[6]!) + 7 * (n[1]! + n[4]! + n[7]!) + (n[2]! + n[5]! + n[8]!);
+  return sum % 10 === 0 && sum > 0;
+}
+
+/** Whether a single value is personal on its own evidence. */
+export function isSensitiveValue(value: string): boolean {
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  if (isLuhnValid(trimmed.replace(/[ -]/g, ""))) return true;
+  if (looksLikeIban(trimmed)) return true;
+  if (looksLikeRoutingNumber(trimmed)) return true;
+  SSN_PATTERN.lastIndex = 0;
+  return SSN_PATTERN.test(trimmed);
+}
+
+/**
+ * Free text with every recognised personal value replaced.
+ *
+ * Ordered so the most specific rules run first: a card number inside an address
+ * line should be removed as a card, not left behind by a street rule that
+ * matched around it.
+ */
+export function redactSensitiveText(text: string, placeholder: string): string {
+  return text
+    .replace(/\b\d(?:[ -]?\d){12,18}\b/g, m => (isLuhnValid(m.replace(/[ -]/g, "")) ? placeholder : m))
+    .replace(IBAN_CANDIDATE, m => (looksLikeIban(m) ? placeholder : m))
+    .replace(SSN_PATTERN, placeholder)
+    .replace(ROUTING_CANDIDATE, m => (looksLikeRoutingNumber(m) ? placeholder : m))
+    .replace(PHONE_PATTERN, placeholder)
+    .replace(STREET_PATTERN, placeholder)
+    // The context word is kept and only the value replaced: "Shipping to
+    // [redacted]" still tells a reader what the page was doing there.
+    .replace(CONTEXTUAL_POSTAL_PATTERN, (_m, lead: string) => `${lead}${placeholder}`)
+    .replace(GREETING_PATTERN, (_m, greet: string, gap: string) => `${greet}${gap}${placeholder}`);
+}
+
+/** What a removed value becomes. A string, so an inferred shape is unchanged. */
+export const REDACTED = "[redacted]";
+
+/** An email anywhere in free text. */
+const EMAIL_PATTERN = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+
+/**
+ * Free text with every recognisable personal value removed.
+ *
+ * The one entry point both sides use: page markdown on its way to the shared
+ * graph, and a user's retained request on its way to the database.
+ */
+export function redactPersonalText(text: string): string;
+export function redactPersonalText(text: string | undefined): string | undefined;
+export function redactPersonalText(text: string | undefined): string | undefined {
+  if (!text) return text;
+  return redactSensitiveText(text.replace(EMAIL_PATTERN, REDACTED), REDACTED);
+}