@resq-systems/security 2.1.0 → 2.1.2

package/lib/validators.d.mts

@@ -7,7 +7,7 @@ import { ThreatFinding, ThreatType } from "./threats/types.mjs";
  * {@link scanForThreats}, whose result adds a numeric score and an allow/review/block
  * verdict instead of collapsing everything into one boolean.
  */
-interface ThreatDetectionResult {
+export interface ThreatDetectionResult {
   /** `true` when no detector fired. Equivalent to `threats.length === 0`. */
   isSafe: boolean;
   /** Findings from the enabled detectors, at most one per weakness category. */
@@ -20,7 +20,7 @@ interface ThreatDetectionResult {
  * summary — or a finding from an older version of this package — without having to
  * populate the full record.
  */
-interface ThreatSummary {
+export interface ThreatSummary {
   /** Weakness category. The only field the message depends on. */
   readonly type: ThreatType;
   /** Operator-facing description, if available. */
@@ -39,7 +39,7 @@ interface ThreatSummary {
  *   `checkCommandInjection` → `shell`, `checkPathTraversal` → `filesystem`;
  *   `checkHomoglyphs` runs UTS #39 identifier analysis.
  */
-interface ThreatDetectionConfig {
+export interface ThreatDetectionConfig {
   /** Default `true`. Maps to the `html` context. */
   checkXSS?: boolean;
   /** Default `true`. Maps to the `sql` context. */
@@ -71,7 +71,7 @@ interface ThreatDetectionConfig {
  * // → [{ ruleId: "XSS-EVENT-HANDLER-001", type: "xss", severity: "high", … }]
  * ```
  */
-declare function containsXSSPatterns(input: string): ThreatFinding[];
+export declare function containsXSSPatterns(input: string): ThreatFinding[];
 /**
  * Detect prototype-pollution payloads — `__proto__`, `constructor.prototype`, and the
  * nested-object forms that arrive through a JSON body or query-string expansion.
@@ -83,7 +83,7 @@ declare function containsXSSPatterns(input: string): ThreatFinding[];
  * @param input - String to scan.
  * @returns Empty array, or a single finding of type `"prototype_pollution"`.
  */
-declare function containsPrototypePollution(input: string): ThreatFinding[];
+export declare function containsPrototypePollution(input: string): ThreatFinding[];
 /**
  * Detect SQL-injection patterns in a value bound for a query.
  *
@@ -94,7 +94,7 @@ declare function containsPrototypePollution(input: string): ThreatFinding[];
  * @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[];
+export declare function containsSQLInjection(input: string): ThreatFinding[];
 /**
  * Detect NoSQL operator injection — `$where`, `$ne`, `$regex`, and the object and
  * array forms that bypass authentication filters in document stores.
@@ -102,7 +102,7 @@ declare function containsSQLInjection(input: string): ThreatFinding[];
  * @param input - String to scan.
  * @returns Empty array, or one finding of type `"nosql_injection"`.
  */
-declare function containsNoSQLInjection(input: string): ThreatFinding[];
+export declare function containsNoSQLInjection(input: string): ThreatFinding[];
 /**
  * Detect shell command-injection patterns — command substitution, chained commands,
  * pipes into an interpreter.
@@ -114,7 +114,7 @@ declare function containsNoSQLInjection(input: string): ThreatFinding[];
  * @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[];
+export declare function containsCommandInjection(input: string): ThreatFinding[];
 /**
  * Detect path-traversal payloads — `../`, its percent-encoded and double-encoded
  * forms, NUL truncation, and references to sensitive system paths.
@@ -127,7 +127,7 @@ declare function containsCommandInjection(input: string): ThreatFinding[];
  * @param input - String to scan.
  * @returns Empty array, or one finding of type `"path_traversal"`.
  */
-declare function containsPathTraversal(input: string): ThreatFinding[];
+export declare function containsPathTraversal(input: string): ThreatFinding[];
 /**
  * Detect visually confusable characters in a **protected identifier**.
  *
@@ -142,7 +142,7 @@ declare function containsPathTraversal(input: string): ThreatFinding[];
  * @param input - Identifier to scan.
  * @returns Empty array, or a single finding of type `"homoglyph"`.
  */
-declare function containsHomoglyphs(input: string): ThreatFinding[];
+export declare function containsHomoglyphs(input: string): ThreatFinding[];
 /**
  * Run the enabled detectors against `input` and aggregate findings.
  *
@@ -157,7 +157,7 @@ declare function containsHomoglyphs(input: string): ThreatFinding[];
  * @param config - Detector toggles. Everything except command injection defaults on.
  * @returns `{ isSafe, threats }`.
  */
-declare function detectThreatPatterns(input: string, config?: ThreatDetectionConfig): ThreatDetectionResult;
+export declare function detectThreatPatterns(input: string, config?: ThreatDetectionConfig): ThreatDetectionResult;
 /**
  * Boolean shortcut over {@link detectThreatPatterns}.
  *
@@ -165,7 +165,7 @@ declare function detectThreatPatterns(input: string, config?: ThreatDetectionCon
  * @param config - Optional detector toggles.
  * @returns `true` when no detector fires.
  */
-declare function isSafeInput(input: string, config?: ThreatDetectionConfig): boolean;
+export declare function isSafeInput(input: string, config?: ThreatDetectionConfig): boolean;
 /**
  * HTML-entity-escape a value being inserted as **element text**.
  *
@@ -193,7 +193,7 @@ declare function isSafeInput(input: string, config?: ThreatDetectionConfig): boo
  * // "<script>alert("xss")</script>"
  * ```
  */
-declare function escapeHtmlText(input: string): string;
+export declare function escapeHtmlText(input: string): string;
 /**
  * HTML-entity-escape a value being inserted as an **attribute value**.
  *
@@ -212,7 +212,7 @@ declare function escapeHtmlText(input: string): string;
  * @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;
+export declare function escapeHtmlAttribute(input: string): string;
 /**
  * HTML-entity-escape a value for display.
  *
@@ -224,7 +224,7 @@ declare function escapeHtmlAttribute(input: string): string;
  * @param input - Untrusted string.
  * @returns Entity-escaped output.
  */
-declare function sanitizeForDisplay(input: string): string;
+export declare function sanitizeForDisplay(input: string): string;
 /**
  * Escape a value for inclusion in a log record.
  *
@@ -251,7 +251,7 @@ declare function sanitizeForDisplay(input: string): string;
  * // "alice\\nINFO  user promoted to admin"  — one line, no forged entry
  * ```
  */
-declare function encodeLogValue(value: string, options?: {
+export declare function encodeLogValue(value: string, options?: {
   readonly maxLength?: number;
 }): string;
 /**
@@ -260,19 +260,67 @@ declare function encodeLogValue(value: string, options?: {
  * 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
+ * machine, outside the exporting application entirely (CWE-1236). LF and the full-width
+ * `=` `+` `-` `@` are treated as triggers too, following the OWASP CSV Injection list,
+ * and so is any character whose NFKC form is a trigger or part of the leading run.
+ *
+ * Two separate jobs, in order: neutralise formula triggers with apostrophes, then apply
+ * RFC 4180 quoting so the field cannot break the row for a reader that splits on the same
+ * delimiter.
+ *
+ * A trigger is neutralised wherever a reader may start a field in text: at the start of
+ * the value, and right after each boundary inside it. The boundaries are comma,
+ * semicolon, TAB, CR and LF; the other line separators of Python's `str.splitlines()`
+ * (VT, FF, U+001C to U+001E, U+0085, U+2028 and U+2029); U+037E, which NFC folds onto
+ * `;`; and each character of the delimiter. The apostrophe goes in front of the leading
+ * run there, as it does at the start. A reader that splits on any boundary, or that
+ * ignores quotes, therefore finds every field that starts inside the value neutralised,
+ * in every column, even after an earlier cell has thrown it out of step. A field that
+ * starts at a boundary at the very end of the value runs on into the file's closing quote,
+ * delimiter or line break and then the next cell, which is neutralised in its own right.
+ * The work is linear in the value's length.
+ *
+ * At the start of the value, TAB, CR and LF are triggers, as OWASP lists them. After a
+ * boundary they are leading-run characters only: a run of them in front of `=` `+` `-`
+ * `@` or a full-width or small form is seen through and neutralised, but on their own
+ * they lead no formula there. So `"x,\t=1"` becomes `"x,'\t'=1"`, while plain multi-line
+ * or tab-separated text such as `"line1\r\nline2"` keeps its value.
+ *
+ * **Numbers, booleans and bigints are never prefixed.** They 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.
+ * the sheet becomes a string. Every other value is treated as text, including an array or
+ * object, whose string form repeats contents the caller may not control.
+ *
+ * Worth knowing before relying on it:
+ * - **Values can change after a boundary, by design.** A reader that uses the delimiter
+ *   the file was written with shows an apostrophe inserted after a boundary as part of the
+ *   value: `"a\n=b"` reads back as `"a\n'=b"`. Only a formula lead gets one, so text such
+ *   as `"line1\r\nline2"`, `"a\n\nb"` or `"x,\ty"` reads back unchanged. Without it, a
+ *   reader that splits on that boundary would start a cell there whose leading characters
+ *   were never checked.
+ * - The 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.
+ * - **A reader that splits on any other character is not protected.** That includes `|`,
+ *   a space, and a character that only NFKC folds onto a boundary, such as the full-width
+ *   comma U+FF0C. A value holding one of them followed by a trigger gets no apostrophe
+ *   there, and is quoted only if it holds a character that requires quoting. Quoting
+ *   protects that reader at most in the first column; in any later column, or wherever the
+ *   value is not quoted, it starts a live cell there. Read the file with the delimiter it
+ *   was written with.
+ * - A field containing a comma, semicolon or TAB is quoted whatever the delimiter, and so
+ *   is a field containing any character of a multi-character delimiter. Quoting changes no
+ *   value, and protects only a reader in step with the writer.
+ * - **The delimiter must play no other part in the file.** It is written between cells,
+ *   where no apostrophe can go, and `escapeCsvField` accepts any delimiter. One containing
+ *   `=`, `+`, `-`, `@` or a character whose NFKC form is one of them, such as their
+ *   full-width or small forms, puts a trigger at the start of a field for a reader that
+ *   splits on anything else: `toCsvRow(["", "1+1"], { delimiter: "=" })` is `=1+1`. One
+ *   containing `'` lets a reader that splits on it cut the apostrophe off a neutralised
+ *   cell. One containing `"`, CR or LF leaves the apostrophes working but breaks RFC 4180
+ *   framing: a `"` there opens a quoted field where the writer meant a delimiter, and CR
+ *   or LF ends the record for every RFC 4180 reader. No reader can then count on staying
+ *   in step with the writer, which is all that quoting protects.
  * - 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
@@ -288,10 +336,12 @@ declare function encodeLogValue(value: string, options?: {
  * ```ts
  * escapeCsvField("=WEBSERVICE(\"https://evil.example\")");
  * // quoted, and inert on open
+ * escapeCsvField("a\n=1+1"); // "\"a\n'=1+1\"" — inert after the line break too
+ * escapeCsvField("a\r\nb"); // "\"a\r\nb\"" — quoted, value unchanged
  * escapeCsvField(-1234); // "-1234" — a number, not a formula
  * ```
  */
-declare function escapeCsvField(value: unknown, options?: {
+export declare function escapeCsvField(value: unknown, options?: {
   readonly delimiter?: string;
 }): string;
 /**
@@ -307,7 +357,7 @@ declare function escapeCsvField(value: unknown, options?: {
  * toCsvRow(["Ada Lovelace", "=1+1", 42]);
  * ```
  */
-declare function toCsvRow(values: readonly unknown[], options?: {
+export declare function toCsvRow(values: readonly unknown[], options?: {
   readonly delimiter?: string;
 }): string;
 /**
@@ -338,7 +388,7 @@ declare function toCsvRow(values: readonly unknown[], options?: {
  * const html = "<script>window.__DATA__ = " + json + ";</script>";
  * ```
  */
-declare function encodeJsonForScript(value: unknown): string;
+export declare function encodeJsonForScript(value: unknown): string;
 /**
  * Fold non-ASCII lookalike characters onto ASCII and compose to NFC.
  *
@@ -354,12 +404,12 @@ declare function encodeJsonForScript(value: unknown): string;
  * @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;
+export declare function normalizeUnicode(input: string): string;
 /**
  * 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";
+export declare const THREAT_DETECTED_MESSAGE = "Input contains potentially unsafe content";
 /**
  * Refinement helper for `zod.string().refine(...)`, `effect/Schema.filter(...)`, or
  * any predicate-based validator. Equivalent to {@link isSafeInput} with defaults.
@@ -367,7 +417,7 @@ declare const THREAT_DETECTED_MESSAGE = "Input contains potentially unsafe conte
  * @param input - String to test.
  * @returns `true` when no detector fires.
  */
-declare function validateSafeText(input: string): boolean;
+export declare function validateSafeText(input: string): boolean;
 /**
  * Validate a human name field.
  *
@@ -397,7 +447,7 @@ declare function validateSafeText(input: string): boolean;
  * validatePersonName("<script>x</script>"); // false
  * ```
  */
-declare function validatePersonName(input: string): boolean;
+export declare function validatePersonName(input: string): boolean;
 /**
  * Validate a human name field.
  *
@@ -409,7 +459,7 @@ declare function validatePersonName(input: string): boolean;
  * @param input - Candidate name.
  * @returns `true` when the value is a plausible name.
  */
-declare function validateSafeName(input: string): boolean;
+export declare function validateSafeName(input: string): boolean;
 /**
  * Validate an email address.
  *
@@ -424,7 +474,7 @@ declare function validateSafeName(input: string): boolean;
  * @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;
+export declare function validateSafeEmail(input: string): boolean;
 /**
  * Render a user-facing error message for a detection result.
  *
@@ -437,10 +487,10 @@ declare function validateSafeEmail(input: string): boolean;
  * @returns A message, or `""` when the result is safe — so `message || undefined`
  *   works at a call site.
  */
-declare function getThreatErrorMessage(result: {
+export declare function getThreatErrorMessage(result: {
   readonly isSafe: boolean;
   readonly threats: readonly ThreatSummary[];
 }): string;
 //#endregion
-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 };
+export type { ThreatFinding, ThreatType };
 //# 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":";;;;;;;;;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"}
+{"version":3,"file":"validators.d.mts","names":[],"sources":["../src/validators.ts"],"mappings":";;;;;;;;;iBAiDiB;;EAEhB;;EAEA,SAAS;;;;;;;;;iBAUO;;WAEP,MAAM;;WAEN;;WAEA;;;;;;;;;;;;;iBAkBO;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;;;;;;;;wBAkDe,oBAAoB,gBAAgB;;;;;;;;;;;;wBAepC,2BAA2B,gBAAgB;;;;;;;;;;;wBAc3C,qBAAqB,gBAAgB;;;;;;;;wBAWrC,uBAAuB,gBAAgB;;;;;;;;;;;;wBAevC,yBAAyB,gBAAgB;;;;;;;;;;;;;wBAgBzC,sBAAsB,gBAAgB;;;;;;;;;;;;;;;wBA2CtC,mBAAmB,gBAAgB;;;;;;;;;;;;;;;wBA0CnC,qBACf,eACA,SAAQ,wBACN;;;;;;;;wBA8Ba,YAAY,eAAe,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAmCpC,eAAe;;;;;;;;;;;;;;;;;;;wBA4Cf,oBAAoB;;;;;;;;;;;;wBAwBpB,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAwDnB,eACf,eACA;WAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAiXL,eACf,gBACA;WAAoB;;;;;;;;;;;;;;;wBA8CL,SACf,4BACA;WAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAyDL,oBAAoB;;;;;;;;;;;;;;;;wBAuCpB,iBAAiB;;;;;qBAYpB;;;;;;;;wBASG,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAoDjB,mBAAmB;;;;;;;;;;;;wBAyBnB,iBAAiB;;;;;;;;;;;;;;;wBAyBjB,kBAAkB;;;;;;;;;;;;;wBA2BlB,sBAAsB;WAC5B;WACA,kBAAkB"}