@resq-systems/security 1.0.5 → 2.0.0

package/lib/threats/types.d.mts

@@ -0,0 +1,245 @@
+//#region src/threats/types.d.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 Vocabulary for the threat rule engine — weakness categories, sink
+ * contexts, severity/confidence grades, and the {@link ThreatRule} /
+ * {@link ThreatFinding} shapes that carry them. Everything here is data-only so the
+ * rule catalog, the scanner, and the scoring policy can be reasoned about (and
+ * unit-tested) independently.
+ *
+ * Design note: rules are *telemetry and defense-in-depth*, not the primary control.
+ * The primary control for each category is the sink-appropriate one — parameterized
+ * queries for SQL, a parser-based sanitizer for HTML, canonicalize-and-contain for
+ * filesystem paths, argv-array process spawning for shells. Each rule names its own
+ * in {@link ThreatRule.primaryControl}.
+ *
+ * @module @resq-systems/security/threats/types
+ */
+/**
+ * The closed set of weakness categories the engine recognizes.
+ *
+ * Serves as the discriminant of {@link ThreatFinding} and drives the exhaustive
+ * `switch` in `getThreatErrorMessage` — adding a variant here without a matching
+ * `case` there is a compile error via `assertNever`.
+ *
+ * Categories follow the OWASP Web Security Testing Guide's input-validation chapter
+ * so findings map onto an established taxonomy rather than package-local names.
+ */
+type ThreatType = "xss" | "sql_injection" | "nosql_injection" | "command_injection" | "path_traversal" | "prototype_pollution" | "homoglyph" | "header_injection" | "ldap_injection" | "xpath_injection" | "xml_injection" | "template_injection" | "file_inclusion" | "ssrf" | "formula_injection" | "log_injection" | "prompt_injection" | "parameter_pollution" | "credential_exposure" | "jwt_tampering" | "double_encoding" | "resource_abuse";
+/**
+ * The sink a value is destined for. Rules declare which contexts they apply to, and
+ * the scanner only evaluates rules matching the caller's declared contexts.
+ *
+ * This is the single most important false-positive control in the package: a
+ * biography containing `C:\Windows`, a support ticket containing `1=1`, and a code
+ * snippet containing `eval(` are all perfectly legitimate `general_text`. They are
+ * only suspicious when the value actually reaches a filesystem, SQL, or HTML sink.
+ *
+ * - `general_text` — free-form prose. Only near-universally hostile signals apply
+ *   (invisible/bidirectional control characters, null bytes).
+ * - `html` — rendered as HTML or interpolated into markup.
+ * - `sql` / `nosql` — reaches a database query builder or driver.
+ * - `shell` — reaches a child process, especially with `shell: true`.
+ * - `filesystem` — becomes part of a path passed to `fs`.
+ * - `url` — fetched server-side, or used to build such a request.
+ * - `url_parameter` — a *single value* about to be concatenated into a query string.
+ *   Distinct from `url`, where `&name=` is the normal grammar rather than evidence of
+ *   an injected parameter — the same distinction `http_header` draws against a whole
+ *   request.
+ * - `http_header` — written into an HTTP or email header value.
+ * - `jwt` — a JSON Web Token, or an already-decoded JWT header. Scoped narrowly on
+ *   purpose: re-scanning a whole opaque token with every detector is the
+ *   run-everything-against-everything anti-pattern this package exists to avoid. To
+ *   check a `kid` or `jku` claim, extract it and declare *its* real sink
+ *   (`filesystem`, `sql`, `url`).
+ * - `identifier` — a username, domain, org name, package name, or brand-adjacent
+ *   label where confusable-glyph collisions matter.
+ * - `object_merge` — parsed into an object graph that is then merged, cloned, or
+ *   assigned property-by-property (`Object.assign`, `lodash.merge`, query-string
+ *   expansion). This is prototype pollution's actual sink.
+ * - `template` — concatenated into template *source* (as opposed to passed as data).
+ * - `xml` — parsed by an XML/SOAP/SVG parser.
+ * - `ldap` / `xpath` — becomes part of an LDAP filter/DN or an XPath expression.
+ * - `spreadsheet` — exported to CSV/XLSX and opened by a spreadsheet application.
+ * - `log` — written to a line-based or structured log sink.
+ * - `llm_prompt` — concatenated into an LLM prompt or reachable by a tool-using agent.
+ */
+type ThreatContext = "general_text" | "html" | "sql" | "nosql" | "shell" | "filesystem" | "url" | "url_parameter" | "http_header" | "jwt" | "identifier" | "object_merge" | "template" | "xml" | "ldap" | "xpath" | "spreadsheet" | "log" | "llm_prompt";
+/** Every {@link ThreatContext} value, for iteration and "scan every sink" callers. */
+declare const ALL_THREAT_CONTEXTS: readonly ["general_text", "html", "sql", "nosql", "shell", "filesystem", "url", "url_parameter", "http_header", "jwt", "identifier", "object_merge", "template", "xml", "ldap", "xpath", "spreadsheet", "log", "llm_prompt"];
+/**
+ * How bad the weakness is if the match is a true positive. Independent of how
+ * likely the match is to *be* a true positive — that is {@link ThreatConfidence}.
+ */
+type ThreatSeverity = "low" | "medium" | "high" | "critical";
+/**
+ * How likely a match is to be a real attack rather than benign content that
+ * happens to look like one.
+ *
+ * - `low` — fires on ordinary content regularly (e.g. the substring `1=1`).
+ * - `medium` — unusual in ordinary content but not impossible.
+ * - `high` — has essentially no benign explanation in the declared context.
+ */
+type ThreatConfidence = "low" | "medium" | "high";
+/** Base anomaly points contributed by a finding, before the confidence multiplier. */
+declare const SEVERITY_WEIGHTS: Readonly<Record<ThreatSeverity, number>>;
+/** Scales {@link SEVERITY_WEIGHTS} by how trustworthy the signature is. */
+declare const CONFIDENCE_MULTIPLIERS: Readonly<Record<ThreatConfidence, number>>;
+/** Ordering helper for `minSeverity` filtering. Higher is worse. */
+declare const SEVERITY_ORDER: Readonly<Record<ThreatSeverity, number>>;
+/**
+ * Which representation of the input a rule matched against.
+ *
+ * Attack signatures are routinely bypassed by encoding, so the scanner evaluates a
+ * small, bounded set of representations rather than the raw bytes alone. Findings
+ * record which one matched, so operators can tell "the request literally contained
+ * `../`" apart from "the request contained `%2e%2e%2f`, which only becomes `../` if
+ * a downstream component decodes it".
+ */
+type InputVariantKind = "raw" | "nfc" | "nfkc" | "percent_decoded" | "html_decoded";
+/** One representation of the scanned input. */
+interface InputVariant {
+  /** Which transformation produced {@link InputVariant.value}. */
+  readonly kind: InputVariantKind;
+  /** The transformed string. */
+  readonly value: string;
+}
+/**
+ * A single signature in the catalog.
+ *
+ * @remarks
+ * `pattern` **must not** carry the global (`g`) or sticky (`y`) flag. Those flags
+ * make `RegExp` objects stateful via `lastIndex`, and the catalog is module-scoped
+ * and shared across every call — a stateful rule would silently skip matches on
+ * alternating invocations. `assertRuleCatalogIsValid` enforces this at load time.
+ */
+interface ThreatRule {
+  /** Stable identifier (e.g. `PATH-TRAVERSAL-ENCODED-001`). Never reused once retired. */
+  readonly id: string;
+  /** Weakness category this rule evidences. */
+  readonly type: ThreatType;
+  /** Sinks for which this rule is meaningful. Never empty. */
+  readonly contexts: readonly ThreatContext[];
+  /** Impact if the match is real. */
+  readonly severity: ThreatSeverity;
+  /** Likelihood the match is real rather than benign lookalike content. */
+  readonly confidence: ThreatConfidence;
+  /** One-line description for operators and log lines. Not user-facing. */
+  readonly description: string;
+  /** MITRE CWE identifier for the weakness, when one applies cleanly. */
+  readonly cwe?: number;
+  /**
+   * The control that actually prevents this weakness. Signatures detect; they do
+   * not prevent. Surfaced on findings so a reviewer reading an alert is pointed at
+   * the fix rather than at a tighter regex.
+   */
+  readonly primaryControl: string;
+  /** The signature. Must be non-global and non-sticky — see the remark above. */
+  readonly pattern: RegExp;
+  /**
+   * Restrict this rule to specific input representations. Defaults to every
+   * variant. Used by rules whose whole purpose is detecting an encoding (e.g. the
+   * percent-encoded traversal rule, which is only meaningful against `raw`).
+   */
+  readonly variants?: readonly InputVariantKind[];
+}
+/** A rule that matched, plus where and in which representation. */
+interface ThreatFinding {
+  /** {@link ThreatRule.id} of the rule that fired. */
+  readonly ruleId: string;
+  /** Copied from the rule — the weakness category. */
+  readonly type: ThreatType;
+  /** Copied from the rule. */
+  readonly severity: ThreatSeverity;
+  /** Copied from the rule. */
+  readonly confidence: ThreatConfidence;
+  /** Copied from the rule. Operator-facing; never render to end users. */
+  readonly description: string;
+  /** Copied from the rule, when present. */
+  readonly cwe?: number;
+  /** Copied from the rule — the control that actually fixes this. */
+  readonly primaryControl: string;
+  /** Which representation matched. */
+  readonly variant: InputVariantKind;
+  /** Matched substring, truncated to 50 characters so logs cannot be flooded. */
+  readonly matchedPattern?: string;
+  /** Match start offset *within the matched variant*, not within the raw input. */
+  readonly start?: number;
+  /** Match end offset (exclusive) within the matched variant. */
+  readonly end?: number;
+}
+/**
+ * Where an untrusted value entered the application.
+ *
+ * The counterpart to {@link ThreatContext}, which names the *sink*. A context says where
+ * a value is going and decides which rules run; a source says where it came from and
+ * decides nothing — it is carried through so a finding can be attributed later.
+ *
+ * Both halves together are what makes a finding actionable: "SQL keywords in a value
+ * bound to a SQL query" is a bug report, while "SQL keywords arriving in a query
+ * parameter from one account, forty times in a minute" is an incident.
+ */
+type InputSource = "http.query" | "http.body" | "http.header" | "http.path" | "http.cookie" | "websocket.message" | "cli.argument" | "file.upload" | "database" | "external.api" | "internal";
+/**
+ * Who and what a scan belongs to, carried through so findings can be correlated.
+ *
+ * Modelled on OWASP AppSensor, whose argument is that application-layer intrusion
+ * detection is about *sequences* attributed to an actor, not about individual strings. A
+ * single `review` verdict is ordinarily noise; thirty of them from one account inside a
+ * minute is an attack in progress, and nothing in a per-string API can express the
+ * difference.
+ *
+ * Every field is optional and none affects detection. The scanner does not resolve,
+ * validate or store any of them — it echoes them onto the result so a logging or SIEM
+ * pipeline can join findings to a request and an actor without threading a correlation id
+ * through its own call stack.
+ *
+ * Treat `actorId` as personal data: it reaches whatever sink the findings reach, so pass
+ * an opaque identifier rather than an email address, or redact downstream with
+ * `sanitizeForLogging`.
+ */
+interface EventContext {
+  /** Correlates every finding raised while handling one request. */
+  readonly requestId?: string;
+  /** The authenticated principal, if any. Opaque — never an email address. */
+  readonly actorId?: string;
+  /** The session the request belongs to, for sequence detection across requests. */
+  readonly sessionId?: string;
+  /** Where the value entered the application. */
+  readonly source?: InputSource;
+}
+/**
+ * Policy outcome derived from the anomaly score.
+ *
+ * Scoring rather than first-match rejection is deliberate: any individual signature
+ * produces false positives, so a single low-confidence hit should raise a signal,
+ * not reject a form submission. This mirrors how OWASP CRS uses anomaly scoring with
+ * tunable thresholds instead of one-rule-one-block.
+ */
+type ThreatVerdict = "allow" | "review" | "block";
+/** Score thresholds separating {@link ThreatVerdict} bands. */
+interface ThreatPolicy {
+  /** Score at or above which the verdict becomes `review`. Default `4`. */
+  readonly reviewAt: number;
+  /** Score at or above which the verdict becomes `block`. Default `8`. */
+  readonly blockAt: number;
+}
+/** Default thresholds: one high/high finding reviews, one critical finding blocks. */
+declare const DEFAULT_THREAT_POLICY: ThreatPolicy;
+//#endregion
+export { ALL_THREAT_CONTEXTS, CONFIDENCE_MULTIPLIERS, DEFAULT_THREAT_POLICY, EventContext, InputSource, InputVariant, InputVariantKind, SEVERITY_ORDER, SEVERITY_WEIGHTS, ThreatConfidence, ThreatContext, ThreatFinding, ThreatPolicy, ThreatRule, ThreatSeverity, ThreatType, ThreatVerdict };
+//# sourceMappingURL=types.d.mts.map

