safeseed 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SafeSeed contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# SafeSeed
+
+**Confirmably-synthetic test data by construction.** Generate stand-in data for test, CI, and demo environments from ranges that published standards have reserved as *permanently not real*, bind a tamper-evident record to the output, verify a file stays in range, and scan data you already have for real PII that slipped in.
+
+No model, no training data, no backend, no accounts, no telemetry, zero runtime dependencies. It runs entirely on your machine. MIT licensed.
+
+> SafeSeed makes *"no production data crossed this boundary"* a property you can audit once and enforce on every run — and it tells you, in writing, exactly where that guarantee ends. The full argument is in [docs/safe-test-data-by-construction.md](docs/safe-test-data-by-construction.md).
+
+---
+
+## Why this exists
+
+The breaches teams plan for involve production. The ones that actually happen often involve a *copy* of production sitting somewhere nobody hardened: a staging database, a CI job's fixtures, a developer's laptop, a screenshot in a bug ticket. The fix everyone agrees on is "don't put real data there, use synthetic data." The disagreement is about what "synthetic" should mean.
+
+Most synthetic-data tools **learn the shape of your real data from your real data**, so the output can memorize and re-emit real records, and privacy becomes something you defend *after the fact* (membership-inference tests, differential-privacy noise, a privacy report) on every dataset, forever.
+
+SafeSeed takes the other path: **never let real data into the process at all.** Each field is drawn from values a standard reserves as non-real. If the source data never touches the generator, there is no real record for it to memorize or re-emit — not because you defended it after the fact, but because the input was never there. You audit a few hundred cited lines once, and every output inherits the guarantee. (This is the argument against model memorization; the structurally-fake tier still carries the coincidence caveat below.)
+
+## What it does
+
+1. **Generate** safe-by-construction test data from the cited reserved ranges (deterministic from a seed, so the output is a committable fixture).
+2. **Attest** with a tamper-evident run record that binds to the file's content hash and states the honesty tier of every field.
+3. **Verify** that a file is still byte-for-byte the generated one *and* that every value is still in range — wire it into CI to fail the build on drift. Strict by default; opt into **column-scoped verify** (`--allow-added-columns`) to attest only the synthetic columns you generated, so a team can add its own business columns (job title, industry) without breaking attestation — added columns are reported as *unattested*, never a silent pass.
+4. **Scan** an *existing* CSV / seed file and flag values that are not in reserved ranges as candidate real PII. Column-scoped verify pairs with scan: verify vouches for the synthetic columns, scan checks the columns you added.
+
+`verify` and `scan` are **generator-agnostic**: they work on any data file, however it was produced, so you can keep the generator you already use and wrap it.
+
+There is also a self-serve **generator page** (browser, zero network): pick fields and types, set rows and seed, preview the tier-colored output, and download the CSV plus its run record. It ships as a committed offline single file at [`demo/safeseed-generator.html`](demo/safeseed-generator.html).
+
+## Quickstart
+
+### CLI
+
+```bash
+# Generate 100 rows of safe data + a run record
+safeseed generate \
+  --fields email:email,name:fullName,phone:phone,ssn:ssn,card:creditCard \
+  --rows 100 --seed 42 \
+  --out data.csv --record record.json
+
+# Fail the build if the file drifts out of range or was tampered with
+safeseed verify --in data.csv --record record.json     # exit 0 clean, 1 on drift
+
+# Column-scoped: attest the synthetic columns, allow + report added business columns
+safeseed verify --in data.csv --record record.json --allow-added-columns
+
+# Scan a legacy file for real PII that slipped in
+safeseed scan --in legacy.csv --fields email:email,phone:phone,ssn:ssn
+
+# Inspect the reserved-range catalog (every field's range, citation, and tier)
+safeseed catalog
+```
+
+### As a CI gate (GitHub Action)
+
+```yaml
+- uses: <org>/safeseed@v0      # the verify Action
+  with:
+    data: fixtures/seed.csv
+    record: fixtures/seed.record.json
+    # allow-added-columns: true   # optional: column-scoped verify (attest synthetic columns,
+    #                             # report added business columns instead of failing)
+```
+
+### As a library
+
+```ts
+import { generate, toCsv, makeRunRecord, verify, scan } from "safeseed";
+
+const ds = generate({
+  schema: [
+    { name: "email", type: "email" },
+    { name: "phone", type: "phone" },
+  ],
+  rows: 100,
+  seed: 42,
+});
+const csv = toCsv(ds.columns, ds.rows);
+const record = await makeRunRecord(ds, csv);
+
+const result = await verify(csv, record); // { ok, failures, checked, unattestedColumns, warnings }
+
+// Column-scoped: attest the synthetic columns only; added columns are reported, not failed.
+const scoped = await verify(extendedCsv, record, { allowAddedColumns: true });
+// scoped.unattestedColumns lists the business columns the team added — scan those.
+```
+
+The library is isomorphic — the same core runs in Node (>=18) and in the browser, using the platform's Web Crypto for hashing.
+
+## The honesty tiers
+
+Honesty is the credibility here, so the claim has tiers, and every field is labeled with its own:
+
+| Tier | What it means | Examples | The claim |
+|---|---|---|---|
+| **provably-non-real** | Reserved by a published standard/protocol; the standard itself makes them non-routable/non-registrable. | RFC 2606 email domains, RFC 5737 / 3849 documentation IPs | "Cannot correspond to a real person or system." |
+| **reserved-not-issued** | Reserved by the *issuing authority* and never assigned — strong, but administrative policy, not protocol. | NANPA `555-01xx` phones, never-issued SSN ranges | "Never assigned, so no real holder has one; non-real by policy, not protocol." |
+| **designated-test-only** | A valid-looking value processors/sandboxes *designate* for testing. It passes validation. | Card test PANs (`4242…`) | "Non-real by designation, **not** by impossibility." |
+| **structurally-fake** | No standard reserves it, so it is made *self-evidently* fake instead of plausible. | `TEST_Lastname_000142`, `123 Example Way` | "Synthetic token; not derived from any real record." |
+
+Stating which tier each field sits in is not a weakness to bury. It is the thing that separates a practitioner from a datasheet.
+
+## What this does **not** prove
+
+The fastest way to lose a security reviewer is to claim more than you can defend. So, on purpose:
+
+- **It attests the generator, not your environment.** "Generated from reserved ranges, no real input" is true at the moment of generation. It says nothing about a file someone later edits, joins against a prod snapshot, or replaces. That is why `verify` re-checks the *actual artifact* (content hash + range), and why the assurance rests on the open, auditable code — a signature proves the tool ran, not that the tool is right. The run record is therefore a **tamper-evident record**, not "cryptographic proof of no PII."
+- **"Not derived from production data" is not "not personal data."** The defensible claim is the former, never the latter.
+- **It is a control, not a scope-out.** A security-of-processing and data-minimization control for non-production environments (GDPR Articles 25 and 32; SOC 2 and ISO 27001 in audit terms). It is not a DSAR answer and not a lawful-basis story.
+- **It is deliberately low-fidelity.** Every phone in one small block, every IP in three ranges. That is correct for "prove there's no real PII in functional and CI tests," and wrong as your general fixture source, your ML training data, or your load-testing input.
+
+## "Why not just use Faker?"
+
+Off-the-shelf fake-data libraries already emit reserved-range values. What is missing is the *discipline* around them: every personal-data field tied to a cited standard, an enforcement check that fails the build when a value drifts out of range, a scan that flags real-looking data already sitting in your test environment, and an honest written statement of exactly what is and isn't guaranteed. That discipline is the contribution. The generator was never the hard part.
+
+(SafeSeed can wrap Faker, by the way: keep it for realistic non-PII fields, and let the cited reserved ranges own every PII-shaped one.)
+
+## Standards referenced
+
+- **RFC 2606** — reserved DNS names (`example.com/.net/.org`, `.test`/`.example`/`.invalid`/`.localhost`).
+- **RFC 5737** — IPv4 documentation blocks (`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`).
+- **RFC 3849** — IPv6 documentation prefix (`2001:db8::/32`).
+- **NANPA / ATIS** — fictitious telephone numbers (`555-0100` through `555-0199`).
+- **SSA SSN randomization** (effective 2011-06-25) — never-assigned ranges (area `000`/`666`/`900-999`, group `00`, serial `0000`), confirmed against the [SSA randomization rules](https://www.ssa.gov/employer/randomization.html).
+- Card numbers are **published processor/sandbox test PANs** (e.g. Stripe testing docs), in the `designated-test-only` tier (they pass Luhn, authorize nowhere).
+
+## Development
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # vitest (the named TDD suite: catalog/generate/verify/scan/record)
+npm run build       # emit dist/ (library + CLI)
+```
+
+The catalog in [`src/catalog.ts`](src/catalog.ts) is the reusable core: it maps each field type to its reserved range, citation, and tier. Generation, verification, and scanning all read from it, which is what makes the promise auditable.
+
+## Status
+
+Core library, CLI, the `verify` Action, and an interactive browser demo are built and tested (64 tests; CI green). SafeSeed 0.2.0 adds per-column hashes and opt-in **column-scoped verify**, a self-serve **generator page**, and a four-tier honesty taxonomy that separates protocol-reserved values from authority-reserved (never-issued) ones. The demo lives in [`demo/`](demo/); both the showcase and the generator ship as committed, offline single files at [`demo/safeseed-demo.html`](demo/safeseed-demo.html) and [`demo/safeseed-generator.html`](demo/safeseed-generator.html). npm publication is the remaining step. The design record is in [SPEC.md](SPEC.md); the v2 feature spec is in [docs/generator-and-column-scoped-verify.md](docs/generator-and-column-scoped-verify.md).
+
+## Support
+
+SafeSeed is free and MIT-licensed. If it's useful to you or your team, you can [support its development on Ko-fi](https://ko-fi.com/Q3S6220HI9).
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/Q3S6220HI9)
+
+## License
+
+[MIT](LICENSE).

package/dist/catalog.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The reserved-range catalog — SafeSeed's reusable core IP.
+ *
+ * Each entry maps a PII-shaped field type to a standards-reserved "never-real"
+ * space, the citation for that reservation, its honesty tier, and the exact
+ * language allowed about it. Generation, verification, and scanning all read from
+ * this one table, which is what makes the promise auditable: review these few
+ * hundred cited lines once, and every output inherits the guarantee.
+ *
+ * Sourcing: the RFC 2606 / 5737 / 3849 reservations and the SSA SSN randomization
+ * exclusions (area 000/666/900-999, group 00, serial 0000) are confirmed against
+ * primary sources. The NANPA 555-0100..0199 fictitious block is well-established;
+ * its shipped citation link is the NANPA homepage rather than a deep rule page.
+ */
+import type { FieldType, Tier } from "./types.js";
+export declare const CATALOG_VERSION = "1.0.0";
+/** Inspectable, structured definition of a reserved space. Drives generation,
+ * verification, and scanning, and lets tests assert the ranges match standards. */
+export type ReservedSpec = {
+    kind: "emailDomains";
+    domains: readonly string[];
+    reservedTlds: readonly string[];
+} | {
+    kind: "domains";
+    domains: readonly string[];
+    reservedTlds: readonly string[];
+} | {
+    kind: "ipv4Blocks";
+    cidrs: readonly string[];
+} | {
+    kind: "ipv6Blocks";
+    cidrs: readonly string[];
+} | {
+    kind: "phoneBlock";
+    centralOfficeCode: string;
+    subscriberStart: number;
+    subscriberEnd: number;
+} | {
+    kind: "ssnInvalid";
+    invalidAreas: readonly string[];
+    invalidAreaMin: number;
+    invalidAreaMax: number;
+    invalidGroup: string;
+    invalidSerial: string;
+} | {
+    kind: "cardTestNumbers";
+    numbers: readonly string[];
+} | {
+    kind: "fakeToken";
+    pattern: string;
+};
+export interface CatalogEntry {
+    field: FieldType;
+    tier: Tier;
+    /** Human-readable citation for the reservation. */
+    citation: string;
+    /** What the reserved space is, in plain words. */
+    description: string;
+    /** Tier-appropriate, non-overclaiming statement about values of this field. */
+    claim: string;
+    reserved: ReservedSpec;
+}
+export declare const CATALOG: readonly CatalogEntry[];
+/** Look up the catalog entry for a field type. Throws if the field is unknown. */
+export declare function getEntry(field: FieldType): CatalogEntry;
+/**
+ * Is `value` inside the reserved range declared for `entry`? This is the single
+ * predicate behind both `verify` (is generated output still in range?) and `scan`
+ * (does existing data contain anything *out* of range, i.e. candidate real PII?).
+ */
+export declare function isReserved(entry: CatalogEntry, value: string): boolean;
+/**
+ * Heuristic used to assert the structurally-fake tier really is self-evident:
+ * a human glancing at the value should see "test data", not a plausible person.
+ */
+export declare function isSelfEvidentlyFake(value: string): boolean;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGlD,eAAO,MAAM,eAAe,UAAU,CAAC;AAEvC;mFACmF;AACnF,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACrF;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAChF;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GACjG;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB,GACD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC;IACX,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,CAAC;CACxB;AAiCD,eAAO,MAAM,OAAO,EAAE,SAAS,YAAY,EAwG1C,CAAC;AAIF,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CAIvD;AAUD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAwCtE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D"}

package/dist/catalog.js

@@ -0,0 +1,203 @@
+import { ipv4InCidr, ipv6InPrefix } from "./net.js";
+export const CATALOG_VERSION = "1.0.0";
+// Tier-appropriate claim language. The strong wording ("cannot correspond to a
+// real person") lives ONLY on the protocol-provable tier; every weaker tier
+// deliberately avoids "proof", "impossible", "guarantee", "cannot be real".
+const CLAIM_PROVABLE = "Reserved by published standard; values in this range cannot correspond to a real person or system.";
+const CLAIM_RESERVED_NOT_ISSUED = "Reserved by the issuing authority and never assigned, so no real holder has one. Non-real by administrative policy rather than by protocol.";
+const CLAIM_DESIGNATED = "Designated test value that passes validation; non-real by processor/sandbox designation, not by construction. Valid-looking, but reserved for testing.";
+const CLAIM_FAKE = "Structurally synthetic token; not derived from any real record. This field type is not reserved by any standard, so realism is deliberately avoided.";
+const RFC2606_DOMAINS = ["example.com", "example.net", "example.org"];
+const RFC2606_TLDS = ["test", "example", "invalid", "localhost"];
+const RFC5737_BLOCKS = ["192.0.2.0/24", "198.51.100.0/24", "203.0.113.0/24"];
+const RFC3849_BLOCKS = ["2001:db8::/32"];
+/** Payment-processor / sandbox test PANs (all Luhn-valid by design; authorize nowhere). */
+const CARD_TEST_NUMBERS = [
+    "4242424242424242", // Visa (widely used sandbox)
+    "4111111111111111", // Visa
+    "4000056655665556", // Visa debit
+    "5555555555554444", // Mastercard
+    "5105105105105100", // Mastercard
+    "2223003122003222", // Mastercard (2-series)
+    "378282246310005", // American Express
+    "371449635398431", // American Express
+    "6011111111111117", // Discover
+    "3530111333300000", // JCB
+];
+export const CATALOG = [
+    {
+        field: "email",
+        tier: "provably-non-real",
+        citation: "RFC 2606 §2–3 (reserved example.com/.net/.org and TLDs .test/.example/.invalid/.localhost)",
+        description: "Email addresses whose domain is an RFC 2606 reserved domain or TLD; can never route to a real mailbox.",
+        claim: CLAIM_PROVABLE,
+        reserved: { kind: "emailDomains", domains: RFC2606_DOMAINS, reservedTlds: RFC2606_TLDS },
+    },
+    {
+        field: "domain",
+        tier: "provably-non-real",
+        citation: "RFC 2606 §2–3 (reserved domains and TLDs)",
+        description: "Hostnames under an RFC 2606 reserved domain or TLD.",
+        claim: CLAIM_PROVABLE,
+        reserved: { kind: "domains", domains: RFC2606_DOMAINS, reservedTlds: RFC2606_TLDS },
+    },
+    {
+        field: "ipv4",
+        tier: "provably-non-real",
+        citation: "RFC 5737 (IPv4 documentation blocks TEST-NET-1/2/3)",
+        description: "IPv4 addresses inside the three RFC 5737 documentation ranges, which per the RFC should not be routed on the public Internet.",
+        claim: CLAIM_PROVABLE,
+        reserved: { kind: "ipv4Blocks", cidrs: RFC5737_BLOCKS },
+    },
+    {
+        field: "ipv6",
+        tier: "provably-non-real",
+        citation: "RFC 3849 (IPv6 documentation prefix 2001:db8::/32)",
+        description: "IPv6 addresses inside the RFC 3849 documentation prefix.",
+        claim: CLAIM_PROVABLE,
+        reserved: { kind: "ipv6Blocks", cidrs: RFC3849_BLOCKS },
+    },
+    {
+        field: "phone",
+        tier: "reserved-not-issued",
+        citation: "NANPA / ATIS fictitious-number assignment (555-0100 through 555-0199)",
+        description: "North American numbers in the 555-01xx fictitious subscriber block, which the numbering authority reserves and never assigns to a real line (administrative reservation, not a protocol limit).",
+        claim: CLAIM_RESERVED_NOT_ISSUED,
+        reserved: { kind: "phoneBlock", centralOfficeCode: "555", subscriberStart: 100, subscriberEnd: 199 },
+    },
+    {
+        field: "ssn",
+        tier: "reserved-not-issued",
+        citation: "SSA SSN randomization (effective 2011-06-25): never-assigned area numbers 000 / 666 / 900-999, plus group 00 and serial 0000 (ssa.gov/employer/randomization.html)",
+        description: "US SSNs whose area, group, or serial falls in a range the SSA never issues — reserved by the issuing authority's own rules rather than by protocol.",
+        claim: CLAIM_RESERVED_NOT_ISSUED,
+        reserved: {
+            kind: "ssnInvalid",
+            invalidAreas: ["000", "666"],
+            invalidAreaMin: 900,
+            invalidAreaMax: 999,
+            invalidGroup: "00",
+            invalidSerial: "0000",
+        },
+    },
+    {
+        field: "creditCard",
+        tier: "designated-test-only",
+        citation: "Payment-processor / sandbox test PANs (e.g. Stripe testing docs); pass Luhn, authorize nowhere",
+        description: "Card numbers processors and sandboxes publish for testing. They pass the Luhn checksum but authorize nowhere, so they are non-real by designation, not by impossibility.",
+        claim: CLAIM_DESIGNATED,
+        reserved: { kind: "cardTestNumbers", numbers: CARD_TEST_NUMBERS },
+    },
+    {
+        field: "firstName",
+        tier: "structurally-fake",
+        citation: "No standard reserves names; structurally-fake token convention",
+        description: "Given names rendered as obvious TEST_ tokens rather than plausible names.",
+        claim: CLAIM_FAKE,
+        reserved: { kind: "fakeToken", pattern: "^TEST_Firstname_\\d{6,}$" },
+    },
+    {
+        field: "lastName",
+        tier: "structurally-fake",
+        citation: "No standard reserves names; structurally-fake token convention",
+        description: "Family names rendered as obvious TEST_ tokens.",
+        claim: CLAIM_FAKE,
+        reserved: { kind: "fakeToken", pattern: "^TEST_Lastname_\\d{6,}$" },
+    },
+    {
+        field: "fullName",
+        tier: "structurally-fake",
+        citation: "No standard reserves names; structurally-fake token convention",
+        description: "Full names rendered as obvious TEST_ tokens.",
+        claim: CLAIM_FAKE,
+        reserved: { kind: "fakeToken", pattern: "^TEST_Person_\\d{6,}$" },
+    },
+    {
+        field: "streetAddress",
+        tier: "structurally-fake",
+        citation: "No standard reserves addresses; structurally-fake 'Example' convention",
+        description: "Street addresses built on the obvious 'Example' street name.",
+        claim: CLAIM_FAKE,
+        reserved: { kind: "fakeToken", pattern: "^\\d+ Example (Way|St|Ave|Rd|Blvd)$" },
+    },
+    {
+        field: "freeText",
+        tier: "structurally-fake",
+        citation: "No standard reserves free text; structurally-fake token convention",
+        description: "Free-text fields rendered as obvious TEST_ tokens.",
+        claim: CLAIM_FAKE,
+        reserved: { kind: "fakeToken", pattern: "^TEST_Text_\\d{6,}$" },
+    },
+];
+const BY_FIELD = new Map(CATALOG.map((e) => [e.field, e]));
+/** Look up the catalog entry for a field type. Throws if the field is unknown. */
+export function getEntry(field) {
+    const entry = BY_FIELD.get(field);
+    if (entry === undefined)
+        throw new Error(`No catalog entry for field type: ${field}`);
+    return entry;
+}
+function domainIsReserved(domain, domains, tlds) {
+    const d = domain.toLowerCase();
+    // RFC 2606 reserves the whole zone of a reserved second-level domain, so a
+    // subdomain (mail.example.com) is reserved too — not just the bare domain.
+    if (domains.some((rd) => d === rd || d.endsWith(`.${rd}`)))
+        return true;
+    return tlds.some((t) => d === t || d.endsWith(`.${t}`));
+}
+/**
+ * Is `value` inside the reserved range declared for `entry`? This is the single
+ * predicate behind both `verify` (is generated output still in range?) and `scan`
+ * (does existing data contain anything *out* of range, i.e. candidate real PII?).
+ */
+export function isReserved(entry, value) {
+    const r = entry.reserved;
+    switch (r.kind) {
+        case "emailDomains": {
+            const at = value.lastIndexOf("@");
+            if (at < 0)
+                return false;
+            return domainIsReserved(value.slice(at + 1), r.domains, r.reservedTlds);
+        }
+        case "domains":
+            return domainIsReserved(value, r.domains, r.reservedTlds);
+        case "ipv4Blocks":
+            return r.cidrs.some((c) => ipv4InCidr(value, c));
+        case "ipv6Blocks":
+            return r.cidrs.some((c) => ipv6InPrefix(value, c));
+        case "phoneBlock": {
+            const digits = value.replace(/\D/g, "");
+            if (digits.length < 7)
+                return false;
+            const last7 = digits.slice(-7);
+            const nxx = last7.slice(0, 3);
+            const line = Number(last7.slice(3));
+            return nxx === r.centralOfficeCode && line >= r.subscriberStart && line <= r.subscriberEnd;
+        }
+        case "ssnInvalid": {
+            const digits = value.replace(/\D/g, "");
+            if (digits.length !== 9)
+                return false;
+            const area = digits.slice(0, 3);
+            const group = digits.slice(3, 5);
+            const serial = digits.slice(5);
+            const areaNum = Number(area);
+            const areaInvalid = r.invalidAreas.includes(area) || (areaNum >= r.invalidAreaMin && areaNum <= r.invalidAreaMax);
+            return areaInvalid || group === r.invalidGroup || serial === r.invalidSerial;
+        }
+        case "cardTestNumbers": {
+            const digits = value.replace(/\D/g, "");
+            return r.numbers.some((n) => n.replace(/\D/g, "") === digits);
+        }
+        case "fakeToken":
+            return new RegExp(r.pattern).test(value);
+    }
+}
+/**
+ * Heuristic used to assert the structurally-fake tier really is self-evident:
+ * a human glancing at the value should see "test data", not a plausible person.
+ */
+export function isSelfEvidentlyFake(value) {
+    return /test[_\s]/i.test(value) || /\bexample\b/i.test(value);
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}