@cdxgen/cdxgen 13.3.0 → 13.5.0

package/lib/parsers/email.js

@@ -0,0 +1,277 @@
+import { isIPv4, isIPv6 } from "node:net";
+import { domainToASCII, domainToUnicode } from "node:url";
+
+/**
+ * Validation of RFC 6531 internationalized email addresses: the JSON Schema
+ * `idn-email` format the CycloneDX schemas assert on contact addresses.
+ *
+ * It follows what `cdxrs validate` (jsonschema-rs) accepts, so the JS and Rust
+ * validators agree on the addresses BOMs actually carry, internationalized
+ * ones included. Two deliberate differences keep this small:
+ * - a `Display Name <address>` string is not an address here, as RFC 6531
+ *   says; jsonschema-rs tolerates it, but cdxgen never emits one and the
+ *   source parsers must not mistake one for an email;
+ * - the RFC 5892 contextual rules and the RFC 5893 bidi rule are not applied,
+ *   so a few exotic internationalized domains are accepted that cdxrs
+ *   rejects. No valid domain is rejected for that.
+ *
+ * Every check is a bounded pass over the input with no backtracking regular
+ * expression.
+ */
+
+const LOCAL_PART_MAX_LENGTH = 64;
+const HOSTNAME_MAX_LENGTH = 253;
+const LABEL_MAX_LENGTH = 63;
+const ATEXT_SPECIALS = "!#$%&'*+-/=?^_`{|}~";
+// Appended before IDNA conversion so a numeric last label is not read as an
+// IPv4 address by the WHATWG host parser behind `domainToASCII`.
+const CONVERSION_SUFFIX = ".invalid";
+// What an internationalized label may hold: letters, combining marks and
+// decimal digits (RFC 5892 PVALID, by general category), plus the characters
+// RFC 5892 makes PVALID by exception, such as the Catalan middle dot.
+const IDNA_LABEL_CHAR = /^[\p{L}\p{Mn}\p{Mc}\p{Nd}]$/u;
+const IDNA_EXCEPTIONS = new Set([
+  "·",
+  "͵",
+  "׳",
+  "״",
+  "۽",
+  "۾",
+  "་",
+  "‌",
+  "‍",
+  "〇",
+  "・",
+]);
+const COMBINING_MARK = /^\p{M}$/u;
+
+/**
+ * @param {string} text Text to inspect
+ * @returns {boolean} Whether the text holds only ASCII
+ */
+const isAscii = (text) => {
+  for (let index = 0; index < text.length; index++) {
+    if (text.charCodeAt(index) > 0x7f) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * @param {number} code Code point
+ * @returns {boolean} Whether the code point is an ASCII letter or digit
+ */
+const isAsciiAlphanumeric = (code) =>
+  (code >= 0x30 && code <= 0x39) ||
+  (code >= 0x41 && code <= 0x5a) ||
+  (code >= 0x61 && code <= 0x7a);
+
+/**
+ * RFC 5322 `atext`, widened by RFC 6531 to every non-ASCII code point.
+ *
+ * @param {string} char One code point
+ * @returns {boolean} Whether it may appear in an unquoted local part atom
+ */
+const isAtext = (char) => {
+  const code = char.codePointAt(0);
+  return (
+    code > 0x7f || isAsciiAlphanumeric(code) || ATEXT_SPECIALS.includes(char)
+  );
+};
+
+/**
+ * The content of a quoted local part: printable ASCII other than `"` and `\`,
+ * non-ASCII, spaces and tabs, and backslash-escaped printable characters.
+ *
+ * @param {string} text Quoted local part without its surrounding quotes
+ * @returns {boolean} Whether the quoted content is valid
+ */
+const isQuotedContent = (text) => {
+  const chars = [...text];
+  for (let index = 0; index < chars.length; index++) {
+    const code = chars[index].codePointAt(0);
+    if (code === 0x5c) {
+      index++;
+      const escaped = chars[index]?.codePointAt(0);
+      if (escaped === undefined || escaped < 0x21 || escaped === 0x7f) {
+        return false;
+      }
+    } else if (code < 0x20 || code === 0x22 || code === 0x7f) {
+      if (code !== 0x09) {
+        return false;
+      }
+    }
+  }
+  return true;
+};
+
+/**
+ * A dot-atom (`atext` atoms joined by single dots) or a quoted string, at
+ * most 64 characters.
+ *
+ * @param {string} localPart Text before the last `@`
+ * @returns {boolean} Whether it is a valid local part
+ */
+const isValidLocalPart = (localPart) => {
+  if (!localPart || [...localPart].length > LOCAL_PART_MAX_LENGTH) {
+    return false;
+  }
+  if (
+    localPart.length >= 2 &&
+    localPart.startsWith('"') &&
+    localPart.endsWith('"')
+  ) {
+    // An empty quoted local part (`""@example.com`) is valid per RFC 5321.
+    return isQuotedContent(localPart.slice(1, -1));
+  }
+  return localPart
+    .split(".")
+    .every((atom) => atom.length > 0 && [...atom].every(isAtext));
+};
+
+/**
+ * An RFC 1123 label in ASCII (A-label) form.
+ *
+ * @param {string} label ASCII label
+ * @returns {boolean} Whether the label is valid
+ */
+const isValidAsciiLabel = (label) => {
+  if (
+    !label ||
+    label.length > LABEL_MAX_LENGTH ||
+    label.startsWith("-") ||
+    label.endsWith("-")
+  ) {
+    return false;
+  }
+  for (let index = 0; index < label.length; index++) {
+    const code = label.charCodeAt(index);
+    if (!isAsciiAlphanumeric(code) && code !== 0x2d) {
+      return false;
+    }
+  }
+  // Hyphens in the third and fourth positions are reserved for A-labels.
+  return label.slice(2, 4) !== "--" || label.toLowerCase().startsWith("xn--");
+};
+
+/**
+ * The Unicode form of a label, as `domainToUnicode` returns it.
+ *
+ * @param {string} label Unicode label
+ * @returns {boolean} Whether the label is valid
+ */
+const isValidUnicodeLabel = (label) => {
+  // `domainToUnicode` leaves an undecodable A-label as it was.
+  if (label.toLowerCase().startsWith("xn--")) {
+    return false;
+  }
+  if (isAscii(label)) {
+    return true;
+  }
+  if (
+    label.startsWith("-") ||
+    label.endsWith("-") ||
+    label.slice(2, 4) === "--"
+  ) {
+    return false;
+  }
+  const chars = [...label];
+  return (
+    !COMBINING_MARK.test(chars[0]) &&
+    chars.every(
+      (char) =>
+        char.charCodeAt(0) <= 0x7f ||
+        IDNA_EXCEPTIONS.has(char) ||
+        IDNA_LABEL_CHAR.test(char),
+    )
+  );
+};
+
+/**
+ * An internationalized hostname: mapped to its A-label form with UTS #46
+ * processing, held to the ASCII hostname rules, and every A-label decoded
+ * back and checked for the characters IDNA allows.
+ *
+ * @param {string} hostname Hostname, possibly holding non-ASCII labels
+ * @returns {boolean} Whether it is a valid IDN hostname
+ */
+export const isValidIdnHostname = (hostname) => {
+  if (typeof hostname !== "string" || !hostname) {
+    return false;
+  }
+  for (let index = 0; index < hostname.length; index++) {
+    // Controls and spaces never belong in a hostname; the WHATWG parser
+    // behind `domainToASCII` would silently strip tabs and newlines.
+    const code = hostname.charCodeAt(index);
+    if (code <= 0x20 || code === 0x7f) {
+      return false;
+    }
+  }
+  let ascii = hostname;
+  if (!isAscii(hostname)) {
+    const converted = domainToASCII(`${hostname}${CONVERSION_SUFFIX}`);
+    if (!converted.endsWith(CONVERSION_SUFFIX)) {
+      return false;
+    }
+    ascii = converted.slice(0, -CONVERSION_SUFFIX.length);
+  }
+  if (
+    !ascii ||
+    ascii.length > HOSTNAME_MAX_LENGTH ||
+    ascii.endsWith(".") ||
+    !ascii.split(".").every(isValidAsciiLabel)
+  ) {
+    return false;
+  }
+  if (!/(^|\.)xn--/i.test(ascii)) {
+    return true;
+  }
+  const unicode = domainToUnicode(`${ascii}${CONVERSION_SUFFIX}`);
+  return (
+    unicode.endsWith(CONVERSION_SUFFIX) &&
+    unicode
+      .slice(0, -CONVERSION_SUFFIX.length)
+      .split(".")
+      .every(isValidUnicodeLabel)
+  );
+};
+
+/**
+ * @param {string} domain Text after the last `@`
+ * @returns {boolean} Whether it is a valid hostname or address literal
+ */
+const isValidEmailDomain = (domain) => {
+  if (domain.startsWith("[") && domain.endsWith("]")) {
+    const literal = domain.slice(1, -1);
+    // RFC 5321 address-literal tags are case-insensitive.
+    if (literal.slice(0, 5).toLowerCase() === "ipv6:") {
+      return isIPv6(literal.slice(5));
+    }
+    return isIPv4(literal);
+  }
+  return isValidIdnHostname(domain);
+};
+
+/**
+ * Whether a value is a valid RFC 6531 email address (`idn-email`): a dot-atom
+ * or quoted local part, where non-ASCII characters are allowed, then `@` and
+ * an internationalized hostname or a bracketed IPv4/IPv6 literal.
+ *
+ * @param {string} value Candidate email address
+ * @returns {boolean} true when the value is a valid address
+ */
+export const isValidIdnEmail = (value) => {
+  if (typeof value !== "string") {
+    return false;
+  }
+  // A domain never holds `@`; a quoted local part may.
+  const separator = value.lastIndexOf("@");
+  if (separator <= 0 || separator === value.length - 1) {
+    return false;
+  }
+  return (
+    isValidLocalPart(value.slice(0, separator)) &&
+    isValidEmailDomain(value.slice(separator + 1))
+  );
+};

package/lib/parsers/largeJson.js

@@ -256,8 +256,9 @@ class ByteCursor {
 
 // The members of the object at the cursor, as { key, start, end } byte ranges
 // of their values, in file order. A repeated key keeps its first position and
-// its last range, which is what JSON.parse does.
-function scanObjectMembers(cursor) {
+// its last range, which is what JSON.parse does. With `stopAt`, the scan ends
+// at the first member of that name, leaving the rest of the object unread.
+function scanObjectMembers(cursor, stopAt = undefined) {
   if (cursor.nextToken() !== OPEN_BRACE) {
     cursor.fail("Expected an object");
   }
@@ -280,6 +281,9 @@ function scanObjectMembers(cursor) {
     const start = cursor.offset;
     cursor.skipValue();
     members.set(key, { start, end: cursor.offset });
+    if (key === stopAt) {
+      return members;
+    }
     const delimiter = cursor.nextToken();
     if (delimiter === CLOSE_BRACE) {
       return members;
@@ -412,6 +416,34 @@ export function indexJsonObject(filePath, options = {}) {
   });
 }
 
+/**
+ * Decode one member of the top-level object in a JSON file, reading the file
+ * only up to the end of that member. A member near the start of a large file
+ * costs a few bounded reads, however large the rest of the file is; the rest
+ * is not checked for well-formedness.
+ *
+ * @param {string} filePath JSON file whose top-level value is an object
+ * @param {string} name Member to decode
+ * @param {Object} [options] Batch and chunk size overrides, for tests
+ * @returns {*} The decoded value, or undefined when the object has no such member
+ * @throws {SyntaxError} When the object is malformed before the member ends
+ */
+export function readJsonMember(filePath, name, options = {}) {
+  const resolved = resolveOptions(options);
+  return withFile(filePath, (fd) => {
+    const cursor = new ByteCursor(
+      fd,
+      0,
+      statSync(filePath).size,
+      resolved.chunkBytes,
+    );
+    const range = scanObjectMembers(cursor, name).get(name);
+    return range
+      ? decodeRange(fd, range.start, range.end, undefined, resolved)
+      : undefined;
+  });
+}
+
 /**
  * Decode the JSON value stored in a byte range of a file, without ever holding
  * more than a bounded run of it in one string.

package/lib/parsers/strictJson.js

@@ -0,0 +1,322 @@
+/**
+ * Strict JSON reading for signed documents.
+ *
+ * JSF signs the RFC 8785 (JCS) form of a document, and JCS is defined over
+ * I-JSON (RFC 7493) input. `JSON.parse` and lenient UTF-8 decoding accept
+ * things I-JSON rules out, and each lets two parsers read different values
+ * from the same signed bytes:
+ *
+ * - a member name repeated within one object, where `JSON.parse` keeps the last
+ *   value and other parsers keep the first or refuse the document;
+ * - a number an IEEE 754 double cannot hold exactly, which JavaScript rounds
+ *   while arbitrary-precision parsers keep every digit;
+ * - bytes that are not UTF-8, which lenient decoders turn into U+FFFD while
+ *   others refuse them or read another encoding;
+ * - an unpaired UTF-16 surrogate escape, which some parsers keep and others
+ *   replace.
+ *
+ * {@link parseStrictJson} rejects all of them, so the values a verifier checks
+ * are the values every consumer of the document reads.
+ */
+
+/**
+ * Raised when JSON text is well-formed but breaks one of the rules above.
+ */
+export class StrictJsonError extends Error {
+  /**
+   * @param {string} message - Description of the problem
+   * @param {string} pointer - RFC 6901 JSON Pointer to the offending member or value
+   */
+  constructor(message, pointer) {
+    super(message);
+    this.name = "StrictJsonError";
+    this.pointer = pointer;
+  }
+}
+
+const QUOTE = 0x22;
+const BACKSLASH = 0x5c;
+const OPEN_OBJECT = 0x7b;
+const CLOSE_OBJECT = 0x7d;
+const OPEN_ARRAY = 0x5b;
+const CLOSE_ARRAY = 0x5d;
+const COMMA = 0x2c;
+const MINUS = 0x2d;
+const PLUS = 0x2b;
+const DOT = 0x2e;
+const DIGIT_0 = 0x30;
+const DIGIT_9 = 0x39;
+const LOWER_E = 0x65;
+const UPPER_E = 0x45;
+const LOWER_U = 0x75;
+
+// Integers with at most 15 digits are below 2^53, so a double holds them exactly.
+const EXACT_INTEGER_DIGITS = 15;
+const MAX_SHOWN_NUMBER_LENGTH = 40;
+
+function isDigit(code) {
+  return code >= DIGIT_0 && code <= DIGIT_9;
+}
+
+function escapePointerToken(token) {
+  return token.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+function pointerOf(frames, depth) {
+  let pointer = "";
+  for (let i = 0; i < depth; i++) {
+    const frame = frames[i];
+    pointer += `/${frame.object ? escapePointerToken(frame.key) : frame.index}`;
+  }
+  return pointer;
+}
+
+function showNumber(token) {
+  return token.length > MAX_SHOWN_NUMBER_LENGTH
+    ? `${token.slice(0, MAX_SHOWN_NUMBER_LENGTH)}…`
+    : token;
+}
+
+/**
+ * Reduces a JSON or ECMAScript number literal to its exact decimal value as a
+ * significand without leading or trailing zeros and a power-of-ten exponent.
+ * The sign is ignored: a finite non-zero double keeps the sign of its literal,
+ * and zero compares equal to negative zero.
+ */
+function decimalValue(literal) {
+  let i = literal.charCodeAt(0) === MINUS ? 1 : 0;
+  let digits = "";
+  let fractionLength = 0;
+  while (i < literal.length && isDigit(literal.charCodeAt(i))) {
+    digits += literal[i++];
+  }
+  if (literal.charCodeAt(i) === DOT) {
+    i++;
+    while (i < literal.length && isDigit(literal.charCodeAt(i))) {
+      digits += literal[i++];
+      fractionLength++;
+    }
+  }
+  let exponent = 0;
+  const marker = literal.charCodeAt(i);
+  if (marker === LOWER_E || marker === UPPER_E) {
+    exponent = Number(literal.slice(i + 1));
+  }
+  let start = 0;
+  while (start < digits.length && digits.charCodeAt(start) === DIGIT_0) {
+    start++;
+  }
+  let end = digits.length;
+  while (end > start && digits.charCodeAt(end - 1) === DIGIT_0) {
+    end--;
+  }
+  if (start === end) {
+    return { significand: "", exponent: 0 };
+  }
+  return {
+    significand: digits.slice(start, end),
+    exponent: exponent - fractionLength + (digits.length - end),
+  };
+}
+
+/**
+ * Returns a description of why a JSON number token does not denote exactly the
+ * double that `JSON.parse` produces for it, or undefined when it does.
+ */
+function numberProblem(token) {
+  const negative = token.charCodeAt(0) === MINUS;
+  const digitCount = token.length - (negative ? 1 : 0);
+  if (digitCount <= EXACT_INTEGER_DIGITS) {
+    let integer = true;
+    for (let i = negative ? 1 : 0; i < token.length; i++) {
+      if (!isDigit(token.charCodeAt(i))) {
+        integer = false;
+        break;
+      }
+    }
+    if (integer) {
+      return undefined;
+    }
+  }
+  const value = Number(token);
+  if (!Number.isFinite(value)) {
+    return "is outside the range of an IEEE 754 double";
+  }
+  const written = decimalValue(token);
+  const parsed = decimalValue(String(value));
+  if (
+    written.significand === parsed.significand &&
+    (written.significand === "" || written.exponent === parsed.exponent)
+  ) {
+    return undefined;
+  }
+  return `cannot be held exactly by an IEEE 754 double; JSON.parse reads it as ${String(value)}`;
+}
+
+function isHighSurrogate(unit) {
+  return unit >= 0xd800 && unit <= 0xdbff;
+}
+
+function isLowSurrogate(unit) {
+  return unit >= 0xdc00 && unit <= 0xdfff;
+}
+
+/**
+ * Finds the end of the string token starting at `start`, and whether it holds
+ * escapes or a UTF-16 surrogate, written raw or as `\u` escape, without its
+ * other half.
+ */
+function stringEnd(text, start) {
+  let i = start + 1;
+  let escaped = false;
+  let unpaired = false;
+  let pendingHigh = false;
+  for (;;) {
+    const code = text.charCodeAt(i);
+    if (code === QUOTE) {
+      return { end: i + 1, escaped, unpaired: unpaired || pendingHigh };
+    }
+    let unit = code;
+    let width = 1;
+    if (code === BACKSLASH) {
+      escaped = true;
+      if (text.charCodeAt(i + 1) === LOWER_U) {
+        unit = Number.parseInt(text.slice(i + 2, i + 6), 16);
+        width = 6;
+      } else {
+        unit = 0;
+        width = 2;
+      }
+    }
+    const low = isLowSurrogate(unit);
+    if (pendingHigh !== low) {
+      unpaired = true;
+    }
+    pendingHigh = isHighSurrogate(unit);
+    i += width;
+  }
+}
+
+function numberEnd(text, start) {
+  let i = start;
+  while (i < text.length) {
+    const code = text.charCodeAt(i);
+    if (
+      isDigit(code) ||
+      code === MINUS ||
+      code === PLUS ||
+      code === DOT ||
+      code === LOWER_E ||
+      code === UPPER_E
+    ) {
+      i++;
+    } else {
+      break;
+    }
+  }
+  return i;
+}
+
+/**
+ * Walks well-formed JSON text without recursion and throws a StrictJsonError
+ * at the first repeated member name, inexact number, or unpaired surrogate.
+ */
+function checkStrictJson(text) {
+  const frames = [];
+  let i = 0;
+  while (i < text.length) {
+    const code = text.charCodeAt(i);
+    if (code === OPEN_OBJECT || code === OPEN_ARRAY) {
+      frames.push({
+        object: code === OPEN_OBJECT,
+        names: code === OPEN_OBJECT ? new Set() : undefined,
+        key: undefined,
+        index: 0,
+        expectName: code === OPEN_OBJECT,
+      });
+      i++;
+    } else if (code === CLOSE_OBJECT || code === CLOSE_ARRAY) {
+      frames.pop();
+      i++;
+    } else if (code === COMMA) {
+      const top = frames.at(-1);
+      if (top.object) {
+        top.expectName = true;
+      } else {
+        top.index++;
+      }
+      i++;
+    } else if (code === QUOTE) {
+      const { end, escaped, unpaired } = stringEnd(text, i);
+      const top = frames.at(-1);
+      const isName = Boolean(top?.object && top.expectName);
+      if (unpaired) {
+        const pointer = isName
+          ? `${pointerOf(frames, frames.length - 1)}/${escapePointerToken(JSON.parse(text.slice(i, end)))}`
+          : pointerOf(frames, frames.length);
+        throw new StrictJsonError(
+          `The ${isName ? "member name" : "string"} at ${pointer || "the document root"} holds an unpaired UTF-16 surrogate, which JSON parsers keep, replace, or reject differently.`,
+          pointer,
+        );
+      }
+      if (isName) {
+        const name = escaped
+          ? JSON.parse(text.slice(i, end))
+          : text.slice(i + 1, end - 1);
+        if (top.names.has(name)) {
+          throw new StrictJsonError(
+            `Duplicate member name at ${pointerOf(frames, frames.length - 1)}/${escapePointerToken(name)}. JSON parsers disagree on which of the repeated values the document holds.`,
+            `${pointerOf(frames, frames.length - 1)}/${escapePointerToken(name)}`,
+          );
+        }
+        top.names.add(name);
+        top.key = name;
+        top.expectName = false;
+      }
+      i = end;
+    } else if (code === MINUS || isDigit(code)) {
+      const end = numberEnd(text, i);
+      const token = text.slice(i, end);
+      const problem = numberProblem(token);
+      if (problem) {
+        const pointer = pointerOf(frames, frames.length);
+        throw new StrictJsonError(
+          `The number ${showNumber(token)} at ${pointer || "the document root"} ${problem}.`,
+          pointer,
+        );
+      }
+      i = end;
+    } else {
+      i++;
+    }
+  }
+}
+
+/**
+ * Parses JSON the way `JSON.parse` does, but refuses bytes that are not UTF-8,
+ * repeated member names within an object, numbers that an IEEE 754 double
+ * cannot hold exactly, and unpaired UTF-16 surrogates.
+ *
+ * Pass the raw bytes of a document rather than text decoded elsewhere, so that
+ * invalid UTF-8 is detected instead of being replaced by U+FFFD.
+ *
+ * @param {string|Uint8Array} input - JSON text, or its UTF-8 bytes
+ * @returns {any} - The parsed value
+ * @throws {SyntaxError} When the text is not JSON
+ * @throws {StrictJsonError} When the input breaks one of the rules above
+ */
+export function parseStrictJson(input) {
+  let text = input;
+  if (typeof input !== "string") {
+    try {
+      text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
+        input,
+      );
+    } catch {
+      throw new StrictJsonError("The document is not valid UTF-8.", "");
+    }
+  }
+  const value = JSON.parse(text);
+  checkStrictJson(text);
+  return value;
+}