package/lib/threats/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/threats/types.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA4CY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA8DA;;cAsBC;;;;;KA8BD;;;;;;;;;KAUA;;cAGC,kBAAkB,SAAS,OAAO;;cAQlC,wBAAwB,SAAS,OAAO;;cAOxC,gBAAgB,SAAS,OAAO;;;;;;;;;;KAoBjC;;UAGK;;WAEP,MAAM;;WAEN;;;;;;;;;;;UAgBO;;WAEP;;WAEA,MAAM;;WAEN,mBAAmB;;WAEnB,UAAU;;WAEV,YAAY;;WAEZ;;WAEA;;;;;;WAMA;;WAEA,SAAS;;;;;;WAMT,oBAAoB;;;UAIb;;WAEP;;WAEA,MAAM;;WAEN,UAAU;;WAEV,YAAY;;WAEZ;;WAEA;;WAEA;;WAEA,SAAS;;WAET;;WAEA;;WAEA;;;;;;;;;;;;;KAkBE;;;;;;;;;;;;;;;;;;;UA+BK;;WAEP;;WAEA;;WAEA;;WAEA,SAAS;;;;;;;;;;KAeP;;UAGK;;WAEP;;WAEA;;;cAIG,uBAAuB"}

package/lib/threats/types.mjs

