namespace-guard 0.6.1 → 0.8.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Wood FRSA
+
+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

@@ -5,7 +5,7 @@
 [![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)
 
-**[Live Demo](https://paultendo.github.io/namespace-guard/)** — try it in your browser
+**[Live Demo](https://paultendo.github.io/namespace-guard/)** — try it in your browser | **[Blog Post](https://paultendo.github.io/posts/namespace-guard-launch/)** — why this exists
 
 **Check slug/handle uniqueness across multiple database tables with reserved name protection.**
 
@@ -60,7 +60,7 @@ if (result.available) {
   // Create the org
 } else {
   // Show error: result.message
-  // e.g., "That name is reserved." or "That name is already in use."
+  // e.g., "That name is reserved. Try another one." or "That name is already in use."
 }
 ```
 
@@ -98,6 +98,7 @@ import { createDrizzleAdapter } from "namespace-guard/adapters/drizzle";
 import { db } from "./db";
 import { users, organizations } from "./schema";
 
+// Pass eq directly, or use { eq, ilike } for case-insensitive support
 const adapter = createDrizzleAdapter(db, { users, organizations }, eq);
 ```
 
@@ -296,6 +297,100 @@ const guard = createNamespaceGuard({
 
 No words are bundled — use any word list you like (e.g., the `bad-words` npm package, your own list, or an external API wrapped in a custom validator).
 
+### Built-in Homoglyph Validator
+
+Prevent spoofing attacks where visually similar characters from any Unicode script are substituted for Latin letters (e.g., Cyrillic "а" for Latin "a" in "admin"):
+
+```typescript
+import { createNamespaceGuard, createHomoglyphValidator } from "namespace-guard";
+
+const guard = createNamespaceGuard({
+  sources: [/* ... */],
+  validators: [
+    createHomoglyphValidator(),
+  ],
+}, adapter);
+```
+
+Options:
+
+```typescript
+createHomoglyphValidator({
+  message: "Custom rejection message.",       // optional
+  additionalMappings: { "\u0261": "g" },      // extend the built-in map
+  rejectMixedScript: true,                    // also reject Latin + non-Latin script mixing
+})
+```
+
+The built-in `CONFUSABLE_MAP` contains 613 character pairs generated from [Unicode TR39 confusables.txt](https://unicode.org/reports/tr39/) plus supplemental Latin small capitals. It covers Cyrillic, Greek, Armenian, Cherokee, IPA, Coptic, Lisu, Canadian Syllabics, Georgian, and 20+ other scripts. The map is exported for inspection or extension, and is regenerable for new Unicode versions with `npx tsx scripts/generate-confusables.ts`.
+
+### How the anti-spoofing pipeline works
+
+Most confusable-detection libraries apply a character map in isolation. namespace-guard uses a three-stage pipeline where each stage is aware of the others:
+
+```
+Input  →  NFKC normalize  →  Confusable map  →  Mixed-script reject
+           (stage 1)          (stage 2)           (stage 3)
+```
+
+**Stage 1: NFKC normalization** collapses full-width characters (`Ｉ` → `I`), ligatures (`fi` → `fi`), superscripts, and other Unicode compatibility forms to their canonical equivalents. This runs first, before any confusable check.
+
+**Stage 2: Confusable map** catches characters that survive NFKC but visually mimic Latin letters — Cyrillic `а` for `a`, Greek `ο` for `o`, Cherokee `Ꭺ` for `A`, and 600+ others from the Unicode Consortium's [confusables.txt](https://unicode.org/Public/security/latest/confusables.txt).
+
+**Stage 3: Mixed-script rejection** (`rejectMixedScript: true`) blocks identifiers that mix Latin with non-Latin scripts (Hebrew, Arabic, Devanagari, Thai, Georgian, Ethiopic, etc.) even if the specific characters aren't in the confusable map. This catches novel homoglyphs that the map doesn't cover.
+
+#### Why NFKC-aware filtering matters
+
+The key insight: TR39's confusables.txt and NFKC normalization sometimes disagree. For example, Unicode says capital `I` (U+0049) is confusable with lowercase `l` — visually true in many fonts. But NFKC maps Mathematical Bold `𝐈` (U+1D408) to `I`, not `l`. If you naively ship the TR39 mapping (`𝐈` → `l`), the confusable check will never see that character — NFKC already converted it to `I` in stage 1.
+
+We found 31 entries where this happens:
+
+| Character | TR39 says | NFKC says | Winner |
+|-----------|-----------|-----------|--------|
+| `ſ` Long S (U+017F) | `f` | `s` | NFKC (`s` is correct) |
+| `Ⅰ` Roman Numeral I (U+2160) | `l` | `i` | NFKC (`i` is correct) |
+| `Ｉ` Fullwidth I (U+FF29) | `l` | `i` | NFKC (`i` is correct) |
+| `𝟎` Math Bold 0 (U+1D7CE) | `o` | `0` | NFKC (`0` is correct) |
+| 11 Mathematical I variants | `l` | `i` | NFKC |
+| 12 Mathematical 0/1 variants | `o`/`l` | `0`/`1` | NFKC |
+
+These entries are dead code in any pipeline that runs NFKC first — and worse, they encode the *wrong* mapping. The generate script (`scripts/generate-confusables.ts`) automatically detects and excludes them.
+
+## Unicode Normalization
+
+By default, `normalize()` applies [NFKC normalization](https://unicode.org/reports/tr15/) before lowercasing. This collapses full-width characters, ligatures, superscripts, and other Unicode compatibility forms to their canonical equivalents:
+
+```typescript
+normalize("ｈｅｌｌｏ");  // "hello" (full-width → ASCII)
+normalize("\ufb01nance"); // "finance" (fi ligature → fi)
+```
+
+NFKC is a no-op for ASCII input and matches what ENS, GitHub, and Unicode IDNA standards mandate. To opt out:
+
+```typescript
+const guard = createNamespaceGuard({
+  sources: [/* ... */],
+  normalizeUnicode: false,
+}, adapter);
+```
+
+## Rejecting Purely Numeric Identifiers
+
+Twitter/X blocks purely numeric handles. Enable this with `allowPurelyNumeric: false`:
+
+```typescript
+const guard = createNamespaceGuard({
+  sources: [/* ... */],
+  allowPurelyNumeric: false,
+  messages: {
+    purelyNumeric: "Handles cannot be all numbers.", // optional custom message
+  },
+}, adapter);
+
+await guard.check("123456"); // { available: false, reason: "invalid", message: "Handles cannot be all numbers." }
+await guard.check("abc123"); // available (has letters)
+```
+
 ## Conflict Suggestions
 
 When a slug is taken, automatically suggest available alternatives using pluggable strategies:
@@ -512,9 +607,9 @@ Validate format only (no database queries).
 
 ---
 
-### `normalize(identifier)`
+### `normalize(identifier, options?)`
 
-Utility function to normalize identifiers. Trims whitespace, lowercases, and strips leading `@` symbols.
+Utility function to normalize identifiers. Trims whitespace, applies NFKC Unicode normalization (by default), lowercases, and strips leading `@` symbols. Pass `{ unicode: false }` to skip NFKC.
 
 ```typescript
 import { normalize } from "namespace-guard";
@@ -664,6 +759,8 @@ Full TypeScript support with exported types:
 import {
   createNamespaceGuard,
   createProfanityValidator,
+  createHomoglyphValidator,
+  CONFUSABLE_MAP,
   normalize,
   type NamespaceConfig,
   type NamespaceSource,

package/dist/cli.js

@@ -266,8 +266,10 @@ function resolveGenerator(suggest, pattern) {
     return result;
   };
 }
-function normalize(raw) {
-  return raw.trim().toLowerCase().replace(/^@+/, "");
+function normalize(raw, options) {
+  const trimmed = raw.trim();
+  const nfkc = options?.unicode ?? true ? trimmed.normalize("NFKC") : trimmed;
+  return nfkc.toLowerCase().replace(/^@+/, "");
 }
 function buildReservedMap(reserved) {
   const map = /* @__PURE__ */ new Map();
@@ -291,6 +293,9 @@ function createNamespaceGuard(config, adapter) {
   const invalidMsg = configMessages.invalid ?? DEFAULT_MESSAGES.invalid;
   const takenMsg = configMessages.taken ?? DEFAULT_MESSAGES.taken;
   const validators = config.validators ?? [];
+  const normalizeOpts = { unicode: config.normalizeUnicode ?? true };
+  const allowPurelyNumeric = config.allowPurelyNumeric ?? true;
+  const purelyNumericMsg = configMessages.purelyNumeric ?? "Identifiers cannot be purely numeric.";
   const cacheEnabled = !!config.cache;
   const cacheTtl = config.cache?.ttl ?? 5e3;
   const cacheMaxSize = 1e3;
@@ -324,38 +329,44 @@ function createNamespaceGuard(config, adapter) {
     return defaultReservedMsg;
   }
   function validateFormat(identifier) {
-    const normalized = normalize(identifier);
+    const normalized = normalize(identifier, normalizeOpts);
     if (!pattern.test(normalized)) {
       return invalidMsg;
     }
+    if (!allowPurelyNumeric && /^\d+(-\d+)*$/.test(normalized)) {
+      return purelyNumericMsg;
+    }
     if (reservedMap.has(normalized)) {
       return getReservedMessage(reservedMap.get(normalized));
     }
     return null;
   }
+  function isOwnedByScope(existing, source, scope) {
+    if (!source.scopeKey) return false;
+    const scopeValue = scope[source.scopeKey];
+    const idColumn = source.idColumn ?? "id";
+    const existingId = existing[idColumn];
+    return !!(scopeValue && existingId && scopeValue === String(existingId));
+  }
   async function checkDbOnly(value, scope) {
     const findOptions = config.caseInsensitive ? { caseInsensitive: true } : void 0;
     const checks = config.sources.map(async (source) => {
       const existing = await cachedFindOne(source, value, findOptions);
       if (!existing) return null;
-      if (source.scopeKey) {
-        const scopeValue = scope[source.scopeKey];
-        const idColumn = source.idColumn ?? "id";
-        const existingId = existing[idColumn];
-        if (scopeValue && existingId && scopeValue === String(existingId)) {
-          return null;
-        }
-      }
+      if (isOwnedByScope(existing, source, scope)) return null;
       return source.name;
     });
     const results = await Promise.all(checks);
     return !results.some((r) => r !== null);
   }
   async function check(identifier, scope = {}, options) {
-    const normalized = normalize(identifier);
+    const normalized = normalize(identifier, normalizeOpts);
     if (!pattern.test(normalized)) {
       return { available: false, reason: "invalid", message: invalidMsg };
     }
+    if (!allowPurelyNumeric && /^\d+(-\d+)*$/.test(normalized)) {
+      return { available: false, reason: "invalid", message: purelyNumericMsg };
+    }
     const reservedCategory = reservedMap.get(normalized);
     if (reservedCategory) {
       return {
@@ -380,14 +391,7 @@ function createNamespaceGuard(config, adapter) {
     const checks = config.sources.map(async (source) => {
       const existing = await cachedFindOne(source, normalized, findOptions);
       if (!existing) return null;
-      if (source.scopeKey) {
-        const scopeValue = scope[source.scopeKey];
-        const idColumn = source.idColumn ?? "id";
-        const existingId = existing[idColumn];
-        if (scopeValue && existingId && scopeValue === String(existingId)) {
-          return null;
-        }
-      }
+      if (isOwnedByScope(existing, source, scope)) return null;
       return source.name;
     });
     const results = await Promise.all(checks);
@@ -405,7 +409,7 @@ function createNamespaceGuard(config, adapter) {
         const candidates = generate(normalized);
         const suggestions = [];
         const passedSync = candidates.filter(
-          (c) => pattern.test(c) && !reservedMap.has(c)
+          (c) => pattern.test(c) && !reservedMap.has(c) && (allowPurelyNumeric || !/^\d+(-\d+)*$/.test(c))
         );
         for (let i = 0; i < passedSync.length && suggestions.length < max; i += max) {
           const batch = passedSync.slice(i, i + max);

package/dist/cli.mjs

@@ -243,8 +243,10 @@ function resolveGenerator(suggest, pattern) {
     return result;
   };
 }
-function normalize(raw) {
-  return raw.trim().toLowerCase().replace(/^@+/, "");
+function normalize(raw, options) {
+  const trimmed = raw.trim();
+  const nfkc = options?.unicode ?? true ? trimmed.normalize("NFKC") : trimmed;
+  return nfkc.toLowerCase().replace(/^@+/, "");
 }
 function buildReservedMap(reserved) {
   const map = /* @__PURE__ */ new Map();
@@ -268,6 +270,9 @@ function createNamespaceGuard(config, adapter) {
   const invalidMsg = configMessages.invalid ?? DEFAULT_MESSAGES.invalid;
   const takenMsg = configMessages.taken ?? DEFAULT_MESSAGES.taken;
   const validators = config.validators ?? [];
+  const normalizeOpts = { unicode: config.normalizeUnicode ?? true };
+  const allowPurelyNumeric = config.allowPurelyNumeric ?? true;
+  const purelyNumericMsg = configMessages.purelyNumeric ?? "Identifiers cannot be purely numeric.";
   const cacheEnabled = !!config.cache;
   const cacheTtl = config.cache?.ttl ?? 5e3;
   const cacheMaxSize = 1e3;
@@ -301,38 +306,44 @@ function createNamespaceGuard(config, adapter) {
     return defaultReservedMsg;
   }
   function validateFormat(identifier) {
-    const normalized = normalize(identifier);
+    const normalized = normalize(identifier, normalizeOpts);
     if (!pattern.test(normalized)) {
       return invalidMsg;
     }
+    if (!allowPurelyNumeric && /^\d+(-\d+)*$/.test(normalized)) {
+      return purelyNumericMsg;
+    }
     if (reservedMap.has(normalized)) {
       return getReservedMessage(reservedMap.get(normalized));
     }
     return null;
   }
+  function isOwnedByScope(existing, source, scope) {
+    if (!source.scopeKey) return false;
+    const scopeValue = scope[source.scopeKey];
+    const idColumn = source.idColumn ?? "id";
+    const existingId = existing[idColumn];
+    return !!(scopeValue && existingId && scopeValue === String(existingId));
+  }
   async function checkDbOnly(value, scope) {
     const findOptions = config.caseInsensitive ? { caseInsensitive: true } : void 0;
     const checks = config.sources.map(async (source) => {
       const existing = await cachedFindOne(source, value, findOptions);
       if (!existing) return null;
-      if (source.scopeKey) {
-        const scopeValue = scope[source.scopeKey];
-        const idColumn = source.idColumn ?? "id";
-        const existingId = existing[idColumn];
-        if (scopeValue && existingId && scopeValue === String(existingId)) {
-          return null;
-        }
-      }
+      if (isOwnedByScope(existing, source, scope)) return null;
       return source.name;
     });
     const results = await Promise.all(checks);
     return !results.some((r) => r !== null);
   }
   async function check(identifier, scope = {}, options) {
-    const normalized = normalize(identifier);
+    const normalized = normalize(identifier, normalizeOpts);
     if (!pattern.test(normalized)) {
       return { available: false, reason: "invalid", message: invalidMsg };
     }
+    if (!allowPurelyNumeric && /^\d+(-\d+)*$/.test(normalized)) {
+      return { available: false, reason: "invalid", message: purelyNumericMsg };
+    }
     const reservedCategory = reservedMap.get(normalized);
     if (reservedCategory) {
       return {
@@ -357,14 +368,7 @@ function createNamespaceGuard(config, adapter) {
     const checks = config.sources.map(async (source) => {
       const existing = await cachedFindOne(source, normalized, findOptions);
       if (!existing) return null;
-      if (source.scopeKey) {
-        const scopeValue = scope[source.scopeKey];
-        const idColumn = source.idColumn ?? "id";
-        const existingId = existing[idColumn];
-        if (scopeValue && existingId && scopeValue === String(existingId)) {
-          return null;
-        }
-      }
+      if (isOwnedByScope(existing, source, scope)) return null;
       return source.name;
     });
     const results = await Promise.all(checks);
@@ -382,7 +386,7 @@ function createNamespaceGuard(config, adapter) {
         const candidates = generate(normalized);
         const suggestions = [];
         const passedSync = candidates.filter(
-          (c) => pattern.test(c) && !reservedMap.has(c)
+          (c) => pattern.test(c) && !reservedMap.has(c) && (allowPurelyNumeric || !/^\d+(-\d+)*$/.test(c))
         );
         for (let i = 0; i < passedSync.length && suggestions.length < max; i += max) {
           const batch = passedSync.slice(i, i + max);

package/dist/index.d.mts

@@ -21,11 +21,19 @@ type NamespaceConfig = {
     pattern?: RegExp;
     /** Use case-insensitive matching in database queries (default: false) */
     caseInsensitive?: boolean;
+    /** Apply NFKC Unicode normalization during normalize() (default: true).
+     *  Collapses full-width characters, ligatures, and compatibility forms to their canonical equivalents. */
+    normalizeUnicode?: boolean;
+    /** Allow purely numeric identifiers like "123" or "12-34" (default: true).
+     *  Set to false to reject them, matching Twitter/X handle rules. */
+    allowPurelyNumeric?: boolean;
     /** Custom error messages */
     messages?: {
         invalid?: string;
         reserved?: string | Record<string, string>;
         taken?: (sourceName: string) => string;
+        /** Message shown when a purely numeric identifier is rejected (default: "Identifiers cannot be purely numeric.") */
+        purelyNumeric?: string;
     };
     /** Async validation hooks — run after format/reserved checks, before DB */
     validators?: Array<(value: string) => Promise<{
@@ -73,18 +81,28 @@ type CheckResult = {
     suggestions?: string[];
 };
 /**
- * Normalize a raw identifier: trims whitespace, lowercases, and strips leading `@` symbols.
+ * Normalize a raw identifier: trims whitespace, applies NFKC Unicode normalization,
+ * lowercases, and strips leading `@` symbols.
+ *
+ * NFKC normalization collapses full-width characters, ligatures, superscripts,
+ * and other compatibility forms to their canonical equivalents. This is a no-op
+ * for ASCII-only input.
  *
  * @param raw - The raw user input
+ * @param options - Optional settings
+ * @param options.unicode - Apply NFKC Unicode normalization (default: true)
  * @returns The normalized identifier
  *
  * @example
  * ```ts
  * normalize("  @Sarah  "); // "sarah"
  * normalize("ACME-Corp");  // "acme-corp"
+ * normalize("\uff48\uff45\uff4c\uff4c\uff4f"); // "hello" (full-width → ASCII)
  * ```
  */
-declare function normalize(raw: string): string;
+declare function normalize(raw: string, options?: {
+    unicode?: boolean;
+}): string;
 /**
  * Create a validator that rejects identifiers containing profanity or offensive words.
  *
@@ -117,6 +135,48 @@ declare function createProfanityValidator(words: string[], options?: {
     available: false;
     message: string;
 } | null>;
+/**
+ * Mapping of visually confusable Unicode characters to their Latin/digit equivalents.
+ * Generated from Unicode TR39 confusables.txt + supplemental Latin small capitals.
+ * Covers every single-character mapping to a lowercase Latin letter or digit,
+ * excluding characters already handled by NFKC normalization (either collapsed
+ * to the same target, or mapped to a different valid Latin char/digit).
+ * Regenerate: `npx tsx scripts/generate-confusables.ts`
+ */
+declare const CONFUSABLE_MAP: Record<string, string>;
+/**
+ * Create a validator that rejects identifiers containing homoglyph/confusable characters.
+ *
+ * Catches spoofing attacks where characters from other scripts are substituted for
+ * visually identical Latin characters (e.g., Cyrillic "а" for Latin "a" in "admin").
+ * Uses a comprehensive mapping of 613 character pairs generated from Unicode TR39
+ * confusables.txt, covering Cyrillic, Greek, Armenian, Cherokee, IPA, Latin small
+ * capitals, Canadian Syllabics, Georgian, Lisu, Coptic, and many other scripts.
+ *
+ * @param options - Optional settings
+ * @param options.message - Custom rejection message (default: "That name contains characters that could be confused with other letters.")
+ * @param options.additionalMappings - Extra confusable pairs to merge with the built-in map
+ * @param options.rejectMixedScript - Also reject identifiers that mix Latin with non-Latin characters from any covered script (Cyrillic, Greek, Armenian, Hebrew, Arabic, Georgian, Cherokee, Canadian Syllabics, Ethiopic, Coptic, Lisu, and more) (default: false)
+ * @returns An async validator function for use in `config.validators`
+ *
+ * @example
+ * ```ts
+ * const guard = createNamespaceGuard({
+ *   sources: [{ name: "user", column: "handle" }],
+ *   validators: [
+ *     createHomoglyphValidator(),
+ *   ],
+ * }, adapter);
+ * ```
+ */
+declare function createHomoglyphValidator(options?: {
+    message?: string;
+    additionalMappings?: Record<string, string>;
+    rejectMixedScript?: boolean;
+}): (value: string) => Promise<{
+    available: false;
+    message: string;
+} | null>;
 /**
  * Create a namespace guard instance for checking slug/handle uniqueness
  * across multiple database tables with reserved name protection.
@@ -165,4 +225,4 @@ declare function createNamespaceGuard(config: NamespaceConfig, adapter: Namespac
 /** The guard instance returned by `createNamespaceGuard`. */
 type NamespaceGuard = ReturnType<typeof createNamespaceGuard>;
 
-export { type CheckResult, type FindOneOptions, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, type SuggestStrategyName, createNamespaceGuard, createProfanityValidator, normalize };
+export { CONFUSABLE_MAP, type CheckResult, type FindOneOptions, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, type SuggestStrategyName, createHomoglyphValidator, createNamespaceGuard, createProfanityValidator, normalize };

package/dist/index.d.ts

@@ -21,11 +21,19 @@ type NamespaceConfig = {
     pattern?: RegExp;
     /** Use case-insensitive matching in database queries (default: false) */
     caseInsensitive?: boolean;
+    /** Apply NFKC Unicode normalization during normalize() (default: true).
+     *  Collapses full-width characters, ligatures, and compatibility forms to their canonical equivalents. */
+    normalizeUnicode?: boolean;
+    /** Allow purely numeric identifiers like "123" or "12-34" (default: true).
+     *  Set to false to reject them, matching Twitter/X handle rules. */
+    allowPurelyNumeric?: boolean;
     /** Custom error messages */
     messages?: {
         invalid?: string;
         reserved?: string | Record<string, string>;
         taken?: (sourceName: string) => string;
+        /** Message shown when a purely numeric identifier is rejected (default: "Identifiers cannot be purely numeric.") */
+        purelyNumeric?: string;
     };
     /** Async validation hooks — run after format/reserved checks, before DB */
     validators?: Array<(value: string) => Promise<{
@@ -73,18 +81,28 @@ type CheckResult = {
     suggestions?: string[];
 };
 /**
- * Normalize a raw identifier: trims whitespace, lowercases, and strips leading `@` symbols.
+ * Normalize a raw identifier: trims whitespace, applies NFKC Unicode normalization,
+ * lowercases, and strips leading `@` symbols.
+ *
+ * NFKC normalization collapses full-width characters, ligatures, superscripts,
+ * and other compatibility forms to their canonical equivalents. This is a no-op
+ * for ASCII-only input.
  *
  * @param raw - The raw user input
+ * @param options - Optional settings
+ * @param options.unicode - Apply NFKC Unicode normalization (default: true)
  * @returns The normalized identifier
  *
  * @example
  * ```ts
  * normalize("  @Sarah  "); // "sarah"
  * normalize("ACME-Corp");  // "acme-corp"
+ * normalize("\uff48\uff45\uff4c\uff4c\uff4f"); // "hello" (full-width → ASCII)
  * ```
  */
-declare function normalize(raw: string): string;
+declare function normalize(raw: string, options?: {
+    unicode?: boolean;
+}): string;
 /**
  * Create a validator that rejects identifiers containing profanity or offensive words.
  *
@@ -117,6 +135,48 @@ declare function createProfanityValidator(words: string[], options?: {
     available: false;
     message: string;
 } | null>;
+/**
+ * Mapping of visually confusable Unicode characters to their Latin/digit equivalents.
+ * Generated from Unicode TR39 confusables.txt + supplemental Latin small capitals.
+ * Covers every single-character mapping to a lowercase Latin letter or digit,
+ * excluding characters already handled by NFKC normalization (either collapsed
+ * to the same target, or mapped to a different valid Latin char/digit).
+ * Regenerate: `npx tsx scripts/generate-confusables.ts`
+ */
+declare const CONFUSABLE_MAP: Record<string, string>;
+/**
+ * Create a validator that rejects identifiers containing homoglyph/confusable characters.
+ *
+ * Catches spoofing attacks where characters from other scripts are substituted for
+ * visually identical Latin characters (e.g., Cyrillic "а" for Latin "a" in "admin").
+ * Uses a comprehensive mapping of 613 character pairs generated from Unicode TR39
+ * confusables.txt, covering Cyrillic, Greek, Armenian, Cherokee, IPA, Latin small
+ * capitals, Canadian Syllabics, Georgian, Lisu, Coptic, and many other scripts.
+ *
+ * @param options - Optional settings
+ * @param options.message - Custom rejection message (default: "That name contains characters that could be confused with other letters.")
+ * @param options.additionalMappings - Extra confusable pairs to merge with the built-in map
+ * @param options.rejectMixedScript - Also reject identifiers that mix Latin with non-Latin characters from any covered script (Cyrillic, Greek, Armenian, Hebrew, Arabic, Georgian, Cherokee, Canadian Syllabics, Ethiopic, Coptic, Lisu, and more) (default: false)
+ * @returns An async validator function for use in `config.validators`
+ *
+ * @example
+ * ```ts
+ * const guard = createNamespaceGuard({
+ *   sources: [{ name: "user", column: "handle" }],
+ *   validators: [
+ *     createHomoglyphValidator(),
+ *   ],
+ * }, adapter);
+ * ```
+ */
+declare function createHomoglyphValidator(options?: {
+    message?: string;
+    additionalMappings?: Record<string, string>;
+    rejectMixedScript?: boolean;
+}): (value: string) => Promise<{
+    available: false;
+    message: string;
+} | null>;
 /**
  * Create a namespace guard instance for checking slug/handle uniqueness
  * across multiple database tables with reserved name protection.
@@ -165,4 +225,4 @@ declare function createNamespaceGuard(config: NamespaceConfig, adapter: Namespac
 /** The guard instance returned by `createNamespaceGuard`. */
 type NamespaceGuard = ReturnType<typeof createNamespaceGuard>;
 
-export { type CheckResult, type FindOneOptions, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, type SuggestStrategyName, createNamespaceGuard, createProfanityValidator, normalize };
+export { CONFUSABLE_MAP, type CheckResult, type FindOneOptions, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, type SuggestStrategyName, createHomoglyphValidator, createNamespaceGuard, createProfanityValidator, normalize };