@resq-systems/security 1.0.0

package/lib/validators.d.mts

@@ -0,0 +1,269 @@
+//#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.
+ */
+interface ThreatDetectionResult {
+  /** `true` when no detectors fired. Equivalent to `threats.length === 0`. */
+  isSafe: boolean;
+  /** All findings produced by enabled detectors, in detector order. */
+  threats: ThreatFinding[];
+}
+/**
+ * A single detector hit. Detectors that fire return at most one
+ * finding per call (one example is enough to reject the input).
+ */
+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;
+}
+/**
+ * The closed set of threat categories the validators recognize. Add
+ * new categories here when adding a new detector.
+ */
+type ThreatType = "xss" | "sql_injection" | "nosql_injection" | "command_injection" | "path_traversal" | "homoglyph";
+/**
+ * Detect XSS-style payloads (script tags, event handlers, dangerous
+ * URI schemes, prototype pollution, …) in a UTF-8 input.
+ *
+ * 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.
+ * @returns Empty array when nothing matches, or a single
+ *   {@link ThreatFinding} of type `"xss"`.
+ *
+ * @example
+ * ```ts
+ * containsXSSPatterns(`<img src=x onerror="alert(1)">`);
+ * // → [{ type: "xss", description: "...", matchedPattern: "onerror=" }]
+ * ```
+ */
+declare function containsXSSPatterns(input: string): ThreatFinding[];
+/**
+ * Detect SQL-injection patterns (UNION SELECT, DROP TABLE,
+ * comment-based bypasses, always-true tautologies, stacked queries)
+ * in input.
+ *
+ * **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.
+ *
+ * @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.
+ *
+ * @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`).
+ *
+ * **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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * Use {@link normalizeUnicode} to *replace* homoglyphs with their
+ * ASCII equivalents — this function only flags their presence.
+ *
+ * @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}.
+ *
+ * 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`.
+ */
+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;
+}
+/**
+ * Run every enabled detector 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).
+ *
+ * Non-string inputs (`null`, `undefined`, numbers, …) are treated as
+ * safe — wrap caller-side validation around this if you want to
+ * reject non-strings.
+ *
+ * @param input - The candidate string.
+ * @param config - Detector toggles. Defaults turn on everything
+ *   except command-injection.
+ * @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.
+ *
+ * @param input - String to test.
+ * @param config - Optional detector toggles.
+ * @returns `true` when no detector fires.
+ */
+declare function isSafeInput(input: string, config?: ThreatDetectionConfig): boolean;
+/**
+ * HTML-entity escape `&`, `<`, `>`, `"`, `'`, and `/` for safe
+ * insertion into HTML text and attribute contexts.
+ *
+ * **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).
+ *
+ * Returns `""` for non-string or empty input.
+ *
+ * @param input - Untrusted string.
+ * @returns Entity-escaped output safe to interpolate into HTML.
+ */
+declare function sanitizeForDisplay(input: string): string;
+/**
+ * Canonicalise a string for safe equality checks against ASCII.
+ *
+ * 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`, …).
+ *
+ * Use before storing user-controlled identifiers (usernames, domain
+ * names) and before comparing them to a denylist or to each other.
+ *
+ * Returns `""` for non-string or empty input.
+ *
+ * @param input - Raw string from an untrusted source.
+ * @returns ASCII-normalized, NFC-composed string.
+ */
+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.
+ */
+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.
+ *
+ * Equivalent to `isSafeInput(input)` with default config.
+ */
+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.
+ *
+ * Suitable for first/last/full-name inputs in registration forms.
+ *
+ * @returns `true` when the name passes both the threat detectors and
+ *   the name-shape regex.
+ */
+declare function validateSafeName(input: string): boolean;
+/**
+ * Refinement for email fields. Combines:
+ *
+ * 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.
+ *
+ * @returns `true` when both checks pass.
+ */
+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.
+ */
+declare function getThreatErrorMessage(result: ThreatDetectionResult): string;
+//#endregion
+export { THREAT_DETECTED_MESSAGE, ThreatDetectionConfig, ThreatDetectionResult, ThreatFinding, ThreatType, containsCommandInjection, containsHomoglyphs, containsNoSQLInjection, containsPathTraversal, containsSQLInjection, containsXSSPatterns, detectThreatPatterns, getThreatErrorMessage, isSafeInput, normalizeUnicode, sanitizeForDisplay, validateSafeEmail, validateSafeName, validateSafeText };
+//# sourceMappingURL=validators.d.mts.map

package/lib/validators.d.mts.map

@@ -0,0 +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"}