@@ -0,0 +1,52 @@
+//#region src/threats/types.ts
+/** Every {@link ThreatContext} value, for iteration and "scan every sink" callers. */
+const ALL_THREAT_CONTEXTS = [
+	"general_text",
+	"html",
+	"sql",
+	"nosql",
+	"shell",
+	"filesystem",
+	"url",
+	"url_parameter",
+	"http_header",
+	"jwt",
+	"identifier",
+	"object_merge",
+	"template",
+	"xml",
+	"ldap",
+	"xpath",
+	"spreadsheet",
+	"log",
+	"llm_prompt"
+];
+/** Base anomaly points contributed by a finding, before the confidence multiplier. */
+const SEVERITY_WEIGHTS = {
+	low: 1,
+	medium: 2,
+	high: 4,
+	critical: 8
+};
+/** Scales {@link SEVERITY_WEIGHTS} by how trustworthy the signature is. */
+const CONFIDENCE_MULTIPLIERS = {
+	low: .5,
+	medium: 1,
+	high: 1.5
+};
+/** Ordering helper for `minSeverity` filtering. Higher is worse. */
+const SEVERITY_ORDER = {
+	low: 0,
+	medium: 1,
+	high: 2,
+	critical: 3
+};
+/** Default thresholds: one high/high finding reviews, one critical finding blocks. */
+const DEFAULT_THREAT_POLICY = {
+	reviewAt: 4,
+	blockAt: 8
+};
+//#endregion
+export { ALL_THREAT_CONTEXTS, CONFIDENCE_MULTIPLIERS, DEFAULT_THREAT_POLICY, SEVERITY_ORDER, SEVERITY_WEIGHTS };
+
+//# sourceMappingURL=types.mjs.map

