namespace-guard 0.22.0 → 0.23.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Paul Wood FRSA
+Copyright (c) 2026 Paul Wood FRSA (@paultendo)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,43 +1,51 @@
 # namespace-guard
 
 [![npm version](https://img.shields.io/npm/v/namespace-guard.svg)](https://www.npmjs.com/package/namespace-guard)
+[![npm downloads](https://img.shields.io/npm/dw/namespace-guard.svg)](https://www.npmjs.com/package/namespace-guard)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/namespace-guard)](https://bundlephobia.com/package/namespace-guard)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**The world's first library that detects confusable characters across non-Latin scripts.** Slug claimability, Unicode anti-spoofing, and LLM [Denial of Spend](https://paultendo.github.io/posts/confusable-vision-llm-attack-tests/) defence in one zero-dependency package.
+**Lookalike detection built on the world's first font-by-font confusables dataset, measured in 322 fonts, including pairs between two non-Latin scripts that Unicode's confusables list leaves out.** Slug claimability, Unicode anti-spoofing, and LLM [Denial of Spend](https://paultendo.github.io/posts/confusable-vision-llm-attack-tests/) defence in one zero-dependency package.
+
+The measured pairs come from [confusable-vision](https://github.com/paultendo/confusable-vision), which [addons.mozilla.org](https://addons.mozilla.org/) uses to check add-on names for lookalikes, [credited by name in Mozilla's source](https://github.com/mozilla/addons-server/blob/master/src/olympia/amo/confusables.py#L4-L6).
 
 - Live demo: https://paultendo.github.io/namespace-guard/
+- Docs: https://paultendo.github.io/namespace-guard/docs/
 - Blog post: https://paultendo.github.io/posts/namespace-guard-launch/
 
+## Used by
+
+- **[agent-sanitizer](https://github.com/AlexanderMattTurner/agent-sanitizer)** cleans untrusted text before an AI agent reads it, and uses namespace-guard as its default engine for folding lookalike characters in tool-call input (paths and commands) to ASCII. [Dependents on deps.dev](https://deps.dev/npm/namespace-guard/0.20.0/dependents).
+- **[d0ma1n](https://d0ma1n.app)** finds the lookalikes of a domain that are already registered, scored with namespace-guard's measured weights.
+- **[Mozilla addons.mozilla.org](https://addons.mozilla.org/)** checks add-on names for lookalikes with characters from **[confusable-vision](https://github.com/paultendo/confusable-vision#used-by)**, where these measured pairs come from ([`confusables.py`](https://github.com/mozilla/addons-server/blob/master/src/olympia/amo/confusables.py#L4-L6) in [addons-server](https://github.com/mozilla/addons-server)). [disarm](https://disarm.dev/) and [SilverSpeak](https://acmcmc.github.io/silverspeak/) use confusable-vision's data too.
+
 ## Cross-script confusable detection
 
-Existing confusable standards (TR39, IDNA) map non-Latin characters to Latin equivalents. They have zero coverage for confusable pairs *between* two non-Latin scripts.
+Unicode's confusables list (TR39), which IDNA and most tools build on, maps each lookalike to one prototype, usually a Latin letter. Two non-Latin characters that look alike are only paired when they happen to share a prototype, so many pairs *between* two non-Latin scripts are missing.
 
-namespace-guard ships measured lookalike pairs from [confusable-vision](https://github.com/paultendo/confusable-vision) release 2026.09.24 (vector-outline raycasting, [RaySpace](https://paultendo.github.io/posts/rayspace-methodology/), at the size and baseline position glyphs have in running text, across every macOS system font and Roboto). They include pairs between two non-Latin scripts that no standard covers:
+namespace-guard ships measured lookalike pairs from [confusable-vision](https://github.com/paultendo/confusable-vision) release 2026.09.26 (vector-outline raycasting, [RaySpace](https://paultendo.github.io/posts/rayspace-methodology/), at the size and baseline position glyphs have in running text, in 322 fonts: every macOS font, Roboto, Noto and DejaVu). They include pairs between two non-Latin scripts that no standard covers:
 
 ```typescript
 import { areConfusable, detectCrossScriptRisk } from "namespace-guard";
 import { CONFUSABLE_WEIGHTS } from "namespace-guard/confusable-weights";
 
-// Hangul ᅵ and Han 丨 are alike in every text font that draws both
-areConfusable("\u1175", "\u4E28", { weights: CONFUSABLE_WEIGHTS }); // true
-
-// Cyrillic ј and Greek ϳ are alike in 95% of text fonts
-areConfusable("\u0458", "\u03F3", { weights: CONFUSABLE_WEIGHTS }); // true
-
-// Cyrillic І and Greek Ι are identical outlines (62 fonts)
-areConfusable("\u0406", "\u0399", { weights: CONFUSABLE_WEIGHTS }); // true
+// Hangul ㅣ and Han 丨 are alike in every text font that draws both. Unicode's list doesn't pair them,
+// so only the measured weights catch it
+areConfusable("\u3163", "\u4E28", { weights: CONFUSABLE_WEIGHTS }); // true
+areConfusable("\u3163", "\u4E28");                                  // false
 
-// Without weights, only skeleton-based detection (TR39 coverage)
-areConfusable("\u1175", "\u4E28"); // false
+// Cyrillic ј and Greek ϳ (alike in 92% of text fonts), and Cyrillic І and Greek Ι (identical outlines in 51 fonts),
+// both map to a Latin letter in Unicode's list, so they match with or without weights
+areConfusable("\u0458", "\u03F3"); // true
+areConfusable("\u0406", "\u0399"); // true
 
 // Analyze an identifier for cross-script risk
-const risk = detectCrossScriptRisk("\u1175\u4E28", { weights: CONFUSABLE_WEIGHTS });
+const risk = detectCrossScriptRisk("\u3163\u4E28", { weights: CONFUSABLE_WEIGHTS });
 // { riskLevel: "high", scripts: ["han", "hangul"], crossScriptPairs: [...] }
 ```
 
-322 pairs ship, each found alike at running-text size within one font or across fonts. A pair's `danger` (0–1) is the share of text fonts (or font combinations) where it holds; filter at `danger > 0.7` (85 pairs) for the pairs alike almost everywhere. `namespace-guard/font-specific-weights` gives the same pairs per font (106 fonts), for saying which font makes a lookalike most convincing. Data licensed CC-BY-4.0.
+2,300 pairs ship, each found alike at running-text size within one font or across fonts, where one character is an ASCII letter or digit or the two are in different scripts. A pair's `danger` (0–1) is the share of text fonts (or font combinations) where it holds; filter at `danger > 0.7` (1,079 pairs) for the pairs alike almost everywhere. `namespace-guard/font-specific-weights` gives the pairs found within one font per font (1,417 pairs in 166 fonts), for saying which font makes a lookalike most convincing. Data licensed CC-BY-4.0.
 
 ## Installation
 
@@ -69,7 +77,7 @@ const guard = createNamespaceGuardWithProfile(
 await guard.assertClaimable("acme-corp");
 ```
 
-For race-safe writes, use `claim()`:
+To check and write in one step, use `claim()`. With a unique index on the canonical column, a write that loses a race comes back as "taken" rather than as a database error. If users and organisations share one namespace, add a shared names table too; see [Names shared by several tables](https://paultendo.github.io/namespace-guard/docs/claiming/#names-shared-by-several-tables).
 
 ```typescript
 const result = await guard.claim(input.handle, async (canonical) => {
@@ -99,11 +107,15 @@ if (!result.claimed) {
 
 ## LLM Pipeline Preprocessing
 
-Confusable characters are pixel-identical to Latin letters but encode as multi-byte BPE tokens. A 95-line contract that costs 881 tokens in clean ASCII costs 4,567 tokens when flooded with confusables: **5.2x the API bill**. The model reads it correctly. The invoice does not care.
+**Lookalike letters can't fool an LLM. They can make it cost up to 5.7x as much to read.**
 
-We tested this across 4 frontier models, 8 attack types, and 130+ API calls. Zero meaning flips. Every substituted clause was correctly interpreted. But the billing attack succeeds. We call it **Denial of Spend**: the confusable analogue of DDoS, where the attacker cannot degrade the service but can inflate the cost of running it.
+I flooded a contract with characters that pass for Latin letters and gave it to seven GPT and Claude models: GPT-6 Astra, Sol and Luna, and Claude Fable 5.1, Opus 5.5, Sonnet 5 and Haiku 4.5. Every one still read every negation correctly. But the contract grew from about a thousand tokens to more than four thousand, and you pay for every one of them. I call this **Denial of Spend**: an attack that can't change what the service does, but can multiply what it costs to run.
 
-`canonicalise()` recovered every substituted term across all 12 attack variants, collapsing the 5.2x inflation to 1.0x. Processing a 10,000-character document takes under 1ms.
+Reading is only part of the bill. The model's answer isn't flooded, and output tokens cost more, so on a short contract the bill for each question rose by up to 3.9x, depending on how much the model wrote back. For work that is all reading, such as embedding documents for search, the bill rises by the full 4x to 5.7x ([results](https://github.com/paultendo/confusable-vision/blob/main/data/output/denial-of-spend/RESULTS.md)).
+
+The first test, in February 2026, covered 4 models, 8 attack types and 130+ API calls, with the same result: no meaning flips, and 5.2x the tokens for the flooded contract.
+
+`canonicalise()` rewrites any word that shows a sign of tampering: one that mixes Latin with another script, has a Latin letter no modern language uses (ɦ, ꞡ), or has a non-ASCII capital inside a lowercase word. Every lookalike in such a word goes back to its Latin letter, in the case of the word around it; ordinary Turkish, Russian or Sámi words are left alone. With `strategy: "all"` it turns the flooded contract back into the clean one, byte for byte, so it takes as many tokens as the clean one; the default leaves 9 short words (1.02x to 1.03x the clean contract's tokens). The flooded contract takes under 2 ms.
 
 ```typescript
 import { canonicalise, scan, isClean } from "namespace-guard";
@@ -112,7 +124,10 @@ const raw = "The seller аssumes аll liаbility.";
 
 const report = scan(raw);        // detailed findings + risk level
 const clean = canonicalise(raw); // "The seller assumes all liability."
-const ok = isClean(raw);         // false (mixed-script confusable detected)
+const ok = isClean(raw);         // false: true only when canonicalise() would change nothing
+
+canonicalise("shall поŧ be limited"); // "shall not be limited" (Cyrillic п, о; Latin t with stroke)
+canonicalise("Tɦİs ƙİŧe İstanbul");   // "This kite İstanbul" (İstanbul shows no sign of tampering)
 
 // For known-Latin documents (e.g. English contracts), use strategy: "all"
 // to also catch words where every character was substituted:
@@ -136,7 +151,7 @@ areConfusable("paypal", "pa\u0443pal"); // true
 confusableDistance("paypal", "pa\u0443pal"); // graded similarity + chainDepth + explainable steps
 ```
 
-For measured visual scoring, pass the optional weights from confusable-vision release 2026.09.24 (322 pairs measured at running-text size by vector-outline raycasting). Each pair has a `danger` score (0–1), the share of text fonts where it holds; use `danger > 0.7` for the pairs alike almost everywhere. The `context` filter restricts to identifier-valid, domain-valid, or all pairs.
+For measured visual scoring, pass the optional weights from confusable-vision release 2026.09.26 (2,300 pairs measured at running-text size by vector-outline raycasting). Each pair has a `danger` score (0–1), the share of text fonts where it holds; use `danger > 0.7` for the pairs alike almost everywhere. The `context` filter restricts to identifier-valid, domain-valid, or all pairs.
 
 ```typescript
 import { confusableDistance } from "namespace-guard";
@@ -159,7 +174,7 @@ import { CONFUSABLE_WEIGHTS } from "namespace-guard/confusable-weights";
 
 // Full-Cyrillic lookalike — registrable and deceptive
 isDomainSpoof("\u0440\u0430\u0443\u0440\u0430\u04CF", "paypal", { weights: CONFUSABLE_WEIGHTS });
-// { spoof: true, script: "cyrillic", danger: 0.91, substitutions: [...] }
+// { spoof: true, script: "cyrillic", danger: 0.781, substitutions: [...] }
 
 // Mixed-script — not registrable, not flagged
 isDomainSpoof("\u0440aypal", "paypal", { weights: CONFUSABLE_WEIGHTS });
@@ -179,11 +194,11 @@ The `danger` score (0–1) is always returned when a script match is found, even
 
 Two research tracks feed the library:
 
-**Visual measurement.** Lookalike pairs measured by vector-outline raycasting ([RaySpace](https://paultendo.github.io/posts/rayspace-methodology/)) at the size and baseline position glyphs have in running text, across every macOS system font and Roboto, and calibrated against pairs with known answers. Release 2026.09.24 finds 857 pairs alike; the 322 that pass its thresholds ship here, including pairs between two non-Latin scripts (Cyrillic/Greek, Katakana/Hiragana, Han/Hangul) that no standard covers. The March 2026 measurements were blind to size and are superseded. Full dataset published as [confusable-vision](https://github.com/paultendo/confusable-vision) (CC-BY-4.0).
+**Visual measurement.** Lookalike pairs measured by vector-outline raycasting ([RaySpace](https://paultendo.github.io/posts/rayspace-methodology/)) at the size and baseline position glyphs have in running text, in 322 fonts (every macOS font, Roboto, Noto and DejaVu), and calibrated against pairs with known answers. Release 2026.09.26 compares every letter and digit each font draws; the 2,300 pairs that pass its thresholds and involve an ASCII letter or two scripts ship here, including pairs between two non-Latin scripts (Cyrillic/Greek, Katakana/Hiragana, Han/Hangul) that no standard covers. Its lookalikes of ASCII letters are also checked in place, set between other letters in common fonts at text size; those that Unicode does not list are in `CONFUSABLE_MAP_FULL` and `MEASURED_CONFUSABLES`. Earlier releases compared only part of this and are superseded. Full dataset published as [confusable-vision](https://github.com/paultendo/confusable-vision) (CC-BY-4.0).
 
-**Normalisation composability.** 31 characters where Unicode's confusables.txt and NFKC normalisation disagree. Two production maps (`CONFUSABLE_MAP` for NFKC-first, `CONFUSABLE_MAP_FULL` for raw-input pipelines), a benchmark corpus, and composability vectors wired into CLI drift baselines. Submitted to [Unicode public review (PRI #540)](https://www.unicode.org/review/pri540/) and published in [accumulated feedback](https://www.unicode.org/review/pri540/feedback.html).
+**Normalisation composability.** 34 characters where Unicode's confusables.txt (August 2026) and NFKC normalisation disagree, up from 31 with the previous file. Three of them are Unicode 16 characters, so a runtime whose NFKC predates Unicode 16 derives 31. Two production maps (`CONFUSABLE_MAP` for NFKC-first, `CONFUSABLE_MAP_FULL` for raw-input pipelines), a benchmark corpus, and composability vectors wired into CLI drift baselines. Submitted to [Unicode public review (PRI #540)](https://www.unicode.org/review/pri540/) and published in [accumulated feedback](https://www.unicode.org/review/pri540/feedback.html).
 
-- Technical reference: [docs/reference.md#how-the-anti-spoofing-pipeline-works](docs/reference.md#how-the-anti-spoofing-pipeline-works)
+- Technical reference: [how a name is checked](https://paultendo.github.io/namespace-guard/docs/how-it-works/) and [Unicode names](https://paultendo.github.io/namespace-guard/docs/unicode-names/)
 - Launch write-up: https://paultendo.github.io/posts/namespace-guard-launch/
 - Denial of Spend: https://paultendo.github.io/posts/confusable-vision-llm-attack-tests/
 
@@ -223,6 +238,8 @@ const guard = createNamespaceGuard(
 );
 ```
 
+The English list comes with an allowlist of names, places and common words that contain a listed word (Scunthorpe, Dickson, Kirkland). With its defaults it refuses 0.4% of dictionary words and 11 of the 38,970 first names given to babies in England and Wales since 1996, and it leaves out names and places that look like a slur. Add your own users' names and towns with `allowlist`, and run it over the names you already have before you switch it on: see [Moderation](https://paultendo.github.io/namespace-guard/docs/moderation/).
+
 ## CLI Workflow
 
 ```bash
@@ -251,29 +268,22 @@ npx namespace-guard drift --json
 - Mongoose
 - Raw SQL
 
-Adapter setup examples and migration guidance: [docs/reference.md#adapters](docs/reference.md#adapters)
+Adapter setup examples and migration guidance: [Adapters](https://paultendo.github.io/namespace-guard/docs/adapters/)
 
 ## Production Recommendation: Canonical Uniqueness
 
 For full protection against Unicode/canonicalization edge cases, enforce uniqueness on canonical columns (for example `handleCanonical`, `slugCanonical`) and point `sources[*].column` there.
 
-Migration guides per adapter: [docs/reference.md#canonical-uniqueness-migration-per-adapter](docs/reference.md#canonical-uniqueness-migration-per-adapter)
+Adding a canonical column, per adapter: [Claiming names](https://paultendo.github.io/namespace-guard/docs/claiming/#store-a-canonical-column) and [Adapters](https://paultendo.github.io/namespace-guard/docs/adapters/)
 
 ## Documentation Map
 
-- Full reference: [docs/reference.md](docs/reference.md)
-- Config reference: [docs/reference.md#configuration](docs/reference.md#configuration)
-- Validators (profanity, homoglyph, invisible): [docs/reference.md#async-validators](docs/reference.md#async-validators)
-- Canonical preflight audit (`audit-canonical`): [docs/reference.md#audit-canonical-command](docs/reference.md#audit-canonical-command)
-- Anti-spoofing pipeline and composability vectors: [docs/reference.md#how-the-anti-spoofing-pipeline-works](docs/reference.md#how-the-anti-spoofing-pipeline-works)
-- LLM preprocessing (`canonicalise`, `scan`, `isClean`): [docs/reference.md#llm-pipeline-preprocessing](docs/reference.md#llm-pipeline-preprocessing)
-- Benchmark corpus (`confusable-bench.v1`): [docs/reference.md#confusable-benchmark-corpus-artifact](docs/reference.md#confusable-benchmark-corpus-artifact)
-- Advanced primitives (`skeleton`, `areConfusable`, `confusableDistance`): [docs/reference.md#advanced-security-primitives](docs/reference.md#advanced-security-primitives)
-- Confusable weights (scored pairs, including cross-script): [docs/reference.md#confusable-weights-subpath](docs/reference.md#confusable-weights-subpath)
-- Cross-script detection: [docs/reference.md#cross-script-detection](docs/reference.md#cross-script-detection)
-- CLI reference: [docs/reference.md#cli](docs/reference.md#cli)
-- API reference: [docs/reference.md#api-reference](docs/reference.md#api-reference)
-- Framework integration (Next.js/Express/tRPC): [docs/reference.md#framework-integration](docs/reference.md#framework-integration)
+The docs live at **[paultendo.github.io/namespace-guard/docs](https://paultendo.github.io/namespace-guard/docs/)**, with search and examples you can run in the page. The pages are Markdown in [`guide/`](guide/), and every example in them runs in the test suite.
+
+- [Getting started](https://paultendo.github.io/namespace-guard/docs/getting-started/) and [how a name is checked](https://paultendo.github.io/namespace-guard/docs/how-it-works/)
+- Guides: [protect names](https://paultendo.github.io/namespace-guard/docs/protect-names/), [Unicode names](https://paultendo.github.io/namespace-guard/docs/unicode-names/), [claiming names](https://paultendo.github.io/namespace-guard/docs/claiming/), [suggestions](https://paultendo.github.io/namespace-guard/docs/suggestions/), [moderation](https://paultendo.github.io/namespace-guard/docs/moderation/), [text for LLMs](https://paultendo.github.io/namespace-guard/docs/llm-text/), [domain names](https://paultendo.github.io/namespace-guard/docs/domains/), [comparing names](https://paultendo.github.io/namespace-guard/docs/comparing-names/), [the CLI](https://paultendo.github.io/namespace-guard/docs/cli/), [upgrading to 0.23](https://paultendo.github.io/namespace-guard/docs/upgrading/)
+- Reference: [configuration](https://paultendo.github.io/namespace-guard/docs/configuration/), [the guard](https://paultendo.github.io/namespace-guard/docs/guard/), [functions](https://paultendo.github.io/namespace-guard/docs/functions/), [data and maps](https://paultendo.github.io/namespace-guard/docs/data/), [adapters](https://paultendo.github.io/namespace-guard/docs/adapters/), [frameworks](https://paultendo.github.io/namespace-guard/docs/frameworks/), [TypeScript](https://paultendo.github.io/namespace-guard/docs/typescript/)
+- [Changelog](https://paultendo.github.io/namespace-guard/docs/changelog/)
 
 ## Support
 

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,120 @@
+# Third-party notices
+
+namespace-guard includes data derived from third-party sources. The
+namespace-guard source code is MIT-licensed (see `LICENSE`). The
+embedded data retains its original licence as noted below.
+
+---
+
+## Unicode confusables.txt
+
+**Used by:** `CONFUSABLE_MAP`, `CONFUSABLE_MAP_FULL`, `skeleton()`,
+`areConfusable()` (in `src/index.ts`)
+
+**Source:** https://unicode.org/Public/security/latest/confusables.txt
+
+**Licence:** Unicode License v3
+https://www.unicode.org/terms_of_use.html
+
+> Copyright 1991-Present Unicode, Inc. All rights reserved.
+
+Regenerate: `npx tsx scripts/generate-confusables.ts`
+
+---
+
+## Unicode Character Database (UnicodeData.txt, Scripts.txt, IdentifierType.txt)
+
+**Used by:** `LATIN_FOLD` and `LATIN_NOT_IN_MODERN_USE` (in `src/latin-fold.ts`),
+used by `canonicalise()`, `scan()` and `isClean()`
+
+**Source:** https://www.unicode.org/Public/UCD/latest/ucd/ and
+https://www.unicode.org/Public/security/latest/IdentifierType.txt (UCD 17.0.0; IdentifierType 16.0.0)
+
+**Licence:** Unicode License v3
+https://www.unicode.org/terms_of_use.html
+
+> Copyright 1991-Present Unicode, Inc. All rights reserved.
+
+Regenerate: `npm run build:latin-fold`
+
+---
+
+## confusable-vision visual similarity data
+
+**Used by:** `CONFUSABLE_WEIGHTS` (in `src/confusable-weights.ts`),
+`FONT_SPECIFIC_WEIGHTS` (in `src/font-specific-weights.ts`), the `visualScore`
+and `novel` entries of `LLM_CONFUSABLE_MAP` (in `src/llm-confusable-map.ts`),
+`MEASURED_CONFUSABLES` and the measured entries of `CONFUSABLE_MAP` and
+`CONFUSABLE_MAP_FULL` (in `src/confusable-maps.ts`)
+
+**Source:** https://github.com/paultendo/confusable-vision, release 2026.09.26
+
+**Licence:** CC-BY-4.0
+https://creativecommons.org/licenses/by/4.0/
+
+**Attribution:** Paul Wood FRSA (@paultendo), confusable-vision.
+Visual similarity weights for 2,300 character pairs (confusable-weights-v4.json),
+1,417 font-specific pairs in 166 fonts, and the in-place checks of lookalikes of
+ASCII letters and digits, from release 2026.09.26, measured with RaySpace.
+
+Regenerate: `node scripts/generate-confusable-weights.js`,
+`node scripts/generate-font-specific-weights.js` and
+`npx tsx scripts/generate-confusables.ts`
+
+---
+
+## profane-words (English profanity list)
+
+**Used by:** `PROFANITY_WORDS_EN` (in `src/profanity-en.ts`)
+
+**Source:** https://github.com/zautumnz/profane-words
+
+**Licence:** WTFPL v2
+
+See `docs/data/profanity-words.SOURCE.md` for curation notes.
+
+Regenerate: `node scripts/generate-profanity-global.js`
+
+---
+
+## Names and places in the English allowlist
+
+**Used by:** `PROFANITY_ALLOWLIST_EN` (in `src/profanity-en.ts`) and
+`docs/data/profanity-allowlist.json`: names, places and common words that contain
+a word on the English list, which `createEnglishProfanityValidator()` lets through.
+The allowlist is a selection of words from these sources, screened for slurs and
+crude words; see `docs/data/profanity-words.SOURCE.md`.
+
+**GeoNames** (`GB.txt`, populated places and administrative areas; `cities1000.txt`)
+https://download.geonames.org/export/dump/
+
+**Licence:** CC BY 4.0
+https://creativecommons.org/licenses/by/4.0/
+
+**Attribution:** Place names from GeoNames (https://www.geonames.org/), licensed
+under CC BY 4.0.
+
+**ONS baby names** ("Baby names in England and Wales: from 1996", 1996 to 2025)
+https://www.ons.gov.uk/peoplepopulationandcommunity/birthsdeathsandmarriages/livebirths/datasets/babynamesinenglandandwalesfrom1996
+
+**Licence:** Open Government Licence v3.0
+https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
+
+**Attribution:** Contains public sector information licensed under the Open
+Government Licence v3.0.
+
+**US Census Bureau 2010 surnames** (`Names_2010Census.csv`)
+https://www2.census.gov/topics/genealogy/2010surnames/names.zip
+
+**Licence:** public domain (a work of the US federal government).
+
+**Webster's Second New International Dictionary (1934)**, as
+`/usr/share/dict/words`: public domain.
+
+No Apple data and no wordfreq data ship with namespace-guard. The core's
+`PROFANITY_COMMON_INSIDE_WORDS` (in `src/index.ts`) holds only letter sequences
+taken from the English list's own entries; they were chosen by measuring those
+entries against `/usr/share/dict/words` and wordfreq's word frequencies.
+
+Regenerate: `npm run build && node scripts/measure-profanity.mjs --write`, then
+`npm run build:profanity-data`. The source files go in `.cache/open-names/`.

package/dist/adapters/drizzle.js

@@ -48,15 +48,16 @@ function createDrizzleAdapter(db, tables, eqOrOptions) {
         compareFn = ops.ilike;
       }
       return queryHandler.findFirst({
-        where: compareFn(column, value),
-        columns: {
-          [idColumn]: true,
-          ...source.scopeKey && source.scopeKey !== idColumn ? { [source.scopeKey]: true } : {}
-        }
+        where: compareFn(column, findOptions?.caseInsensitive ? escapeLike(value) : value),
+        // The guard only needs the id: it compares the scope's value with it
+        columns: { [idColumn]: true }
       });
     }
   };
 }
+function escapeLike(value) {
+  return value.replace(/[\\%_]/g, "\\$&");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createDrizzleAdapter

package/dist/adapters/drizzle.mjs

@@ -24,15 +24,16 @@ function createDrizzleAdapter(db, tables, eqOrOptions) {
         compareFn = ops.ilike;
       }
       return queryHandler.findFirst({
-        where: compareFn(column, value),
-        columns: {
-          [idColumn]: true,
-          ...source.scopeKey && source.scopeKey !== idColumn ? { [source.scopeKey]: true } : {}
-        }
+        where: compareFn(column, findOptions?.caseInsensitive ? escapeLike(value) : value),
+        // The guard only needs the id: it compares the scope's value with it
+        columns: { [idColumn]: true }
       });
     }
   };
 }
+function escapeLike(value) {
+  return value.replace(/[\\%_]/g, "\\$&");
+}
 export {
   createDrizzleAdapter
 };

package/dist/adapters/knex.js

@@ -27,7 +27,7 @@ function createKnexAdapter(knex) {
   return {
     async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
-      const columns = source.scopeKey && source.scopeKey !== idColumn ? [idColumn, source.scopeKey] : [idColumn];
+      const columns = [idColumn];
       let query = knex(source.name).select(columns);
       if (options?.caseInsensitive) {
         query = query.whereRaw(`LOWER(??) = LOWER(?)`, [source.column, value]);

package/dist/adapters/knex.mjs

@@ -3,7 +3,7 @@ function createKnexAdapter(knex) {
   return {
     async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
-      const columns = source.scopeKey && source.scopeKey !== idColumn ? [idColumn, source.scopeKey] : [idColumn];
+      const columns = [idColumn];
       let query = knex(source.name).select(columns);
       if (options?.caseInsensitive) {
         query = query.whereRaw(`LOWER(??) = LOWER(?)`, [source.column, value]);

package/dist/adapters/kysely.js

@@ -27,10 +27,10 @@ function createKyselyAdapter(db) {
   return {
     async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
-      const columns = source.scopeKey && source.scopeKey !== idColumn ? [idColumn, source.scopeKey] : [idColumn];
+      const columns = [idColumn];
       let query = db.selectFrom(source.name).select(columns);
       if (options?.caseInsensitive) {
-        query = query.where(source.column, "ilike", value);
+        query = query.where(source.column, "ilike", escapeLike(value));
       } else {
         query = query.where(source.column, "=", value);
       }
@@ -39,6 +39,9 @@ function createKyselyAdapter(db) {
     }
   };
 }
+function escapeLike(value) {
+  return value.replace(/[\\%_]/g, "\\$&");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createKyselyAdapter

package/dist/adapters/kysely.mjs

@@ -3,10 +3,10 @@ function createKyselyAdapter(db) {
   return {
     async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
-      const columns = source.scopeKey && source.scopeKey !== idColumn ? [idColumn, source.scopeKey] : [idColumn];
+      const columns = [idColumn];
       let query = db.selectFrom(source.name).select(columns);
       if (options?.caseInsensitive) {
-        query = query.where(source.column, "ilike", value);
+        query = query.where(source.column, "ilike", escapeLike(value));
       } else {
         query = query.where(source.column, "=", value);
       }
@@ -15,6 +15,9 @@ function createKyselyAdapter(db) {
     }
   };
 }
+function escapeLike(value) {
+  return value.replace(/[\\%_]/g, "\\$&");
+}
 export {
   createKyselyAdapter
 };

package/dist/adapters/mikro-orm.js

@@ -31,8 +31,8 @@ function createMikroORMAdapter(em, entities) {
         throw new Error(`MikroORM entity "${source.name}" not found in provided entities object`);
       }
       const idColumn = source.idColumn ?? "id";
-      const fields = source.scopeKey && source.scopeKey !== idColumn ? [idColumn, source.scopeKey] : [idColumn];
-      const whereValue = options?.caseInsensitive ? { $ilike: value } : value;
+      const fields = [idColumn];
+      const whereValue = options?.caseInsensitive ? { $ilike: escapeLike(value) } : value;
       return em.findOne(
         entity,
         { [source.column]: whereValue },
@@ -41,6 +41,9 @@ function createMikroORMAdapter(em, entities) {
     }
   };
 }
+function escapeLike(value) {
+  return value.replace(/[\\%_]/g, "\\$&");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createMikroORMAdapter

package/dist/adapters/mikro-orm.mjs

@@ -7,8 +7,8 @@ function createMikroORMAdapter(em, entities) {
         throw new Error(`MikroORM entity "${source.name}" not found in provided entities object`);
       }
       const idColumn = source.idColumn ?? "id";
-      const fields = source.scopeKey && source.scopeKey !== idColumn ? [idColumn, source.scopeKey] : [idColumn];
-      const whereValue = options?.caseInsensitive ? { $ilike: value } : value;
+      const fields = [idColumn];
+      const whereValue = options?.caseInsensitive ? { $ilike: escapeLike(value) } : value;
       return em.findOne(
         entity,
         { [source.column]: whereValue },
@@ -17,6 +17,9 @@ function createMikroORMAdapter(em, entities) {
     }
   };
 }
+function escapeLike(value) {
+  return value.replace(/[\\%_]/g, "\\$&");
+}
 export {
   createMikroORMAdapter
 };

package/dist/adapters/mongoose.js

@@ -32,17 +32,15 @@ function createMongooseAdapter(models) {
       }
       const idColumn = source.idColumn ?? "_id";
       const projection = { [idColumn]: 1 };
-      if (source.scopeKey && source.scopeKey !== idColumn) {
-        projection[source.scopeKey] = 1;
-      }
       const query = model.findOne(
         { [source.column]: value },
         projection
       );
-      if (options?.caseInsensitive) {
-        return query.collation({ locale: "en", strength: 2 }).lean();
+      const doc = options?.caseInsensitive ? await query.collation({ locale: "en", strength: 2 }).lean() : await query.lean();
+      if (doc && source.idColumn === void 0 && doc.id === void 0 && doc._id !== void 0) {
+        return { ...doc, id: doc._id };
       }
-      return query.lean();
+      return doc;
     }
   };
 }

package/dist/adapters/mongoose.mjs

@@ -8,17 +8,15 @@ function createMongooseAdapter(models) {
       }
       const idColumn = source.idColumn ?? "_id";
       const projection = { [idColumn]: 1 };
-      if (source.scopeKey && source.scopeKey !== idColumn) {
-        projection[source.scopeKey] = 1;
-      }
       const query = model.findOne(
         { [source.column]: value },
         projection
       );
-      if (options?.caseInsensitive) {
-        return query.collation({ locale: "en", strength: 2 }).lean();
+      const doc = options?.caseInsensitive ? await query.collation({ locale: "en", strength: 2 }).lean() : await query.lean();
+      if (doc && source.idColumn === void 0 && doc.id === void 0 && doc._id !== void 0) {
+        return { ...doc, id: doc._id };
       }
-      return query.lean();
+      return doc;
     }
   };
 }

package/dist/adapters/prisma.js

@@ -34,10 +34,8 @@ function createPrismaAdapter(prisma) {
       const whereValue = options?.caseInsensitive ? { equals: value, mode: "insensitive" } : value;
       return model.findFirst({
         where: { [source.column]: whereValue },
-        select: {
-          [idColumn]: true,
-          ...source.scopeKey ? { [source.scopeKey]: true } : {}
-        }
+        // The guard only needs the id: it compares the scope's value with it
+        select: { [idColumn]: true }
       });
     }
   };

package/dist/adapters/prisma.mjs

@@ -10,10 +10,8 @@ function createPrismaAdapter(prisma) {
       const whereValue = options?.caseInsensitive ? { equals: value, mode: "insensitive" } : value;
       return model.findFirst({
         where: { [source.column]: whereValue },
-        select: {
-          [idColumn]: true,
-          ...source.scopeKey ? { [source.scopeKey]: true } : {}
-        }
+        // The guard only needs the id: it compares the scope's value with it
+        select: { [idColumn]: true }
       });
     }
   };

package/dist/adapters/raw.js

@@ -36,8 +36,7 @@ function createRawAdapter(execute) {
       assertSafeIdentifier(source.name, "table name");
       assertSafeIdentifier(source.column, "column name");
       assertSafeIdentifier(idColumn, "id column name");
-      if (source.scopeKey) assertSafeIdentifier(source.scopeKey, "scope key");
-      const columns = source.scopeKey && source.scopeKey !== idColumn ? `"${idColumn}", "${source.scopeKey}"` : `"${idColumn}"`;
+      const columns = `"${idColumn}"`;
       const whereClause = options?.caseInsensitive ? `LOWER("${source.column}") = LOWER($1)` : `"${source.column}" = $1`;
       const sql = `SELECT ${columns} FROM "${source.name}" WHERE ${whereClause} LIMIT 1`;
       const result = await execute(sql, [value]);

package/dist/adapters/raw.mjs

@@ -12,8 +12,7 @@ function createRawAdapter(execute) {
       assertSafeIdentifier(source.name, "table name");
       assertSafeIdentifier(source.column, "column name");
       assertSafeIdentifier(idColumn, "id column name");
-      if (source.scopeKey) assertSafeIdentifier(source.scopeKey, "scope key");
-      const columns = source.scopeKey && source.scopeKey !== idColumn ? `"${idColumn}", "${source.scopeKey}"` : `"${idColumn}"`;
+      const columns = `"${idColumn}"`;
       const whereClause = options?.caseInsensitive ? `LOWER("${source.column}") = LOWER($1)` : `"${source.column}" = $1`;
       const sql = `SELECT ${columns} FROM "${source.name}" WHERE ${whereClause} LIMIT 1`;
       const result = await execute(sql, [value]);

package/dist/adapters/sequelize.js

@@ -31,7 +31,7 @@ function createSequelizeAdapter(models, helpers) {
         throw new Error(`Sequelize model "${source.name}" not found in provided models object`);
       }
       const idColumn = source.idColumn ?? "id";
-      const attributes = source.scopeKey && source.scopeKey !== idColumn ? [idColumn, source.scopeKey] : [idColumn];
+      const attributes = [idColumn];
       let where;
       if (options?.caseInsensitive) {
         if (!helpers) {

package/dist/adapters/sequelize.mjs

@@ -7,7 +7,7 @@ function createSequelizeAdapter(models, helpers) {
         throw new Error(`Sequelize model "${source.name}" not found in provided models object`);
       }
       const idColumn = source.idColumn ?? "id";
-      const attributes = source.scopeKey && source.scopeKey !== idColumn ? [idColumn, source.scopeKey] : [idColumn];
+      const attributes = [idColumn];
       let where;
       if (options?.caseInsensitive) {
         if (!helpers) {