@resq-systems/security 1.0.4 → 2.0.0

package/lib/unicode/confusables.mjs

@@ -0,0 +1,954 @@
+//#region src/unicode/confusables.ts
+/**
+* Copyright 2026 ResQ Systems, Inc.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*     http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+/**
+* @fileoverview Confusable-character data and UTS #39 skeleton generation.
+*
+* A *skeleton* is an opaque comparison key. Two strings whose skeletons are equal are
+* visually confusable; that is the only thing a skeleton means. It is not a normalized
+* identifier, it is not safe to display, and it must never be stored in place of what
+* the user actually typed — the point is to keep the original for display and compare
+* skeletons for collisions.
+*
+* Coverage is split in two:
+*
+* - **Algorithmic ranges** — fullwidth forms, mathematical alphanumerics, and
+*   enclosed/parenthesized letters are contiguous ranges at a fixed offset from
+*   ASCII, so they fold by computation rather than by table. That covers several
+*   thousand code points in a few lines.
+* - **A curated table** — the Cyrillic, Greek, Armenian, Cherokee, Coptic, and
+*   Canadian-Aboriginal glyphs that render like Latin letters, written as numeric
+*   code points so the source stays ASCII and every entry is reviewable in a diff.
+*
+* This is not the complete `confusables.txt` dataset (~6 000 mappings). It covers the
+* Latin-target subset, which is what matters for the identifiers this package guards:
+* usernames, domains, org names, package names. Callers needing full UTS #39 coverage
+* should layer a dedicated dataset on top and track Unicode's release cadence.
+*
+* @module @resq-systems/security/unicode/confusables
+*/
+/**
+* Confusable code points grouped by the ASCII prototype they fold to.
+*
+* Written as numeric code points on purpose. A table of raw lookalike glyphs is by
+* construction unreadable in review — the entries are supposed to be
+* indistinguishable from their targets — and one stray copy-paste produces exactly
+* the silent duplicate the previous `HOMOGLYPH_MAP` carried on its `a` row.
+*
+* The `l` and `o` rows fold across case (`I`, `l`, `1` all become `l`; `O`, `o`, `0`
+* all become `o`) because those glyph families are genuinely indistinguishable in
+* most typefaces. Every other row preserves case.
+*
+* Rows are keyed by the letter a code point **renders as**, not by its Unicode general
+* category, and the two disagree often enough to matter. A Greek, Cyrillic, Coptic or
+* Roman-numeral capital whose glyph is the Latin capital belongs in the uppercase row:
+* filing `Ρ` (U+03A1) under `p` folds it to `p` while `P` folds to `P`, so the spoof
+* pair an identifier check exists to catch compares as *not* confusable. The reverse
+* also happens — `Ƅ` (U+0184), `Ь` (U+042C), `Ꮟ` (U+13CF), `Ꮒ` (U+13C2), `Ꮷ` (U+13E7)
+* and `Ꭹ` (U+13A9) carry general category `Lu` but draw as lowercase shapes, so they
+* stay in the lowercase rows. An audit keyed on general category flags those six; they
+* are correct as written.
+*/
+const CONFUSABLES_BY_PROTOTYPE = {
+	a: [
+		1072,
+		945,
+		593,
+		594,
+		7424,
+		9082,
+		43898
+	],
+	b: [
+		388,
+		1068,
+		1100,
+		5071,
+		5551,
+		1074,
+		7427,
+		384
+	],
+	c: [
+		1089,
+		1010,
+		11429,
+		7428,
+		8573,
+		392
+	],
+	d: [
+		1281,
+		5095,
+		5231,
+		8518,
+		8574,
+		599,
+		7429
+	],
+	e: [
+		1077,
+		1213,
+		8494,
+		7431,
+		43826,
+		1108,
+		8455
+	],
+	f: [
+		383,
+		402,
+		989,
+		7837,
+		42905
+	],
+	g: [
+		609,
+		485,
+		1409,
+		5115,
+		7555,
+		8458
+	],
+	h: [
+		1211,
+		1392,
+		5058,
+		8462,
+		1163
+	],
+	i: [
+		1110,
+		953,
+		617,
+		8560,
+		8505,
+		305,
+		8126,
+		9075
+	],
+	j: [
+		1112,
+		1011,
+		1397,
+		8521
+	],
+	k: [
+		1082,
+		954,
+		7435,
+		11413,
+		312
+	],
+	l: [
+		73,
+		49,
+		124,
+		1231,
+		8467,
+		8572,
+		406,
+		448,
+		1472,
+		8544,
+		8556,
+		8739,
+		921,
+		1030,
+		8464,
+		322
+	],
+	m: [
+		1084,
+		8575,
+		7437,
+		653
+	],
+	n: [
+		1400,
+		7438,
+		627,
+		1404
+	],
+	o: [
+		79,
+		48,
+		1086,
+		1054,
+		959,
+		927,
+		1413,
+		1365,
+		1637,
+		1781,
+		2406,
+		2790,
+		3046,
+		3174,
+		7439,
+		11422,
+		11423,
+		2918,
+		4125,
+		7441
+	],
+	p: [
+		1088,
+		961,
+		9076,
+		7448,
+		11427
+	],
+	q: [
+		1307,
+		1379,
+		42839
+	],
+	r: [
+		1075,
+		7462,
+		11397,
+		1107,
+		638
+	],
+	s: [
+		1109,
+		42801,
+		445,
+		642
+	],
+	t: [
+		1090,
+		964,
+		7451,
+		355
+	],
+	u: [
+		965,
+		1405,
+		7452,
+		1094,
+		651
+	],
+	v: [
+		957,
+		1141,
+		8564,
+		8744,
+		7456
+	],
+	w: [
+		1309,
+		1377,
+		7457,
+		1096,
+		43907
+	],
+	x: [
+		1093,
+		967,
+		8569,
+		5741,
+		215
+	],
+	y: [
+		1091,
+		947,
+		655,
+		1199,
+		5033,
+		7935,
+		978
+	],
+	z: [
+		656,
+		7458,
+		42851,
+		438
+	],
+	A: [
+		1040,
+		913,
+		5034,
+		11373
+	],
+	B: [
+		1042,
+		914,
+		5108,
+		5623,
+		11394,
+		8492
+	],
+	C: [
+		1057,
+		1017,
+		8557,
+		5087,
+		8450,
+		8493,
+		11428
+	],
+	D: [
+		5024,
+		8558,
+		5610,
+		8517
+	],
+	E: [
+		1045,
+		917,
+		5036,
+		11577,
+		8496,
+		1212
+	],
+	F: [
+		988,
+		5556,
+		42904,
+		8497
+	],
+	G: [
+		1292,
+		5056,
+		42912,
+		1293,
+		11424
+	],
+	H: [
+		1053,
+		919,
+		5051,
+		8459,
+		11406,
+		8460,
+		8461
+	],
+	J: [
+		1032,
+		5035,
+		5261,
+		7434
+	],
+	K: [
+		1050,
+		922,
+		8490,
+		5094,
+		11412
+	],
+	L: [
+		5086,
+		7436,
+		11472,
+		8466,
+		5290
+	],
+	M: [
+		1052,
+		924,
+		5047,
+		11416,
+		8499,
+		8559
+	],
+	N: [
+		925,
+		11418,
+		8469,
+		628
+	],
+	P: [
+		5090,
+		8473,
+		5229,
+		1056,
+		929,
+		11426
+	],
+	Q: [
+		1306,
+		11605,
+		42838,
+		8474,
+		8506
+	],
+	R: [
+		5025,
+		5074,
+		7449,
+		422,
+		8475,
+		8477
+	],
+	S: [
+		11425,
+		536,
+		1029,
+		5082
+	],
+	T: [
+		1058,
+		932,
+		5026,
+		8868,
+		11430,
+		1006
+	],
+	U: [
+		1357,
+		8746,
+		1359
+	],
+	V: [
+		8548,
+		1140,
+		5081
+	],
+	W: [
+		5043,
+		1310,
+		1308
+	],
+	X: [
+		9587,
+		11437,
+		1061,
+		935,
+		8553,
+		11436
+	],
+	Y: [
+		1198,
+		8511,
+		1059,
+		933,
+		11432
+	],
+	Z: [
+		8484,
+		5060,
+		918,
+		5059,
+		11391
+	],
+	"2": [
+		423,
+		1e3,
+		42564,
+		5311
+	],
+	"3": [
+		1047,
+		1248,
+		439,
+		11468,
+		1177
+	],
+	"4": [5070, 5228],
+	"5": [444, 7549],
+	"6": [
+		1073,
+		5102,
+		1041
+	],
+	"7": [1216, 7548],
+	"8": [
+		546,
+		2819,
+		2538
+	],
+	"9": [
+		1641,
+		1785,
+		5101,
+		2407
+	],
+	"-": [
+		8208,
+		8209,
+		8210,
+		8211,
+		8212,
+		8213,
+		8722,
+		8259,
+		65112,
+		1418,
+		6150
+	],
+	".": [
+		1632,
+		1776,
+		8228,
+		42232,
+		1793,
+		1794
+	],
+	"/": [
+		8260,
+		8725,
+		9585,
+		10744,
+		5941,
+		12339
+	],
+	"\\": [
+		8726,
+		10741,
+		9586,
+		9290,
+		65128
+	],
+	"'": [
+		8216,
+		8217,
+		697,
+		700,
+		712,
+		1370,
+		1523,
+		8242
+	],
+	"\"": [
+		8220,
+		8221,
+		698,
+		1524,
+		8243
+	],
+	":": [
+		1417,
+		1475,
+		8758,
+		42889,
+		65072,
+		10626
+	],
+	";": [894, 65044],
+	"!": [
+		451,
+		11601,
+		65045
+	],
+	"?": [
+		660,
+		577,
+		2429,
+		5038
+	],
+	"(": [10088, 9115],
+	")": [10089, 9118],
+	"[": [10098, 12304],
+	"]": [10099, 12305],
+	"{": [10100],
+	"}": [10101],
+	"@": [3663],
+	"#": [11614],
+	$: [7839],
+	"%": [1642, 8274],
+	"&": [42872],
+	"*": [
+		1645,
+		8270,
+		8727,
+		66335
+	],
+	"+": [
+		5869,
+		10133,
+		10010
+	],
+	",": [
+		1549,
+		1643,
+		8218,
+		12289
+	],
+	"<": [
+		706,
+		5176,
+		8249,
+		10094
+	],
+	">": [
+		707,
+		5171,
+		8250,
+		10095
+	],
+	"=": [
+		11840,
+		12448,
+		42239
+	],
+	"~": [
+		732,
+		8128,
+		8275,
+		8764
+	],
+	"^": [708, 710],
+	_: [717, 65343],
+	"`": [715],
+	"|": [
+		10072,
+		65512,
+		2404
+	]
+};
+/**
+* Flattened lookup: confusable code point to its ASCII prototype.
+*
+* Later rows win on collision. That is intentional and harmless — a code point listed
+* under two prototypes is confusable with both, so either answer yields the same
+* collision behavior provided the choice is deterministic, which it is.
+*/
+const CONFUSABLE_MAP = (() => {
+	const map = /* @__PURE__ */ new Map();
+	for (const [prototype, codePoints] of Object.entries(CONFUSABLES_BY_PROTOTYPE)) for (const codePoint of codePoints) map.set(codePoint, prototype);
+	return map;
+})();
+/** Fullwidth `U+FF01`–`U+FF5E` map to `!`–`~` by subtracting this offset. */
+const FULLWIDTH_OFFSET = 65248;
+/** Lowest fullwidth form that folds to ASCII. */
+const FULLWIDTH_START = 65281;
+/** Highest fullwidth form that folds to ASCII. */
+const FULLWIDTH_END = 65374;
+/**
+* Contiguous ranges that fold to ASCII at a fixed offset from the range start.
+*
+* Each entry is `[rangeStart, rangeEnd, asciiStart]`. Handling these by computation
+* rather than by table folds several thousand code points — the mathematical
+* alphanumeric block alone is over 1 000 — without a single table row.
+*/
+const ALGORITHMIC_RANGES = [
+	[
+		119808,
+		119833,
+		65
+	],
+	[
+		119834,
+		119859,
+		97
+	],
+	[
+		119860,
+		119885,
+		65
+	],
+	[
+		119886,
+		119911,
+		97
+	],
+	[
+		119912,
+		119937,
+		65
+	],
+	[
+		119938,
+		119963,
+		97
+	],
+	[
+		119964,
+		119989,
+		65
+	],
+	[
+		119990,
+		120015,
+		97
+	],
+	[
+		120016,
+		120041,
+		65
+	],
+	[
+		120042,
+		120067,
+		97
+	],
+	[
+		120068,
+		120093,
+		65
+	],
+	[
+		120094,
+		120119,
+		97
+	],
+	[
+		120120,
+		120145,
+		65
+	],
+	[
+		120146,
+		120171,
+		97
+	],
+	[
+		120172,
+		120197,
+		65
+	],
+	[
+		120198,
+		120223,
+		97
+	],
+	[
+		120224,
+		120249,
+		65
+	],
+	[
+		120250,
+		120275,
+		97
+	],
+	[
+		120276,
+		120301,
+		65
+	],
+	[
+		120302,
+		120327,
+		97
+	],
+	[
+		120328,
+		120353,
+		65
+	],
+	[
+		120354,
+		120379,
+		97
+	],
+	[
+		120380,
+		120405,
+		65
+	],
+	[
+		120406,
+		120431,
+		97
+	],
+	[
+		120432,
+		120457,
+		65
+	],
+	[
+		120458,
+		120483,
+		97
+	],
+	[
+		120782,
+		120791,
+		48
+	],
+	[
+		120792,
+		120801,
+		48
+	],
+	[
+		120802,
+		120811,
+		48
+	],
+	[
+		120812,
+		120821,
+		48
+	],
+	[
+		120822,
+		120831,
+		48
+	],
+	[
+		9398,
+		9423,
+		65
+	],
+	[
+		9424,
+		9449,
+		97
+	],
+	[
+		9372,
+		9397,
+		97
+	],
+	[
+		127280,
+		127305,
+		65
+	],
+	[
+		127312,
+		127337,
+		65
+	],
+	[
+		127344,
+		127369,
+		65
+	]
+];
+/**
+* {@link ALGORITHMIC_RANGES} as start-sorted parallel arrays, built once at module load.
+*
+* The literal above stays the source of truth because it is grouped for reading — maths
+* alphanumerics, then digits, then enclosed forms — which leaves it unsorted, so it can
+* only be searched linearly. Sorting a derived copy allows a binary search without
+* reordering the table a reviewer reads.
+*/
+const [RANGE_STARTS, RANGE_ENDS, RANGE_ASCII_STARTS] = (() => {
+	const sorted = [...ALGORITHMIC_RANGES].sort((a, b) => a[0] - b[0]);
+	return [
+		Int32Array.from(sorted, (range) => range[0]),
+		Int32Array.from(sorted, (range) => range[1]),
+		Int32Array.from(sorted, (range) => range[2])
+	];
+})();
+/** Lowest code point covered by any algorithmic range. */
+const MIN_RANGE_START = RANGE_STARTS[0];
+/** Highest code point covered by any algorithmic range. */
+const MAX_RANGE_END = RANGE_ENDS.reduce((max, end) => end > max ? end : max, 0);
+/**
+* Fold one code point to its ASCII prototype.
+*
+* @param codePoint - Code point to fold.
+* @returns The ASCII prototype, or `null` when the code point is not confusable with
+*   anything in the ASCII range.
+*/
+function foldCodePoint(codePoint) {
+	if (codePoint >= FULLWIDTH_START && codePoint <= FULLWIDTH_END) return String.fromCodePoint(codePoint - FULLWIDTH_OFFSET);
+	if (codePoint >= MIN_RANGE_START && codePoint <= MAX_RANGE_END) {
+		let low = 0;
+		let high = RANGE_STARTS.length - 1;
+		while (low <= high) {
+			const mid = low + high >> 1;
+			if (codePoint < RANGE_STARTS[mid]) high = mid - 1;
+			else if (codePoint > RANGE_ENDS[mid]) low = mid + 1;
+			else {
+				const offset = codePoint - RANGE_STARTS[mid];
+				return String.fromCodePoint(RANGE_ASCII_STARTS[mid] + offset);
+			}
+		}
+	}
+	return CONFUSABLE_MAP.get(codePoint) ?? null;
+}
+/** Combining marks, dropped during skeleton generation. */
+const COMBINING_MARKS = /\p{M}/gu;
+/** Default-ignorable and zero-width code points, which contribute nothing visually. */
+const INVISIBLE_CODE_POINTS = /[\u00ad\u200b-\u200f\u2060-\u2064\ufeff\u202a-\u202e\u2066-\u2069]/g;
+/**
+* Generate a UTS #39-style confusable skeleton.
+*
+* Pipeline: decompose to NFD, drop invisible and combining code points, fold each
+* remaining code point through the confusable tables, recompose to NFC.
+*
+* Two strings with equal skeletons are visually confusable. That is *all* an equal
+* skeleton means — in particular it does not mean the strings are equivalent, and the
+* skeleton is neither a display nor a storage form. Accents are dropped and the
+* `I/l/1` and `O/o/0` families collapse across case, so `José`, `Jose`, and `J0sé`
+* share a skeleton by design.
+*
+* @param input - Raw string. Non-string or empty input yields `""`.
+* @returns The comparison key.
+*
+* @example
+* ```ts
+* // Cyrillic а in an otherwise Latin string.
+* getSkeleton("pаypal") === getSkeleton("paypal"); // true
+* getSkeleton("paypaI") === getSkeleton("paypal");      // true — I folds to l
+* ```
+*/
+function getSkeleton(input) {
+	if (!input || typeof input !== "string") return "";
+	const decomposed = input.normalize("NFD").replace(INVISIBLE_CODE_POINTS, "").replace(COMBINING_MARKS, "");
+	let skeleton = "";
+	for (const character of decomposed) {
+		const codePoint = character.codePointAt(0);
+		if (codePoint === void 0) continue;
+		skeleton += foldCodePoint(codePoint) ?? character;
+	}
+	return skeleton.normalize("NFC");
+}
+/**
+* Map non-ASCII lookalike characters onto their ASCII prototypes, preserving
+* everything else.
+*
+* Unlike {@link getSkeleton} this is a *conservative* transform: accents and other
+* combining marks survive, ASCII characters are never rewritten, and the result stays
+* readable. `Ολγα` keeps its Greek letters only insofar as they are not Latin
+* lookalikes; `café` stays `café`.
+*
+* Even so, prefer {@link getSkeleton} for collision checks and keep the original for
+* display. Rewriting a user's identifier into a different string is a lossy operation
+* that this function can only make *look* safe.
+*
+* @param input - Raw string. Non-string or empty input yields `""`.
+* @returns NFC-composed string with non-ASCII confusables folded to ASCII.
+*
+* @example
+* ```ts
+* foldConfusables("pаypal"); // "paypal" — Cyrillic а folded
+* foldConfusables("café");    // "café"   — accent preserved
+* foldConfusables("HELLO");   // "HELLO"  — ASCII untouched
+* ```
+*/
+function foldConfusables(input) {
+	if (!input || typeof input !== "string") return "";
+	let folded = "";
+	for (const character of input.normalize("NFC")) {
+		const codePoint = character.codePointAt(0);
+		if (codePoint === void 0) continue;
+		folded += codePoint <= 127 ? character : foldCodePoint(codePoint) ?? character;
+	}
+	return folded.normalize("NFC");
+}
+/**
+* Test whether two distinct strings are visually confusable.
+*
+* @param left - First string.
+* @param right - Second string.
+* @returns `true` when the strings differ but their skeletons match.
+*/
+function areConfusable(left, right) {
+	if (left === right) return false;
+	return getSkeleton(left) === getSkeleton(right);
+}
+//#endregion
+export { CONFUSABLE_MAP, areConfusable, foldConfusables, getSkeleton };
+
+//# sourceMappingURL=confusables.mjs.map