package/lib/threats/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","names":[],"sources":["../../src/threats/types.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @fileoverview Vocabulary for the threat rule engine — weakness categories, sink\n * contexts, severity/confidence grades, and the {@link ThreatRule} /\n * {@link ThreatFinding} shapes that carry them. Everything here is data-only so the\n * rule catalog, the scanner, and the scoring policy can be reasoned about (and\n * unit-tested) independently.\n *\n * Design note: rules are *telemetry and defense-in-depth*, not the primary control.\n * The primary control for each category is the sink-appropriate one — parameterized\n * queries for SQL, a parser-based sanitizer for HTML, canonicalize-and-contain for\n * filesystem paths, argv-array process spawning for shells. Each rule names its own\n * in {@link ThreatRule.primaryControl}.\n *\n * @module @resq-systems/security/threats/types\n */\n\n//#region Categories\n\n/**\n * The closed set of weakness categories the engine recognizes.\n *\n * Serves as the discriminant of {@link ThreatFinding} and drives the exhaustive\n * `switch` in `getThreatErrorMessage` — adding a variant here without a matching\n * `case` there is a compile error via `assertNever`.\n *\n * Categories follow the OWASP Web Security Testing Guide's input-validation chapter\n * so findings map onto an established taxonomy rather than package-local names.\n */\nexport type ThreatType =\n\t| \"xss\"\n\t| \"sql_injection\"\n\t| \"nosql_injection\"\n\t| \"command_injection\"\n\t| \"path_traversal\"\n\t| \"prototype_pollution\"\n\t| \"homoglyph\"\n\t| \"header_injection\"\n\t| \"ldap_injection\"\n\t| \"xpath_injection\"\n\t| \"xml_injection\"\n\t| \"template_injection\"\n\t| \"file_inclusion\"\n\t| \"ssrf\"\n\t| \"formula_injection\"\n\t| \"log_injection\"\n\t| \"prompt_injection\"\n\t| \"parameter_pollution\"\n\t| \"credential_exposure\"\n\t| \"jwt_tampering\"\n\t| \"double_encoding\"\n\t| \"resource_abuse\";\n\n/**\n * The sink a value is destined for. Rules declare which contexts they apply to, and\n * the scanner only evaluates rules matching the caller's declared contexts.\n *\n * This is the single most important false-positive control in the package: a\n * biography containing `C:\\Windows`, a support ticket containing `1=1`, and a code\n * snippet containing `eval(` are all perfectly legitimate `general_text`. They are\n * only suspicious when the value actually reaches a filesystem, SQL, or HTML sink.\n *\n * - `general_text` — free-form prose. Only near-universally hostile signals apply\n *   (invisible/bidirectional control characters, null bytes).\n * - `html` — rendered as HTML or interpolated into markup.\n * - `sql` / `nosql` — reaches a database query builder or driver.\n * - `shell` — reaches a child process, especially with `shell: true`.\n * - `filesystem` — becomes part of a path passed to `fs`.\n * - `url` — fetched server-side, or used to build such a request.\n * - `url_parameter` — a *single value* about to be concatenated into a query string.\n *   Distinct from `url`, where `&name=` is the normal grammar rather than evidence of\n *   an injected parameter — the same distinction `http_header` draws against a whole\n *   request.\n * - `http_header` — written into an HTTP or email header value.\n * - `jwt` — a JSON Web Token, or an already-decoded JWT header. Scoped narrowly on\n *   purpose: re-scanning a whole opaque token with every detector is the\n *   run-everything-against-everything anti-pattern this package exists to avoid. To\n *   check a `kid` or `jku` claim, extract it and declare *its* real sink\n *   (`filesystem`, `sql`, `url`).\n * - `identifier` — a username, domain, org name, package name, or brand-adjacent\n *   label where confusable-glyph collisions matter.\n * - `object_merge` — parsed into an object graph that is then merged, cloned, or\n *   assigned property-by-property (`Object.assign`, `lodash.merge`, query-string\n *   expansion). This is prototype pollution's actual sink.\n * - `template` — concatenated into template *source* (as opposed to passed as data).\n * - `xml` — parsed by an XML/SOAP/SVG parser.\n * - `ldap` / `xpath` — becomes part of an LDAP filter/DN or an XPath expression.\n * - `spreadsheet` — exported to CSV/XLSX and opened by a spreadsheet application.\n * - `log` — written to a line-based or structured log sink.\n * - `llm_prompt` — concatenated into an LLM prompt or reachable by a tool-using agent.\n */\nexport type ThreatContext =\n\t| \"general_text\"\n\t| \"html\"\n\t| \"sql\"\n\t| \"nosql\"\n\t| \"shell\"\n\t| \"filesystem\"\n\t| \"url\"\n\t| \"url_parameter\"\n\t| \"http_header\"\n\t| \"jwt\"\n\t| \"identifier\"\n\t| \"object_merge\"\n\t| \"template\"\n\t| \"xml\"\n\t| \"ldap\"\n\t| \"xpath\"\n\t| \"spreadsheet\"\n\t| \"log\"\n\t| \"llm_prompt\";\n\n/** Every {@link ThreatContext} value, for iteration and \"scan every sink\" callers. */\nexport const ALL_THREAT_CONTEXTS = [\n\t\"general_text\",\n\t\"html\",\n\t\"sql\",\n\t\"nosql\",\n\t\"shell\",\n\t\"filesystem\",\n\t\"url\",\n\t\"url_parameter\",\n\t\"http_header\",\n\t\"jwt\",\n\t\"identifier\",\n\t\"object_merge\",\n\t\"template\",\n\t\"xml\",\n\t\"ldap\",\n\t\"xpath\",\n\t\"spreadsheet\",\n\t\"log\",\n\t\"llm_prompt\",\n] as const satisfies readonly ThreatContext[];\n\n//#endregion\n\n//#region Grading\n\n/**\n * How bad the weakness is if the match is a true positive. Independent of how\n * likely the match is to *be* a true positive — that is {@link ThreatConfidence}.\n */\nexport type ThreatSeverity = \"low\" | \"medium\" | \"high\" | \"critical\";\n\n/**\n * How likely a match is to be a real attack rather than benign content that\n * happens to look like one.\n *\n * - `low` — fires on ordinary content regularly (e.g. the substring `1=1`).\n * - `medium` — unusual in ordinary content but not impossible.\n * - `high` — has essentially no benign explanation in the declared context.\n */\nexport type ThreatConfidence = \"low\" | \"medium\" | \"high\";\n\n/** Base anomaly points contributed by a finding, before the confidence multiplier. */\nexport const SEVERITY_WEIGHTS: Readonly<Record<ThreatSeverity, number>> = {\n\tlow: 1,\n\tmedium: 2,\n\thigh: 4,\n\tcritical: 8,\n};\n\n/** Scales {@link SEVERITY_WEIGHTS} by how trustworthy the signature is. */\nexport const CONFIDENCE_MULTIPLIERS: Readonly<Record<ThreatConfidence, number>> = {\n\tlow: 0.5,\n\tmedium: 1,\n\thigh: 1.5,\n};\n\n/** Ordering helper for `minSeverity` filtering. Higher is worse. */\nexport const SEVERITY_ORDER: Readonly<Record<ThreatSeverity, number>> = {\n\tlow: 0,\n\tmedium: 1,\n\thigh: 2,\n\tcritical: 3,\n};\n\n//#endregion\n\n//#region Variants\n\n/**\n * Which representation of the input a rule matched against.\n *\n * Attack signatures are routinely bypassed by encoding, so the scanner evaluates a\n * small, bounded set of representations rather than the raw bytes alone. Findings\n * record which one matched, so operators can tell \"the request literally contained\n * `../`\" apart from \"the request contained `%2e%2e%2f`, which only becomes `../` if\n * a downstream component decodes it\".\n */\nexport type InputVariantKind = \"raw\" | \"nfc\" | \"nfkc\" | \"percent_decoded\" | \"html_decoded\";\n\n/** One representation of the scanned input. */\nexport interface InputVariant {\n\t/** Which transformation produced {@link InputVariant.value}. */\n\treadonly kind: InputVariantKind;\n\t/** The transformed string. */\n\treadonly value: string;\n}\n\n//#endregion\n\n//#region Rules and findings\n\n/**\n * A single signature in the catalog.\n *\n * @remarks\n * `pattern` **must not** carry the global (`g`) or sticky (`y`) flag. Those flags\n * make `RegExp` objects stateful via `lastIndex`, and the catalog is module-scoped\n * and shared across every call — a stateful rule would silently skip matches on\n * alternating invocations. `assertRuleCatalogIsValid` enforces this at load time.\n */\nexport interface ThreatRule {\n\t/** Stable identifier (e.g. `PATH-TRAVERSAL-ENCODED-001`). Never reused once retired. */\n\treadonly id: string;\n\t/** Weakness category this rule evidences. */\n\treadonly type: ThreatType;\n\t/** Sinks for which this rule is meaningful. Never empty. */\n\treadonly contexts: readonly ThreatContext[];\n\t/** Impact if the match is real. */\n\treadonly severity: ThreatSeverity;\n\t/** Likelihood the match is real rather than benign lookalike content. */\n\treadonly confidence: ThreatConfidence;\n\t/** One-line description for operators and log lines. Not user-facing. */\n\treadonly description: string;\n\t/** MITRE CWE identifier for the weakness, when one applies cleanly. */\n\treadonly cwe?: number;\n\t/**\n\t * The control that actually prevents this weakness. Signatures detect; they do\n\t * not prevent. Surfaced on findings so a reviewer reading an alert is pointed at\n\t * the fix rather than at a tighter regex.\n\t */\n\treadonly primaryControl: string;\n\t/** The signature. Must be non-global and non-sticky — see the remark above. */\n\treadonly pattern: RegExp;\n\t/**\n\t * Restrict this rule to specific input representations. Defaults to every\n\t * variant. Used by rules whose whole purpose is detecting an encoding (e.g. the\n\t * percent-encoded traversal rule, which is only meaningful against `raw`).\n\t */\n\treadonly variants?: readonly InputVariantKind[];\n}\n\n/** A rule that matched, plus where and in which representation. */\nexport interface ThreatFinding {\n\t/** {@link ThreatRule.id} of the rule that fired. */\n\treadonly ruleId: string;\n\t/** Copied from the rule — the weakness category. */\n\treadonly type: ThreatType;\n\t/** Copied from the rule. */\n\treadonly severity: ThreatSeverity;\n\t/** Copied from the rule. */\n\treadonly confidence: ThreatConfidence;\n\t/** Copied from the rule. Operator-facing; never render to end users. */\n\treadonly description: string;\n\t/** Copied from the rule, when present. */\n\treadonly cwe?: number;\n\t/** Copied from the rule — the control that actually fixes this. */\n\treadonly primaryControl: string;\n\t/** Which representation matched. */\n\treadonly variant: InputVariantKind;\n\t/** Matched substring, truncated to 50 characters so logs cannot be flooded. */\n\treadonly matchedPattern?: string;\n\t/** Match start offset *within the matched variant*, not within the raw input. */\n\treadonly start?: number;\n\t/** Match end offset (exclusive) within the matched variant. */\n\treadonly end?: number;\n}\n\n//#endregion\n\n//#region Event correlation\n\n/**\n * Where an untrusted value entered the application.\n *\n * The counterpart to {@link ThreatContext}, which names the *sink*. A context says where\n * a value is going and decides which rules run; a source says where it came from and\n * decides nothing — it is carried through so a finding can be attributed later.\n *\n * Both halves together are what makes a finding actionable: \"SQL keywords in a value\n * bound to a SQL query\" is a bug report, while \"SQL keywords arriving in a query\n * parameter from one account, forty times in a minute\" is an incident.\n */\nexport type InputSource =\n\t| \"http.query\"\n\t| \"http.body\"\n\t| \"http.header\"\n\t| \"http.path\"\n\t| \"http.cookie\"\n\t| \"websocket.message\"\n\t| \"cli.argument\"\n\t| \"file.upload\"\n\t| \"database\"\n\t| \"external.api\"\n\t| \"internal\";\n\n/**\n * Who and what a scan belongs to, carried through so findings can be correlated.\n *\n * Modelled on OWASP AppSensor, whose argument is that application-layer intrusion\n * detection is about *sequences* attributed to an actor, not about individual strings. A\n * single `review` verdict is ordinarily noise; thirty of them from one account inside a\n * minute is an attack in progress, and nothing in a per-string API can express the\n * difference.\n *\n * Every field is optional and none affects detection. The scanner does not resolve,\n * validate or store any of them — it echoes them onto the result so a logging or SIEM\n * pipeline can join findings to a request and an actor without threading a correlation id\n * through its own call stack.\n *\n * Treat `actorId` as personal data: it reaches whatever sink the findings reach, so pass\n * an opaque identifier rather than an email address, or redact downstream with\n * `sanitizeForLogging`.\n */\nexport interface EventContext {\n\t/** Correlates every finding raised while handling one request. */\n\treadonly requestId?: string;\n\t/** The authenticated principal, if any. Opaque — never an email address. */\n\treadonly actorId?: string;\n\t/** The session the request belongs to, for sequence detection across requests. */\n\treadonly sessionId?: string;\n\t/** Where the value entered the application. */\n\treadonly source?: InputSource;\n}\n\n//#endregion\n\n//#region Verdicts\n\n/**\n * Policy outcome derived from the anomaly score.\n *\n * Scoring rather than first-match rejection is deliberate: any individual signature\n * produces false positives, so a single low-confidence hit should raise a signal,\n * not reject a form submission. This mirrors how OWASP CRS uses anomaly scoring with\n * tunable thresholds instead of one-rule-one-block.\n */\nexport type ThreatVerdict = \"allow\" | \"review\" | \"block\";\n\n/** Score thresholds separating {@link ThreatVerdict} bands. */\nexport interface ThreatPolicy {\n\t/** Score at or above which the verdict becomes `review`. Default `4`. */\n\treadonly reviewAt: number;\n\t/** Score at or above which the verdict becomes `block`. Default `8`. */\n\treadonly blockAt: number;\n}\n\n/** Default thresholds: one high/high finding reviews, one critical finding blocks. */\nexport const DEFAULT_THREAT_POLICY: ThreatPolicy = {\n\treviewAt: 4,\n\tblockAt: 8,\n};\n\n//#endregion\n"],"mappings":";;AAgIA,MAAa,sBAAsB;CAClC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACD;;AAuBA,MAAa,mBAA6D;CACzE,KAAK;CACL,QAAQ;CACR,MAAM;CACN,UAAU;AACX;;AAGA,MAAa,yBAAqE;CACjF,KAAK;CACL,QAAQ;CACR,MAAM;AACP;;AAGA,MAAa,iBAA2D;CACvE,KAAK;CACL,QAAQ;CACR,MAAM;CACN,UAAU;AACX;;AA+KA,MAAa,wBAAsC;CAClD,UAAU;CACV,SAAS;AACV"}

