@resq-systems/security 1.0.5 → 2.0.0

package/lib/validators.d.mts

@@ -1,180 +1,165 @@
+import { ThreatFinding, ThreatType } from "./threats/types.mjs";
 //#region src/validators.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.
- */
 /**
  * Outcome of {@link detectThreatPatterns}.
  *
- * `isSafe` is the boolean shortcut; `threats` is the full list of
- * findings (one per detector that fired). Use
- * {@link getThreatErrorMessage} to render a user-facing message for
- * the first finding.
+ * `isSafe` is the boolean shortcut; `threats` carries the findings. Prefer
+ * {@link scanForThreats}, whose result adds a numeric score and an allow/review/block
+ * verdict instead of collapsing everything into one boolean.
  */
 interface ThreatDetectionResult {
-  /** `true` when no detectors fired. Equivalent to `threats.length === 0`. */
+  /** `true` when no detector fired. Equivalent to `threats.length === 0`. */
   isSafe: boolean;
-  /** All findings produced by enabled detectors, in detector order. */
+  /** Findings from the enabled detectors, at most one per weakness category. */
   threats: ThreatFinding[];
 }
 /**
- * A single detector hit. Detectors that fire return at most one
- * finding per call (one example is enough to reject the input).
+ * Minimal shape {@link getThreatErrorMessage} needs.
+ *
+ * Deliberately narrower than {@link ThreatFinding} so callers can pass a hand-built
+ * summary — or a finding from an older version of this package — without having to
+ * populate the full record.
  */
