namespace-guard 0.7.0 → 0.8.2

package/README.md

@@ -299,7 +299,7 @@ No words are bundled — use any word list you like (e.g., the `bad-words` npm p
 
 ### Built-in Homoglyph Validator
 
-Prevent spoofing attacks where Cyrillic or Greek characters are substituted for visually identical Latin letters (e.g., Cyrillic "а" for Latin "a" in "admin"):
+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";
@@ -318,11 +318,43 @@ Options:
 createHomoglyphValidator({
   message: "Custom rejection message.",       // optional
   additionalMappings: { "\u0261": "g" },      // extend the built-in map
-  rejectMixedScript: true,                    // also reject Latin + Cyrillic/Greek mixing
+  rejectMixedScript: true,                    // also reject Latin + non-Latin script mixing
 })
 ```
 
-The built-in `CONFUSABLE_MAP` covers ~30 Cyrillic-to-Latin and Greek-to-Latin pairs — the most common spoofing vectors. It's exported for inspection or extension.
+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
 
@@ -616,7 +648,8 @@ Enable in-memory caching to reduce database calls during rapid checks (e.g., liv
 const guard = createNamespaceGuard({
   sources: [/* ... */],
   cache: {
-    ttl: 5000, // milliseconds (default: 5000)
+    ttl: 5000,     // milliseconds (default: 5000)
+    maxSize: 1000, // max cached entries before LRU eviction (default: 1000)
   },
 }, adapter);
 

package/dist/adapters/raw.d.mts

@@ -3,32 +3,6 @@ import { NamespaceAdapter } from '../index.mjs';
 type QueryExecutor = (sql: string, params: unknown[]) => Promise<{
     rows: Record<string, unknown>[];
 }>;
-/**
- * Create a namespace adapter for raw SQL queries
- *
- * Works with PostgreSQL-compatible clients that use $1-style parameter placeholders (pg).
- * For MySQL or SQLite, wrap the executor to translate parameter syntax.
- *
- * @example
- * ```ts
- * import { Pool } from "pg";
- * import { createNamespaceGuard } from "namespace-guard";
- * import { createRawAdapter } from "namespace-guard/adapters/raw";
- *
- * const pool = new Pool();
- *
- * const guard = createNamespaceGuard(
- *   {
- *     reserved: ["admin", "api", "settings"],
- *     sources: [
- *       { name: "users", column: "handle", scopeKey: "id" },
- *       { name: "organizations", column: "slug", scopeKey: "id" },
- *     ],
- *   },
- *   createRawAdapter((sql, params) => pool.query(sql, params))
- * );
- * ```
- */
 declare function createRawAdapter(execute: QueryExecutor): NamespaceAdapter;
 
 export { createRawAdapter };

package/dist/adapters/raw.d.ts

@@ -3,32 +3,6 @@ import { NamespaceAdapter } from '../index.js';
 type QueryExecutor = (sql: string, params: unknown[]) => Promise<{
     rows: Record<string, unknown>[];
 }>;
-/**
- * Create a namespace adapter for raw SQL queries
- *
- * Works with PostgreSQL-compatible clients that use $1-style parameter placeholders (pg).
- * For MySQL or SQLite, wrap the executor to translate parameter syntax.
- *
- * @example
- * ```ts
- * import { Pool } from "pg";
- * import { createNamespaceGuard } from "namespace-guard";
- * import { createRawAdapter } from "namespace-guard/adapters/raw";
- *
- * const pool = new Pool();
- *
- * const guard = createNamespaceGuard(
- *   {
- *     reserved: ["admin", "api", "settings"],
- *     sources: [
- *       { name: "users", column: "handle", scopeKey: "id" },
- *       { name: "organizations", column: "slug", scopeKey: "id" },
- *     ],
- *   },
- *   createRawAdapter((sql, params) => pool.query(sql, params))
- * );
- * ```
- */
 declare function createRawAdapter(execute: QueryExecutor): NamespaceAdapter;
 
 export { createRawAdapter };

package/dist/adapters/raw.js

@@ -23,10 +23,20 @@ __export(raw_exports, {
   createRawAdapter: () => createRawAdapter
 });
 module.exports = __toCommonJS(raw_exports);
+var SAFE_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function assertSafeIdentifier(name, label) {
+  if (!SAFE_IDENTIFIER.test(name)) {
+    throw new Error(`Unsafe ${label}: ${JSON.stringify(name)}. Use only letters, digits, and underscores.`);
+  }
+}
 function createRawAdapter(execute) {
   return {
     async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
+      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 whereClause = options?.caseInsensitive ? `LOWER("${source.column}") = LOWER($1)` : `"${source.column}" = $1`;
       const sql = `SELECT ${columns} FROM "${source.name}" WHERE ${whereClause} LIMIT 1`;

package/dist/adapters/raw.mjs

@@ -1,8 +1,18 @@
 // src/adapters/raw.ts
+var SAFE_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function assertSafeIdentifier(name, label) {
+  if (!SAFE_IDENTIFIER.test(name)) {
+    throw new Error(`Unsafe ${label}: ${JSON.stringify(name)}. Use only letters, digits, and underscores.`);
+  }
+}
 function createRawAdapter(execute) {
   return {
     async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
+      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 whereClause = options?.caseInsensitive ? `LOWER("${source.column}") = LOWER($1)` : `"${source.column}" = $1`;
       const sql = `SELECT ${columns} FROM "${source.name}" WHERE ${whereClause} LIMIT 1`;

package/dist/cli.js

@@ -144,14 +144,12 @@ function createScrambleStrategy(_pattern) {
     const candidates = [];
     const chars = identifier.split("");
     for (let i = 0; i < chars.length - 1; i++) {
-      if (chars[i] !== chars[i + 1]) {
-        const swapped = [...chars];
-        [swapped[i], swapped[i + 1]] = [swapped[i + 1], swapped[i]];
-        const candidate = swapped.join("");
-        if (candidate !== identifier && !seen.has(candidate)) {
-          seen.add(candidate);
-          candidates.push(candidate);
-        }
+      const swapped = [...chars];
+      [swapped[i], swapped[i + 1]] = [swapped[i + 1], swapped[i]];
+      const candidate = swapped.join("");
+      if (candidate !== identifier && !seen.has(candidate)) {
+        seen.add(candidate);
+        candidates.push(candidate);
       }
     }
     return candidates;
@@ -298,7 +296,7 @@ function createNamespaceGuard(config, adapter) {
   const purelyNumericMsg = configMessages.purelyNumeric ?? "Identifiers cannot be purely numeric.";
   const cacheEnabled = !!config.cache;
   const cacheTtl = config.cache?.ttl ?? 5e3;
-  const cacheMaxSize = 1e3;
+  const cacheMaxSize = config.cache?.maxSize ?? 1e3;
   const cacheMap = /* @__PURE__ */ new Map();
   let cacheHits = 0;
   let cacheMisses = 0;
@@ -488,10 +486,20 @@ function createNamespaceGuard(config, adapter) {
 }
 
 // src/adapters/raw.ts
+var SAFE_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function assertSafeIdentifier(name, label) {
+  if (!SAFE_IDENTIFIER.test(name)) {
+    throw new Error(`Unsafe ${label}: ${JSON.stringify(name)}. Use only letters, digits, and underscores.`);
+  }
+}
 function createRawAdapter(execute) {
   return {
     async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
+      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 whereClause = options?.caseInsensitive ? `LOWER("${source.column}") = LOWER($1)` : `"${source.column}" = $1`;
       const sql = `SELECT ${columns} FROM "${source.name}" WHERE ${whereClause} LIMIT 1`;
@@ -574,6 +582,10 @@ async function createDatabaseAdapter(url) {
     process.exit(1);
   }
   const Pool = pg.default?.Pool ?? pg.Pool;
+  if (!Pool) {
+    console.error("Could not find Pool export from pg package. Check your pg version.");
+    process.exit(1);
+  }
   const pool = new Pool({ connectionString: url });
   return {
     adapter: createRawAdapter((sql, params) => pool.query(sql, params)),

package/dist/cli.mjs

@@ -121,14 +121,12 @@ function createScrambleStrategy(_pattern) {
     const candidates = [];
     const chars = identifier.split("");
     for (let i = 0; i < chars.length - 1; i++) {
-      if (chars[i] !== chars[i + 1]) {
-        const swapped = [...chars];
-        [swapped[i], swapped[i + 1]] = [swapped[i + 1], swapped[i]];
-        const candidate = swapped.join("");
-        if (candidate !== identifier && !seen.has(candidate)) {
-          seen.add(candidate);
-          candidates.push(candidate);
-        }
+      const swapped = [...chars];
+      [swapped[i], swapped[i + 1]] = [swapped[i + 1], swapped[i]];
+      const candidate = swapped.join("");
+      if (candidate !== identifier && !seen.has(candidate)) {
+        seen.add(candidate);
+        candidates.push(candidate);
       }
     }
     return candidates;
@@ -275,7 +273,7 @@ function createNamespaceGuard(config, adapter) {
   const purelyNumericMsg = configMessages.purelyNumeric ?? "Identifiers cannot be purely numeric.";
   const cacheEnabled = !!config.cache;
   const cacheTtl = config.cache?.ttl ?? 5e3;
-  const cacheMaxSize = 1e3;
+  const cacheMaxSize = config.cache?.maxSize ?? 1e3;
   const cacheMap = /* @__PURE__ */ new Map();
   let cacheHits = 0;
   let cacheMisses = 0;
@@ -465,10 +463,20 @@ function createNamespaceGuard(config, adapter) {
 }
 
 // src/adapters/raw.ts
+var SAFE_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function assertSafeIdentifier(name, label) {
+  if (!SAFE_IDENTIFIER.test(name)) {
+    throw new Error(`Unsafe ${label}: ${JSON.stringify(name)}. Use only letters, digits, and underscores.`);
+  }
+}
 function createRawAdapter(execute) {
   return {
     async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
+      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 whereClause = options?.caseInsensitive ? `LOWER("${source.column}") = LOWER($1)` : `"${source.column}" = $1`;
       const sql = `SELECT ${columns} FROM "${source.name}" WHERE ${whereClause} LIMIT 1`;
@@ -551,6 +559,10 @@ async function createDatabaseAdapter(url) {
     process.exit(1);
   }
   const Pool = pg.default?.Pool ?? pg.Pool;
+  if (!Pool) {
+    console.error("Could not find Pool export from pg package. Check your pg version.");
+    process.exit(1);
+  }
   const pool = new Pool({ connectionString: url });
   return {
     adapter: createRawAdapter((sql, params) => pool.query(sql, params)),

package/dist/index.d.mts

@@ -53,6 +53,8 @@ type NamespaceConfig = {
     cache?: {
         /** Time-to-live in milliseconds (default: 5000) */
         ttl?: number;
+        /** Maximum number of cached entries before LRU eviction (default: 1000) */
+        maxSize?: number;
     };
 };
 /** Options passed to adapter `findOne` calls. */
@@ -136,22 +138,27 @@ declare function createProfanityValidator(words: string[], options?: {
     message: string;
 } | null>;
 /**
- * Default mapping of visually confusable Unicode characters to their Latin equivalents.
- * Covers Cyrillic-to-Latin and Greek-to-Latin lookalikes — the most common spoofing vectors.
- * Exported for advanced users who need to inspect or extend the mapping.
+ * 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 Cyrillic or Greek characters are substituted for
+ * 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 curated mapping of ~30 character pairs that covers 95%+ of real impersonation attempts.
+ * 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 Cyrillic/Greek characters (default: false)
+ * @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

package/dist/index.d.ts

@@ -53,6 +53,8 @@ type NamespaceConfig = {
     cache?: {
         /** Time-to-live in milliseconds (default: 5000) */
         ttl?: number;
+        /** Maximum number of cached entries before LRU eviction (default: 1000) */
+        maxSize?: number;
     };
 };
 /** Options passed to adapter `findOne` calls. */
@@ -136,22 +138,27 @@ declare function createProfanityValidator(words: string[], options?: {
     message: string;
 } | null>;
 /**
- * Default mapping of visually confusable Unicode characters to their Latin equivalents.
- * Covers Cyrillic-to-Latin and Greek-to-Latin lookalikes — the most common spoofing vectors.
- * Exported for advanced users who need to inspect or extend the mapping.
+ * 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 Cyrillic or Greek characters are substituted for
+ * 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 curated mapping of ~30 character pairs that covers 95%+ of real impersonation attempts.
+ * 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 Cyrillic/Greek characters (default: false)
+ * @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