package/lib/threats/variants.d.mts

@@ -0,0 +1,57 @@
+import { InputVariant } from "./types.mjs";
+//#region src/threats/variants.d.ts
+/**
+ * Decode HTML character references in a single pass.
+ *
+ * Handles `<`, `<`, and the named subset in {@link NAMED_ENTITIES}, with or
+ * without the trailing semicolon — browsers accept several named references
+ * unterminated and attackers rely on it. Unrecognized references are left verbatim;
+ * this is best-effort detection support, not a rendering path.
+ *
+ * @param input - Raw string.
+ * @returns The string with recognized references replaced.
+ *
+ * @example
+ * ```ts
+ * decodeHtmlEntities("&#60;script&#62;"); // "<script>"
+ * decodeHtmlEntities("&unknownref;");     // "&unknownref;"
+ * ```
+ */
+declare function decodeHtmlEntities(input: string): string;
+/**
+ * Percent-decode a string, tolerating malformed sequences.
+ *
+ * `decodeURIComponent` throws `URIError` on an invalid escape (`%zz`, a lone `%`, a
+ * truncated surrogate pair). That failure is itself telemetry — well-formed clients
+ * do not emit it — so the caller gets `null` and the `raw` variant stays scannable
+ * instead of the whole scan aborting.
+ *
+ * @param input - Possibly percent-encoded string.
+ * @returns The decoded string, or `null` when the input contains no `%` or is not
+ *   validly encoded.
+ */
+declare function tryPercentDecode(input: string): string | null;
+/**
+ * Build the representations to scan.
+ *
+ * Always includes `raw`. Adds `nfc`, `percent_decoded`, and `html_decoded` only when
+ * that transformation actually changes the string, so a plain ASCII value costs one
+ * pass rather than four.
+ *
+ * The original input is never mutated or replaced — callers keep the raw value for
+ * storage and display, and the variants exist solely so a rule can observe what the
+ * value would become at a decoding sink.
+ *
+ * @param input - Raw untrusted string.
+ * @returns One to four distinct representations, `raw` first.
+ *
+ * @example
+ * ```ts
+ * buildInputVariants("%2e%2e%2f");
+ * // [{ kind: "raw", value: "%2e%2e%2f" }, { kind: "percent_decoded", value: "../" }]
+ * ```
+ */
+declare function buildInputVariants(input: string): readonly InputVariant[];
+//#endregion
+export { buildInputVariants, decodeHtmlEntities, tryPercentDecode };
+//# sourceMappingURL=variants.d.mts.map