-interface ThreatFinding {
-  /** Which detector matched. */
-  type: ThreatType;
-  /** Human-readable description suitable for log lines (not for end users — use {@link getThreatErrorMessage} instead). */
-  description: string;
-  /** First 50 chars of the matching substring, for diagnostics. Truncated to prevent leaking large payloads in logs. */
-  matchedPattern?: string;
+interface ThreatSummary {
+  /** Weakness category. The only field the message depends on. */
+  readonly type: ThreatType;
+  /** Operator-facing description, if available. */
+  readonly description?: string;
+  /** Matched excerpt, if available. */
+  readonly matchedPattern?: string;
 }
 /**
- * The closed set of threat categories the validators recognize. Add
- * new categories here when adding a new detector.
+ * Per-detector toggles for {@link detectThreatPatterns}.
+ *
+ * @deprecated Prefer {@link scanForThreats} with an explicit `contexts` list. These
+ *   booleans conflate "which weakness am I looking for" with "where is this value
+ *   going", and the second question is the one that decides whether a signature is
+ *   evidence or noise. Each flag maps onto a context: `checkXSS` → `html`,
+ *   `checkSQLInjection` → `sql`, `checkNoSQLInjection` → `nosql`,
+ *   `checkCommandInjection` → `shell`, `checkPathTraversal` → `filesystem`;
+ *   `checkHomoglyphs` runs UTS #39 identifier analysis.
  */
-type ThreatType = "xss" | "sql_injection" | "nosql_injection" | "command_injection" | "path_traversal" | "homoglyph";
+interface ThreatDetectionConfig {
+  /** Default `true`. Maps to the `html` context. */
+  checkXSS?: boolean;
+  /** Default `true`. Maps to the `sql` context. */
+  checkSQLInjection?: boolean;
+  /** Default `true`. Maps to the `nosql` context. */
+  checkNoSQLInjection?: boolean;
+  /** Default `false` — opt in only when input reaches a shell. Maps to `shell`. */
+  checkCommandInjection?: boolean;
+  /** Default `true`. Maps to the `filesystem` context. */
+  checkPathTraversal?: boolean;
+  /** Default `true`. Runs UTS #39 identifier analysis rather than a pattern list. */
+  checkHomoglyphs?: boolean;
+}
 /**
- * Detect XSS-style payloads (script tags, event handlers, dangerous
- * URI schemes, prototype pollution, …) in a UTF-8 input.
+ * Detect XSS payloads — script tags, inline event handlers, dangerous URI schemes,
+ * markup sinks — in a value bound for an HTML context.
  *
- * Inputs longer than 100 000 characters are truncated before scanning
- * to bound regex evaluation cost and prevent ReDoS on crafted
- * payloads. Returns at most one finding — the regex catalog is
- * exhaustive enough that the first hit is sufficient for a
- * reject-or-sanitize decision.
+ * @param input - String to scan. Truncated at 100 000 characters.
+ * @returns Empty array, or a single finding of type `"xss"`.
  *
- * @param input - String to scan.
- * @returns Empty array when nothing matches, or a single
- *   {@link ThreatFinding} of type `"xss"`.
+ * @remarks
+ * Prototype-pollution patterns (`__proto__`, `constructor[`) no longer surface here.
+ * They are a distinct weakness class with distinct controls and now report as
+ * `prototype_pollution` — see {@link containsPrototypePollution}.
  *
  * @example
  * ```ts
  * containsXSSPatterns(`<img src=x onerror="alert(1)">`);
- * // → [{ type: "xss", description: "...", matchedPattern: "onerror=" }]
+ * // → [{ ruleId: "XSS-EVENT-HANDLER-001", type: "xss", severity: "high", … }]
  * ```
  */
 declare function containsXSSPatterns(input: string): ThreatFinding[];
 /**
- * Detect SQL-injection patterns (UNION SELECT, DROP TABLE,
- * comment-based bypasses, always-true tautologies, stacked queries)
- * in input.
+ * Detect prototype-pollution payloads — `__proto__`, `constructor.prototype`, and the
+ * nested-object forms that arrive through a JSON body or query-string expansion.
  *
- * **Not a replacement for parameterised queries.** Use this as a
- * defense-in-depth signal in addition to a properly bound prepared
- * statement, never as the only barrier.
+ * **Not the control.** Reject unknown keys with schema validation, build lookup
+ * objects with `Object.create(null)`, and use a merge that skips `__proto__`,
+ * `constructor`, and `prototype`.
+ *
+ * @param input - String to scan.
+ * @returns Empty array, or a single finding of type `"prototype_pollution"`.
+ */
+declare function containsPrototypePollution(input: string): ThreatFinding[];
+/**
+ * Detect SQL-injection patterns in a value bound for a query.
+ *
+ * **Not a replacement for parameterized queries.** A bound parameter is safe whatever
+ * keywords it contains; an interpolated one is unsafe however many signatures it
+ * dodges. Use this for telemetry alongside binding, never instead of it.
  *
  * @param input - String to scan. Truncated at 100 000 characters.
  * @returns Empty array, or one finding of type `"sql_injection"`.
  */
 declare function containsSQLInjection(input: string): ThreatFinding[];
 /**
- * Detect NoSQL-injection patterns — Mongo-style operator injection
- * (`$where`, `$ne`, `$regex`), JavaScript-in-query payloads, and
- * structural manipulators that can bypass auth filters in document
- * stores.
+ * Detect NoSQL operator injection — `$where`, `$ne`, `$regex`, and the object and
+ * array forms that bypass authentication filters in document stores.
  *
  * @param input - String to scan.
  * @returns Empty array, or one finding of type `"nosql_injection"`.
  */
 declare function containsNoSQLInjection(input: string): ThreatFinding[];
 /**
- * Detect shell command-injection patterns: command substitution
- * (`$(...)`, backticks), chained dangerous commands (`; rm`, `; curl`,
- * …) and shell-piped exec (`| sh`, `| bash`).
+ * Detect shell command-injection patterns — command substitution, chained commands,
+ * pipes into an interpreter.
  *
- * **Off by default in {@link detectThreatPatterns}** — these patterns
- * occasionally fire on legitimate user content. Enable explicitly
- * (`checkCommandInjection: true`) only when input flows into a child
- * process or shell.
+ * **Off by default in {@link detectThreatPatterns}**, because these patterns fire on
+ * ordinary prose. Enable only when the value reaches a child process, and prefer
+ * spawning with an argv array and `shell: false`, which makes the category moot.
  *
  * @param input - String to scan. Truncated at 100 000 characters.
  * @returns Empty array, or one finding of type `"command_injection"`.
  */
 declare function containsCommandInjection(input: string): ThreatFinding[];
 /**
- * Detect path-traversal payloads — `../`, encoded dots, raw absolute
- * paths trying to escape a base directory. Pair with `path.resolve()`
- * + a `startsWith()` containment check on the canonicalised path
- * before reading or writing the file.
+ * Detect path-traversal payloads — `../`, its percent-encoded and double-encoded
+ * forms, NUL truncation, and references to sensitive system paths.
+ *
+ * **Not the control.** Use `resolveContainedPath` from
+ * `@resq-systems/security/paths`, which resolves the candidate against a base
+ * directory and verifies containment — a check that also catches absolute paths and
+ * separator tricks no signature enumerates.
  *
  * @param input - String to scan.
  * @returns Empty array, or one finding of type `"path_traversal"`.
  */
 declare function containsPathTraversal(input: string): ThreatFinding[];
 /**
- * Detect lookalike Unicode characters (Cyrillic / Greek glyphs that
- * render identically to common ASCII letters). The classic phishing
- * trick is `paypaӏ.com` (`ӏ` instead of `l`); this detector catches
- * the building blocks.
+ * Detect visually confusable characters in a **protected identifier**.
  *
- * Use {@link normalizeUnicode} to *replace* homoglyphs with their
- * ASCII equivalents — this function only flags their presence.
+ * Backed by UTS #39 script analysis rather than a hand-written lookalike table, so it
+ * reports the actual signal — a Latin/Cyrillic mix in `pаypal` — instead of flagging
+ * every non-ASCII character. Single-script values are not confusable with anything, so
+ * `Ольга Иванова` and `東京タワー` pass where the previous implementation rejected both.
  *
- * @param input - String to scan.
- * @returns Empty array, or one finding of type `"homoglyph"` (the
- *   first matched lookalike).
- */
-declare function containsHomoglyphs(input: string): ThreatFinding[];
-/**
- * Per-detector toggles for {@link detectThreatPatterns}.
+ * Scope this to usernames, domains, org names, and package names. Do **not** run it on
+ * prose or on people's names — see {@link validatePersonName}.
  *
- * Defaults: XSS, SQL, NoSQL, path-traversal, and homoglyph detectors
- * are **on**; command injection is **off** (false-positive prone).
- * Pass `false` to disable a detector or `true` to force-enable
- * `checkCommandInjection`.
+ * @param input - Identifier to scan.
+ * @returns Empty array, or a single finding of type `"homoglyph"`.
  */
-interface ThreatDetectionConfig {
-  /** Default `true`. */
-  checkXSS?: boolean;
-  /** Default `true`. */
-  checkSQLInjection?: boolean;
-  /** Default `true`. */
-  checkNoSQLInjection?: boolean;
-  /** Default `false` — opt in only when input reaches a shell. */
-  checkCommandInjection?: boolean;
-  /** Default `true`. */
-  checkPathTraversal?: boolean;
-  /** Default `true`. */
-  checkHomoglyphs?: boolean;
-}
+declare function containsHomoglyphs(input: string): ThreatFinding[];
 /**
- * Run every enabled detector against `input` and aggregate findings.
+ * Run the enabled detectors against `input` and aggregate findings.
  *
- * Returns early-but-not-immediately: each individual detector still
- * runs to completion, but each detector returns at most one finding,
- * so the aggregate threats array is small (≤ 6 entries).
+ * @deprecated Prefer {@link scanForThreats}, which takes explicit contexts and returns
+ *   a score and verdict rather than one boolean. This wrapper maps the legacy toggles
+ *   onto contexts and keeps the one-finding-per-category shape.
  *
- * Non-string inputs (`null`, `undefined`, numbers, …) are treated as
- * safe — wrap caller-side validation around this if you want to
- * reject non-strings.
+ * Non-string input (`null`, `undefined`, a number) is reported safe — wrap your own
+ * type validation around this if you need to reject those.
  *
  * @param input - The candidate string.
- * @param config - Detector toggles. Defaults turn on everything
- *   except command-injection.
+ * @param config - Detector toggles. Everything except command injection defaults on.
  * @returns `{ isSafe, threats }`.
- *
- * @example
- * ```ts
- * const result = detectThreatPatterns(req.body.query);
- * if (!result.isSafe) return new Response(getThreatErrorMessage(result), { status: 400 });
- * ```
  */
 declare function detectThreatPatterns(input: string, config?: ThreatDetectionConfig): ThreatDetectionResult;
 /**
- * Boolean shortcut over {@link detectThreatPatterns} — discards the
- * findings list when you only need a yes/no decision.
+ * Boolean shortcut over {@link detectThreatPatterns}.
  *
  * @param input - String to test.
  * @param config - Optional detector toggles.
@@ -182,88 +167,280 @@ declare function detectThreatPatterns(input: string, config?: ThreatDetectionCon
  */
 declare function isSafeInput(input: string, config?: ThreatDetectionConfig): boolean;
 /**
- * HTML-entity escape `&`, `<`, `>`, `"`, `'`, and `/` for safe
- * insertion into HTML text and attribute contexts.
+ * HTML-entity-escape a value being inserted as **element text**.
+ *
+ * Escapes `&`, `<`, `>`, `"`, `'`, and `/`, which covers text nodes and fully quoted
+ * attribute values.
+ *
+ * **Output encoding is context-dependent.** HTML text, quoted attributes, unquoted
+ * attributes, URLs, JavaScript string literals, and CSS each have different rules, and
+ * no single function is correct for all of them. This one is correct for text; use
+ * {@link escapeHtmlAttribute} for attribute values, `sanitizeUrl` for URLs, and
+ * `sanitizeHtml` (DOMPurify) when the value is meant to *be* markup.
+ *
+ * There is deliberately no CSS-context escaper here, and no general JavaScript-string
+ * escaper — hand-rolled versions of those are reliably wrong, and the fix is to stop
+ * interpolating untrusted values into style and script *source*. Embedding untrusted
+ * *data* in a script element is the one tractable case, because `JSON.stringify` fixes
+ * the string boundaries first; {@link encodeJsonForScript} covers that and nothing else.
+ *
+ * @param input - Untrusted string. Non-string or empty input yields `""`.
+ * @returns Entity-escaped output safe to interpolate into HTML text.
+ *
+ * @example
+ * ```ts
+ * escapeHtmlText('<script>alert("xss")</script>');
+ * // "&lt;script&gt;alert(&quot;xss&quot;)&lt;&#x2F;script&gt;"
+ * ```
+ */
+declare function escapeHtmlText(input: string): string;
+/**
+ * HTML-entity-escape a value being inserted as an **attribute value**.
  *
- * **Limited scope.** This is appropriate for plain text destined for
- * `textContent` or attribute values, not for unfiltered HTML
- * rendering. For rich-text use a vetted sanitizer (DOMPurify on the
- * client, sanitize-html or similar on the server).
+ * Everything {@link escapeHtmlText} escapes, plus backtick, equals, and whitespace —
+ * the characters that let a payload break out of an *unquoted* attribute. That case is
+ * precisely what generic "escape for display" helpers get wrong.
  *
- * Returns `""` for non-string or empty input.
+ * The ceiling on the unquoted case is injection of a valueless boolean attribute —
+ * `autofocus`, `disabled`, `formnovalidate` — not script execution: an injected
+ * `onmouseover=…` arrives with its `=` already escaped, so it lands as an attribute
+ * whose *name* is the escaped text, with no handler bound.
+ *
+ * Quote your attributes anyway. This makes an unquoted attribute survivable; it does
+ * not make it correct.
+ *
+ * @param input - Untrusted string. Non-string or empty input yields `""`.
+ * @returns Output safe to interpolate into a quoted or unquoted attribute value.
+ */
+declare function escapeHtmlAttribute(input: string): string;
+/**
+ * HTML-entity-escape a value for display.
+ *
+ * @deprecated Renamed to {@link escapeHtmlText}, which says what it actually does. The
+ *   old name suggested a general-purpose "make this safe to display" operation, and
+ *   callers reasonably read it as attribute-safe — which entity escaping alone is not,
+ *   for *unquoted* attributes. Behaviour is unchanged; only the name is.
  *
  * @param input - Untrusted string.
- * @returns Entity-escaped output safe to interpolate into HTML.
+ * @returns Entity-escaped output.
  */
 declare function sanitizeForDisplay(input: string): string;
 /**
- * Canonicalise a string for safe equality checks against ASCII.
+ * Escape a value for inclusion in a log record.
+ *
+ * This is the control named by the log-injection rules. A log line is a *sink*: a value
+ * carrying a newline forges an entry (CWE-117), one carrying a terminal escape rewrites
+ * what an operator sees, and one carrying a bidirectional override reorders the line
+ * without altering a byte of it.
+ *
+ * Escaping rather than stripping is deliberate. The record is evidence, so the encoded
+ * form is reversible and nothing is silently discarded — contrast `stripAnsi`, which
+ * deletes. Structured logging is still the better answer, because it removes the
+ * ambiguity this function can only make visible; use both.
  *
- * Two-pass:
- * 1. Normalize to NFC (composed form) so combining-character
- *    sequences don't compare differently from their pre-composed
- *    counterparts.
- * 2. Replace known homoglyphs (Cyrillic `А`, Greek `Ε`, …) with their
- *    ASCII equivalents (`A`, `E`, …).
+ * @param value - Untrusted field value. Non-string or empty input yields `""`.
+ * @param options - Optional bounds.
+ * @param options.maxLength - Characters read from `value`. Defaults to 2048. Truncation
+ *   is announced in the output rather than applied silently, and the returned string may
+ *   exceed this length, because escaping expands.
+ * @returns A single-line, control-free rendering of `value`.
+ *
+ * @example
+ * ```ts
+ * encodeLogValue("alice\nINFO  user promoted to admin");
+ * // "alice\\nINFO  user promoted to admin"  — one line, no forged entry
+ * ```
+ */
+declare function encodeLogValue(value: string, options?: {
+  readonly maxLength?: number;
+}): string;
+/**
+ * Escape one cell for CSV export.
+ *
+ * This is the control named by the formula-injection rules. A CSV file is not inert: a
+ * cell beginning `=`, `+`, `-`, `@`, tab or CR is evaluated as a formula by Excel,
+ * Sheets and LibreOffice when the recipient opens it, so the payload executes on *their*
+ * machine, outside the exporting application entirely (CWE-1236).
+ *
+ * Two separate jobs, in order: neutralise the formula trigger with a leading apostrophe,
+ * then apply RFC 4180 quoting so the field cannot break the row.
+ *
+ * **Only strings are prefixed.** A `number` or `boolean` came from the application's own
+ * types and cannot carry a formula, so `-1234` exports as a negative number while
+ * `"-1234"` exports as text. Pass numeric columns as numbers, or every negative value in
+ * the sheet becomes a string.
+ *
+ * Three things worth knowing before relying on it:
+ * - The leading apostrophe is an Excel convention, **not** an RFC 4180 construct. Readers
+ *   that do not implement it surface it as a literal character in the data.
+ * - NUL is removed rather than escaped, so it does not round-trip.
+ * - Scanning the output with `scanForThreats` still reports a finding, by design:
+ *   `CSV-FORMULA-LEAD-001` sees through the apostrophe and `CSV-DDE-001` is
+ *   position-independent. The rules describe the *value*; this function protects the
+ *   *file*. A clean scan is the wrong acceptance test.
+ *
+ * @param value - Cell value. `null` and `undefined` become `""`.
+ * @param options - Optional dialect settings.
+ * @param options.delimiter - Field separator the row will be joined with. Defaults to `","`.
+ * @returns The escaped field, ready to join into a row.
  *
- * Use before storing user-controlled identifiers (usernames, domain
- * names) and before comparing them to a denylist or to each other.
+ * @example
+ * ```ts
+ * escapeCsvField("=WEBSERVICE(\"https://evil.example\")");
+ * // quoted, and inert on open
+ * escapeCsvField(-1234); // "-1234" — a number, not a formula
+ * ```
+ */
+declare function escapeCsvField(value: unknown, options?: {
+  readonly delimiter?: string;
+}): string;
+/**
+ * Escape and join one row for CSV export.
  *
- * Returns `""` for non-string or empty input.
+ * @param values - Cell values, in column order.
+ * @param options - Optional dialect settings.
+ * @param options.delimiter - Field separator. Defaults to `","`.
+ * @returns The joined row, without a line terminator.
  *
- * @param input - Raw string from an untrusted source.
- * @returns ASCII-normalized, NFC-composed string.
+ * @example
+ * ```ts
+ * toCsvRow(["Ada Lovelace", "=1+1", 42]);
+ * ```
+ */
+declare function toCsvRow(values: readonly unknown[], options?: {
+  readonly delimiter?: string;
+}): string;
+/**
+ * Serialise a value for embedding inside a `<script>` element.
+ *
+ * `JSON.stringify` alone is not safe here. Its output may contain `</script>`, which
+ * closes the element from *inside a string literal* — the HTML tokenizer never looks at
+ * JavaScript syntax — so the remainder of the payload becomes markup.
+ *
+ * **Script element content only.** The output contains unescaped `"`, so it must never be
+ * placed in an attribute; use {@link escapeHtmlAttribute} there. It is also not a general
+ * JavaScript-string escaper — it is safe precisely because `JSON.stringify` has already
+ * decided where the string boundaries are.
+ *
+ * Using `<script type="application/json">` with `JSON.parse(el.textContent)` does **not**
+ * remove the need for this: a raw `</script>` in the data closes that element too.
+ *
+ * @param value - Any JSON-serialisable value.
+ * @returns JSON text safe to place between `<script>` tags.
+ * @throws {TypeError} If `value` cannot be represented as JSON — `undefined`, a function
+ *   or a symbol at the top level (for which `JSON.stringify` returns `undefined` rather
+ *   than a string), a circular structure, or a `BigInt`. Failing loudly is deliberate: a
+ *   sentinel string would emit a syntax error into the page instead.
+ *
+ * @example
+ * ```ts
+ * const json = encodeJsonForScript({ name: userName });
+ * const html = "<script>window.__DATA__ = " + json + ";</script>";
+ * ```
+ */
+declare function encodeJsonForScript(value: unknown): string;
+/**
+ * Fold non-ASCII lookalike characters onto ASCII and compose to NFC.
+ *
+ * @deprecated Prefer `getSkeleton` and `analyzeIdentifier` from
+ *   `@resq-systems/security/unicode`. Rewriting a user's identifier into a different
+ *   string loses information and only *looks* safe — the durable pattern is to store
+ *   what they typed, index its skeleton, and compare skeletons for collisions.
+ *
+ * Now backed by the UTS #39 confusable tables rather than the previous 14-entry map,
+ * so coverage is far wider. Combining marks are preserved (`e` + U+0301 still composes
+ * to `é`) and ASCII characters are never rewritten.
+ *
+ * @param input - Raw string from an untrusted source. Non-string input yields `""`.
+ * @returns NFC-composed string with non-ASCII confusables folded to ASCII.
  */
 declare function normalizeUnicode(input: string): string;
 /**
- * Generic user-facing fallback message. Render this verbatim when a
- * detector fires but you don't want to expose which one. Prefer
- * {@link getThreatErrorMessage} for category-specific messages.
+ * Generic user-facing fallback message. Render verbatim when a detector fires and you
+ * do not want to reveal which one.
  */
 declare const THREAT_DETECTED_MESSAGE = "Input contains potentially unsafe content";
 /**
- * Boolean refinement helper for use with `zod.string().refine(...)`,
- * `effect/Schema.filter(...)`, or any predicate-based validator.
+ * Refinement helper for `zod.string().refine(...)`, `effect/Schema.filter(...)`, or
+ * any predicate-based validator. Equivalent to {@link isSafeInput} with defaults.
  *
- * Equivalent to `isSafeInput(input)` with default config.
+ * @param input - String to test.
+ * @returns `true` when no detector fires.
  */
 declare function validateSafeText(input: string): boolean;
 /**
- * Refinement for human name fields. More permissive than
- * {@link validateSafeText} — allows international letters,
- * combining marks, hyphens, apostrophes, and spaces — but still
- * rejects HTML/SQL/NoSQL injection patterns and homoglyph forgeries.
+ * Validate a human name field.
+ *
+ * The policy is an allowlist of what a name is made of — letters in any script,
+ * combining marks, apostrophes, hyphens, periods, spaces — plus a length bound and a
+ * bidirectional-control check. Nothing that passes it can carry an injection payload,
+ * because `<`, `(`, `;`, `$`, `=`, and every digit are already excluded.
  *
- * Suitable for first/last/full-name inputs in registration forms.
+ * It deliberately does **not** run SQL, path-traversal, or confusable detectors. A
+ * name is not a query, a path, or a protected identifier, and subjecting one to those
+ * checks rejects real people: the previous implementation ran the homoglyph detector
+ * here, which failed any name containing а, е, о, р, с, or х — that is, most Russian,
+ * Ukrainian, Bulgarian, Serbian, and Greek names.
  *
- * @returns `true` when the name passes both the threat detectors and
- *   the name-shape regex.
+ * Encode the value at whatever sink it eventually reaches. That is what makes it safe;
+ * this function only establishes that it is a name.
+ *
+ * @param input - Candidate name.
+ * @returns `true` when the value is a plausible name.
+ *
+ * @example
+ * ```ts
+ * validatePersonName("O'Brien");            // true
+ * validatePersonName("José García");        // true
+ * validatePersonName("Ольга Иванова");      // true
+ * validatePersonName("John123");            // false
+ * validatePersonName("<script>x</script>"); // false
+ * ```
+ */
+declare function validatePersonName(input: string): boolean;
+/**
+ * Validate a human name field.
+ *
+ * @deprecated Renamed to {@link validatePersonName}. The old name implied a general
+ *   "safe name" check and was implemented as one, running injection and homoglyph
+ *   detectors against people's names. Behaviour now matches
+ *   {@link validatePersonName}.
+ *
+ * @param input - Candidate name.
+ * @returns `true` when the value is a plausible name.
  */
 declare function validateSafeName(input: string): boolean;
 /**
- * Refinement for email fields. Combines:
+ * Validate an email address.
  *
- * 1. RFC-style format check (length-bounded to ≤ 254 chars to
- *    prevent ReDoS).
- * 2. XSS / SQL / NoSQL / homoglyph detectors — emails are extremely
- *    constrained and should never legitimately contain HTML or query
- *    operators.
+ * Two checks: an RFC-shaped format match (length-bounded first, so the pattern never
+ * sees an unbounded string), and UTS #39 identifier analysis of the **domain**, where
+ * a mixed-script host is the IDN homograph attack — `аpple.com` with a Cyrillic `а`
+ * resolves somewhere else entirely.
  *
- * @returns `true` when both checks pass.
+ * The local part is not confusable-checked: it is not a routable identifier, and
+ * flagging it would reject legitimate internationalized mailboxes.
+ *
+ * @param input - Candidate address.
+ * @returns `true` when the format is valid and the domain is not a script mix.
  */
 declare function validateSafeEmail(input: string): boolean;
 /**
- * Map a {@link ThreatDetectionResult} into a user-facing error
- * message string suitable for an HTTP 400 response or form
- * validation error. Returns `""` when the result is safe (so
- * `error || undefined` works).
- *
- * Uses only the **first** finding for the message — exposing every
- * threat type to the user can leak information about the detection
- * rules. For full diagnostics, log `result.threats` server-side
- * rather than returning them.
+ * Render a user-facing error message for a detection result.
+ *
+ * Uses only the **first** finding: enumerating every category that fired leaks the
+ * shape of the rule set to whoever is probing it. Log `result.threats` server-side for
+ * diagnostics and return this to the client.
+ *
+ * @param result - A {@link ThreatDetectionResult}, a `ThreatScanResult`-shaped object,
+ *   or any `{ isSafe, threats }` pair.
+ * @returns A message, or `""` when the result is safe — so `message || undefined`
+ *   works at a call site.
  */
-declare function getThreatErrorMessage(result: ThreatDetectionResult): string;
+declare function getThreatErrorMessage(result: {
+  readonly isSafe: boolean;
+  readonly threats: readonly ThreatSummary[];
+}): string;
 //#endregion
-export { THREAT_DETECTED_MESSAGE, ThreatDetectionConfig, ThreatDetectionResult, ThreatFinding, ThreatType, containsCommandInjection, containsHomoglyphs, containsNoSQLInjection, containsPathTraversal, containsSQLInjection, containsXSSPatterns, detectThreatPatterns, getThreatErrorMessage, isSafeInput, normalizeUnicode, sanitizeForDisplay, validateSafeEmail, validateSafeName, validateSafeText };
+export { THREAT_DETECTED_MESSAGE, ThreatDetectionConfig, ThreatDetectionResult, type ThreatFinding, ThreatSummary, type ThreatType, containsCommandInjection, containsHomoglyphs, containsNoSQLInjection, containsPathTraversal, containsPrototypePollution, containsSQLInjection, containsXSSPatterns, detectThreatPatterns, encodeJsonForScript, encodeLogValue, escapeCsvField, escapeHtmlAttribute, escapeHtmlText, getThreatErrorMessage, isSafeInput, normalizeUnicode, sanitizeForDisplay, toCsvRow, validatePersonName, validateSafeEmail, validateSafeName, validateSafeText };
 //# sourceMappingURL=validators.d.mts.map

package/lib/validators.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"validators.d.mts","names":[],"sources":["../src/validators.ts"],"mappings":";;AAyKA;;;;;;;;;AAWA;;;;;;;;;;AAaA;;;UAxBiB,qBAAA;EAwBK;EAtBrB,MAAA;EAkDkC;EAhDlC,OAAA,EAAS,aAAA;AAAA;;AAgFV;;;UAzEiB,aAAA;EAyEiD;EAvEjE,IAAA,EAAM,UAAA;EAmG+B;EAjGrC,WAAA;EAiGsC;EA/FtC,cAAA;AAAA;;;;;KAOW,UAAA;;;;;AA2LZ;;;;;AA+BA;;;;;;;;;;;iBA9LgB,mBAAA,CAAoB,KAAA,WAAgB,aAAA;AA4OpD;;;;;;;;;;AAgDA;;AAhDA,iBA5MgB,oBAAA,CAAqB,KAAA,WAAgB,aAAA;;;;;;;AA8QrD;;;iBAlPgB,sBAAA,CAAuB,KAAA,WAAgB,aAAA;;AAgRvD;;;;;AAyBA;;;;;AAQA;;iBAlRgB,wBAAA,CAAyB,KAAA,WAAgB,aAAA;;;AAiSzD;;;;;AA0BA;;iBAtRgB,qBAAA,CAAsB,KAAA,WAAgB,aAAA;;;AAwTtD;;;;;;;;;;;iBAzRgB,kBAAA,CAAmB,KAAA,WAAgB,aAAA;;;;;;;;;UA+BlC,qBAAA;;EAEhB,QAAA;;EAEA,iBAAA;;EAEA,mBAAA;;EAEA,qBAAA;;EAEA,kBAAA;;EAEA,eAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;iBAkCe,oBAAA,CACf,KAAA,UACA,MAAA,GAAQ,qBAAA,GACN,qBAAA;;;;;;;;;iBA6Ca,WAAA,CAAY,KAAA,UAAe,MAAA,GAAS,qBAAA;;;;;;;;;;;;;;;iBAkBpC,kBAAA,CAAmB,KAAA;;;;;;;;;;;;;;;;;;;iBA8BnB,gBAAA,CAAiB,KAAA;;;;;;cAyBpB,uBAAA;;;;;;;iBAQG,gBAAA,CAAiB,KAAA;;;;;;;;;;;;iBAejB,gBAAA,CAAiB,KAAA;;;;;;;;;;;;iBA0BjB,iBAAA,CAAkB,KAAA;;;;;;;;;;;;iBAkClB,qBAAA,CAAsB,MAAA,EAAQ,qBAAA"}
+{"version":3,"file":"validators.d.mts","names":[],"sources":["../src/validators.ts"],"mappings":";;;;;;;;;UAgDiB;;EAEhB;;EAEA,SAAS;;;;;;;;;UAUO;;WAEP,MAAM;;WAEN;;WAEA;;;;;;;;;;;;;UAkBO;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;;;;;;;;iBAkDe,oBAAoB,gBAAgB;;;;;;;;;;;;iBAepC,2BAA2B,gBAAgB;;;;;;;;;;;iBAc3C,qBAAqB,gBAAgB;;;;;;;;iBAWrC,uBAAuB,gBAAgB;;;;;;;;;;;;iBAevC,yBAAyB,gBAAgB;;;;;;;;;;;;;iBAgBzC,sBAAsB,gBAAgB;;;;;;;;;;;;;;;iBA2CtC,mBAAmB,gBAAgB;;;;;;;;;;;;;;;iBA0CnC,qBACf,eACA,SAAQ,wBACN;;;;;;;;iBA8Ba,YAAY,eAAe,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmCpC,eAAe;;;;;;;;;;;;;;;;;;;iBA4Cf,oBAAoB;;;;;;;;;;;;iBAwBpB,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwDnB,eACf,eACA;WAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqEL,eACf,gBACA;WAAoB;;;;;;;;;;;;;;;iBA+BL,SACf,4BACA;WAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyDL,oBAAoB;;;;;;;;;;;;;;;;iBAuCpB,iBAAiB;;;;;cAYpB;;;;;;;;iBASG,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoDjB,mBAAmB;;;;;;;;;;;;iBAyBnB,iBAAiB;;;;;;;;;;;;;;;iBAyBjB,kBAAkB;;;;;;;;;;;;;iBA2BlB,sBAAsB;WAC5B;WACA,kBAAkB"}