package/lib/threats/variants.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variants.d.mts","names":[],"sources":["../../src/threats/variants.ts"],"mappings":";;;;;;;;;;;;;;;;;;;iBAqGgB,mBAAmB;;;;;;;;;;;;;iBA4CnB,iBAAiB;;;;;;;;;;;;;;;;;;;;;iBAiCjB,mBAAmB,yBAAyB"}

package/lib/threats/variants.mjs

@@ -0,0 +1,144 @@
+//#region src/threats/variants.ts
+/**
+* Named HTML entities worth decoding for detection purposes.
+*
+* Not a complete HTML5 entity table — there are roughly 2 200 of those — and not
+* trying to be. It covers the characters that carry syntactic meaning in the sinks
+* this package guards. Every other reference decodes to a character no rule looks
+* for, so leaving it encoded cannot hide an attack.
+*/
+const NAMED_ENTITIES = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	apos: "'",
+	nbsp: " ",
+	sol: "/",
+	bsol: "\\",
+	colon: ":",
+	semi: ";",
+	lpar: "(",
+	rpar: ")",
+	lbrack: "[",
+	rbrack: "]",
+	lcub: "{",
+	rcub: "}",
+	excl: "!",
+	equals: "=",
+	dollar: "$",
+	commat: "@",
+	num: "#",
+	percnt: "%",
+	period: ".",
+	comma: ",",
+	ast: "*",
+	verbar: "|",
+	grave: "`",
+	Tab: "	",
+	NewLine: "\n"
+};
+/** Matches a numeric (decimal or hex) or named reference, with an optional semicolon. */
+const ENTITY_PATTERN = /&(?:#[xX]([0-9a-fA-F]{1,6})|#(\d{1,7})|([a-zA-Z][a-zA-Z0-9]{1,31}));?/g;
+/**
+* Highest code point `String.fromCodePoint` accepts. Numeric references above this
+* are left as written rather than throwing.
+*/
+const MAX_CODE_POINT = 1114111;
+/**
+* Decode HTML character references in a single pass.
+*
+* Handles `&#60;`, `&#x3c;`, and the named subset in {@link NAMED_ENTITIES}, with or
+* without the trailing semicolon — browsers accept several named references
+* unterminated and attackers rely on it. Unrecognized references are left verbatim;
+* this is best-effort detection support, not a rendering path.
+*
+* @param input - Raw string.
+* @returns The string with recognized references replaced.
+*
+* @example
+* ```ts
+* decodeHtmlEntities("&#60;script&#62;"); // "<script>"
+* decodeHtmlEntities("&unknownref;");     // "&unknownref;"
+* ```
+*/
+function decodeHtmlEntities(input) {
+	if (!input.includes("&")) return input;
+	return input.replace(ENTITY_PATTERN, (match, hex, dec, name) => {
+		if (hex !== void 0) {
+			const code = Number.parseInt(hex, 16);
+			return code <= MAX_CODE_POINT ? String.fromCodePoint(code) : match;
+		}
+		if (dec !== void 0) {
+			const code = Number.parseInt(dec, 10);
+			return code <= MAX_CODE_POINT ? String.fromCodePoint(code) : match;
+		}
+		if (name !== void 0) return Object.hasOwn(NAMED_ENTITIES, name) ? NAMED_ENTITIES[name] : match;
+		return match;
+	});
+}
+/**
+* Percent-decode a string, tolerating malformed sequences.
+*
+* `decodeURIComponent` throws `URIError` on an invalid escape (`%zz`, a lone `%`, a
+* truncated surrogate pair). That failure is itself telemetry — well-formed clients
+* do not emit it — so the caller gets `null` and the `raw` variant stays scannable
+* instead of the whole scan aborting.
+*
+* @param input - Possibly percent-encoded string.
+* @returns The decoded string, or `null` when the input contains no `%` or is not
+*   validly encoded.
+*/
+function tryPercentDecode(input) {
+	if (!input.includes("%")) return null;
+	try {
+		return decodeURIComponent(input);
+	} catch {
+		return null;
+	}
+}
+/**
+* Build the representations to scan.
+*
+* Always includes `raw`. Adds `nfc`, `percent_decoded`, and `html_decoded` only when
+* that transformation actually changes the string, so a plain ASCII value costs one
+* pass rather than four.
+*
+* The original input is never mutated or replaced — callers keep the raw value for
+* storage and display, and the variants exist solely so a rule can observe what the
+* value would become at a decoding sink.
+*
+* @param input - Raw untrusted string.
+* @returns One to four distinct representations, `raw` first.
+*
+* @example
+* ```ts
+* buildInputVariants("%2e%2e%2f");
+* // [{ kind: "raw", value: "%2e%2e%2f" }, { kind: "percent_decoded", value: "../" }]
+* ```
+*/
+function buildInputVariants(input) {
+	const variants = [{
+		kind: "raw",
+		value: input
+	}];
+	const seen = /* @__PURE__ */ new Set([input]);
+	const add = (kind, value) => {
+		if (seen.has(value)) return;
+		seen.add(value);
+		variants.push({
+			kind,
+			value
+		});
+	};
+	add("nfc", input.normalize("NFC"));
+	add("nfkc", input.normalize("NFKC"));
+	const percentDecoded = tryPercentDecode(input);
+	if (percentDecoded !== null) add("percent_decoded", percentDecoded);
+	add("html_decoded", decodeHtmlEntities(input));
+	return variants;
+}
+//#endregion
+export { buildInputVariants, decodeHtmlEntities, tryPercentDecode };
+
+//# sourceMappingURL=variants.mjs.map

package/lib/threats/variants.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"variants.mjs","names":[],"sources":["../../src/threats/variants.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @fileoverview Canonicalization variants — the small, bounded set of representations\n * the scanner evaluates so signatures are not trivially bypassed by encoding.\n *\n * The set is deliberately small and non-recursive. Decoding everything repeatedly\n * until it stops changing is its own bug class: it makes the scanner disagree with\n * the downstream component about what the value actually is, and it lets an attacker\n * pick whichever of several disagreeing interpretations suits them. Instead, each\n * variant is one transformation applied once, findings record which variant matched,\n * and payloads that only surface after multiple decodes get explicit rules such as\n * `PATH-TRAVERSAL-DOUBLE-ENCODED-001`.\n *\n * @module @resq-systems/security/threats/variants\n */\n\nimport type { InputVariant, InputVariantKind } from \"./types.js\";\n\n//#region HTML entity decoding\n\n/**\n * Named HTML entities worth decoding for detection purposes.\n *\n * Not a complete HTML5 entity table — there are roughly 2 200 of those — and not\n * trying to be. It covers the characters that carry syntactic meaning in the sinks\n * this package guards. Every other reference decodes to a character no rule looks\n * for, so leaving it encoded cannot hide an attack.\n */\nconst NAMED_ENTITIES: Readonly<Record<string, string>> = {\n\tamp: \"&\",\n\tlt: \"<\",\n\tgt: \">\",\n\tquot: '\"',\n\tapos: \"'\",\n\tnbsp: \" \",\n\tsol: \"/\",\n\tbsol: \"\\\\\",\n\tcolon: \":\",\n\tsemi: \";\",\n\tlpar: \"(\",\n\trpar: \")\",\n\tlbrack: \"[\",\n\trbrack: \"]\",\n\tlcub: \"{\",\n\trcub: \"}\",\n\texcl: \"!\",\n\tequals: \"=\",\n\tdollar: \"$\",\n\tcommat: \"@\",\n\tnum: \"#\",\n\tpercnt: \"%\",\n\tperiod: \".\",\n\tcomma: \",\",\n\tast: \"*\",\n\tverbar: \"|\",\n\tgrave: \"`\",\n\tTab: \"\\t\",\n\tNewLine: \"\\n\",\n};\n\n/** Matches a numeric (decimal or hex) or named reference, with an optional semicolon. */\nconst ENTITY_PATTERN = /&(?:#[xX]([0-9a-fA-F]{1,6})|#(\\d{1,7})|([a-zA-Z][a-zA-Z0-9]{1,31}));?/g;\n\n/**\n * Highest code point `String.fromCodePoint` accepts. Numeric references above this\n * are left as written rather than throwing.\n */\nconst MAX_CODE_POINT = 0x10ffff;\n\n/**\n * Decode HTML character references in a single pass.\n *\n * Handles `&#60;`, `&#x3c;`, and the named subset in {@link NAMED_ENTITIES}, with or\n * without the trailing semicolon — browsers accept several named references\n * unterminated and attackers rely on it. Unrecognized references are left verbatim;\n * this is best-effort detection support, not a rendering path.\n *\n * @param input - Raw string.\n * @returns The string with recognized references replaced.\n *\n * @example\n * ```ts\n * decodeHtmlEntities(\"&#60;script&#62;\"); // \"<script>\"\n * decodeHtmlEntities(\"&unknownref;\");     // \"&unknownref;\"\n * ```\n */\nexport function decodeHtmlEntities(input: string): string {\n\tif (!input.includes(\"&\")) return input;\n\n\t// `String.prototype.replace` resets a global pattern's lastIndex on entry, so the\n\t// module-scoped ENTITY_PATTERN carries no state between calls.\n\treturn input.replace(ENTITY_PATTERN, (match, hex?: string, dec?: string, name?: string) => {\n\t\tif (hex !== undefined) {\n\t\t\tconst code = Number.parseInt(hex, 16);\n\t\t\treturn code <= MAX_CODE_POINT ? String.fromCodePoint(code) : match;\n\t\t}\n\t\tif (dec !== undefined) {\n\t\t\tconst code = Number.parseInt(dec, 10);\n\t\t\treturn code <= MAX_CODE_POINT ? String.fromCodePoint(code) : match;\n\t\t}\n\t\tif (name !== undefined) {\n\t\t\t// Own-property check, not `?? match`: the name group matches `constructor`,\n\t\t\t// `toString`, `valueOf` and friends, which resolve up the prototype chain to a\n\t\t\t// function. `??` never fires for those, and `replace` then coerces the function\n\t\t\t// to its source text — `&constructor;` decoded to\n\t\t\t// `function Object() { [native code] }`, injecting braces and parens that trip\n\t\t\t// unrelated rules and corrupting the `html_decoded` variant for any input\n\t\t\t// carrying such a reference.\n\t\t\treturn Object.hasOwn(NAMED_ENTITIES, name) ? NAMED_ENTITIES[name] : match;\n\t\t}\n\t\treturn match;\n\t});\n}\n\n//#endregion\n\n//#region Percent decoding\n\n/**\n * Percent-decode a string, tolerating malformed sequences.\n *\n * `decodeURIComponent` throws `URIError` on an invalid escape (`%zz`, a lone `%`, a\n * truncated surrogate pair). That failure is itself telemetry — well-formed clients\n * do not emit it — so the caller gets `null` and the `raw` variant stays scannable\n * instead of the whole scan aborting.\n *\n * @param input - Possibly percent-encoded string.\n * @returns The decoded string, or `null` when the input contains no `%` or is not\n *   validly encoded.\n */\nexport function tryPercentDecode(input: string): string | null {\n\tif (!input.includes(\"%\")) return null;\n\ttry {\n\t\treturn decodeURIComponent(input);\n\t} catch {\n\t\treturn null;\n\t}\n}\n\n//#endregion\n\n//#region Variant construction\n\n/**\n * Build the representations to scan.\n *\n * Always includes `raw`. Adds `nfc`, `percent_decoded`, and `html_decoded` only when\n * that transformation actually changes the string, so a plain ASCII value costs one\n * pass rather than four.\n *\n * The original input is never mutated or replaced — callers keep the raw value for\n * storage and display, and the variants exist solely so a rule can observe what the\n * value would become at a decoding sink.\n *\n * @param input - Raw untrusted string.\n * @returns One to four distinct representations, `raw` first.\n *\n * @example\n * ```ts\n * buildInputVariants(\"%2e%2e%2f\");\n * // [{ kind: \"raw\", value: \"%2e%2e%2f\" }, { kind: \"percent_decoded\", value: \"../\" }]\n * ```\n */\nexport function buildInputVariants(input: string): readonly InputVariant[] {\n\tconst variants: InputVariant[] = [{ kind: \"raw\", value: input }];\n\tconst seen = new Set<string>([input]);\n\n\tconst add = (kind: InputVariantKind, value: string): void => {\n\t\tif (seen.has(value)) return;\n\t\tseen.add(value);\n\t\tvariants.push({ kind, value });\n\t};\n\n\t// `normalize` throws only on an invalid form argument, never on content.\n\tadd(\"nfc\", input.normalize(\"NFC\"));\n\n\t// NFC is a documented no-op on compatibility characters, so fullwidth forms slipped\n\t// past every signature: `．．／．．／etc／passwd` and `＜script＞` both scanned clean.\n\t// NFKC folds U+FF01–FF5E onto ASCII, which is exactly the mapping a downstream\n\t// component performs when it normalizes before parsing. Kept as its own variant\n\t// rather than replacing `nfc`, because NFKC is lossy and must never be what the\n\t// caller stores.\n\tadd(\"nfkc\", input.normalize(\"NFKC\"));\n\n\tconst percentDecoded = tryPercentDecode(input);\n\tif (percentDecoded !== null) {\n\t\tadd(\"percent_decoded\", percentDecoded);\n\t}\n\n\tadd(\"html_decoded\", decodeHtmlEntities(input));\n\n\treturn variants;\n}\n\n//#endregion\n"],"mappings":";;;;;;;;;AA2CA,MAAM,iBAAmD;CACxD,KAAK;CACL,IAAI;CACJ,IAAI;CACJ,MAAM;CACN,MAAM;CACN,MAAM;CACN,KAAK;CACL,MAAM;CACN,OAAO;CACP,MAAM;CACN,MAAM;CACN,MAAM;CACN,QAAQ;CACR,QAAQ;CACR,MAAM;CACN,MAAM;CACN,MAAM;CACN,QAAQ;CACR,QAAQ;CACR,QAAQ;CACR,KAAK;CACL,QAAQ;CACR,QAAQ;CACR,OAAO;CACP,KAAK;CACL,QAAQ;CACR,OAAO;CACP,KAAK;CACL,SAAS;AACV;;AAGA,MAAM,iBAAiB;;;;;AAMvB,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;AAmBvB,SAAgB,mBAAmB,OAAuB;CACzD,IAAI,CAAC,MAAM,SAAS,GAAG,GAAG,OAAO;CAIjC,OAAO,MAAM,QAAQ,iBAAiB,OAAO,KAAc,KAAc,SAAkB;EAC1F,IAAI,QAAQ,KAAA,GAAW;GACtB,MAAM,OAAO,OAAO,SAAS,KAAK,EAAE;GACpC,OAAO,QAAQ,iBAAiB,OAAO,cAAc,IAAI,IAAI;EAC9D;EACA,IAAI,QAAQ,KAAA,GAAW;GACtB,MAAM,OAAO,OAAO,SAAS,KAAK,EAAE;GACpC,OAAO,QAAQ,iBAAiB,OAAO,cAAc,IAAI,IAAI;EAC9D;EACA,IAAI,SAAS,KAAA,GAQZ,OAAO,OAAO,OAAO,gBAAgB,IAAI,IAAI,eAAe,QAAQ;EAErE,OAAO;CACR,CAAC;AACF;;;;;;;;;;;;;AAkBA,SAAgB,iBAAiB,OAA8B;CAC9D,IAAI,CAAC,MAAM,SAAS,GAAG,GAAG,OAAO;CACjC,IAAI;EACH,OAAO,mBAAmB,KAAK;CAChC,QAAQ;EACP,OAAO;CACR;AACD;;;;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,mBAAmB,OAAwC;CAC1E,MAAM,WAA2B,CAAC;EAAE,MAAM;EAAO,OAAO;CAAM,CAAC;CAC/D,MAAM,uBAAO,IAAI,IAAY,CAAC,KAAK,CAAC;CAEpC,MAAM,OAAO,MAAwB,UAAwB;EAC5D,IAAI,KAAK,IAAI,KAAK,GAAG;EACrB,KAAK,IAAI,KAAK;EACd,SAAS,KAAK;GAAE;GAAM;EAAM,CAAC;CAC9B;CAGA,IAAI,OAAO,MAAM,UAAU,KAAK,CAAC;CAQjC,IAAI,QAAQ,MAAM,UAAU,MAAM,CAAC;CAEnC,MAAM,iBAAiB,iBAAiB,KAAK;CAC7C,IAAI,mBAAmB,MACtB,IAAI,mBAAmB,cAAc;CAGtC,IAAI,gBAAgB,mBAAmB,KAAK,CAAC;CAE7C,OAAO;AACR"}

package/lib/unicode/confusables.d.mts

@@ -0,0 +1,82 @@
+//#region src/unicode/confusables.d.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.
+ */
+/**
+ * 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.
+ */
+declare const CONFUSABLE_MAP: ReadonlyMap<number, string>;
+/**
+ * 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
+ * ```
+ */
+declare function getSkeleton(input: string): string;
+/**
+ * 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
+ * ```
+ */
+declare function foldConfusables(input: string): string;
+/**
+ * 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.
+ */
+declare function areConfusable(left: string, right: string): boolean;
+//#endregion
+export { CONFUSABLE_MAP, areConfusable, foldConfusables, getSkeleton };
+//# sourceMappingURL=confusables.d.mts.map

package/lib/unicode/confusables.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confusables.d.mts","names":[],"sources":["../../src/unicode/confusables.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;cA6Ka,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;iBAsKb,YAAY;;;;;;;;;;;;;;;;;;;;;;;;iBAyCZ,gBAAgB;;;;;;;;iBAsBhB,cAAc,cAAc"}