@mitre/hdf-utilities 3.6.0-rc.2 → 3.6.0-rc.4

package/README.md

@@ -15,6 +15,33 @@ Generic utility functions for working with common data formats (JSON, XML, CSV)
 - Parse HDF-specific structures (use `@mitre/hdf-parsers` for HDF traversal)
 - Convert between security tool formats (use `@mitre/hdf-converters`)
 
+### Why the Go and TypeScript surfaces differ
+
+The two languages do not export the same modules, and that is deliberate. This
+package holds cross-language **policy** — decisions both implementations must
+agree on — while each language uses its own serializer.
+
+The plumbing in `hash` and `json` has no Go counterpart because Go's standard library already provides it: `crypto/sha256`, `encoding/json`. Wrapping `parseJSON`, `stringifyJSON` or `generateHash` in Go would add a layer with no decision in it. The TypeScript side needs those wrappers because JavaScript ships no equivalent, and the wrapper is where safe defaults get centralised. The policy in those modules does exist in both: Go's `CanonicalJSON`, `ChecksumJSON` and `SHA256Hex` are the twins of TypeScript's `canonicalJson` and `canonicalChecksum`. The canonical byte form a checksum is taken over (sorted keys, `<`, `>` and `&` escaped, null-valued keys dropped) is a decision both implementations must agree on, so it is pinned against shared vectors rather than left to each serializer.
+
+`csv` exists in both, but the two surfaces are deliberately different sizes: the
+TypeScript module parses and builds CSV, while the Go one carries only the
+formula-injection policy and leaves writing to `encoding/csv`.
+
+XML shows the pattern most clearly. Go's `xml.go` exports only
+`ContainsXMLEntityDeclarations` and `ExtractXMLRootElement` — an XXE-safety
+policy and a domain helper — and leaves parsing to `encoding/xml`. The
+TypeScript `xml/` module wraps fast-xml-parser and carries the same policy in its
+defaults.
+
+So the test for whether something belongs in both languages is not "does the
+other one have it" but "is it a decision, or is it plumbing". Formula-injection
+sanitizing (`SanitizeCSVValue` / `sanitizeCsvValue`) is a decision: which leading
+characters a spreadsheet will execute, and what neutralises them. It exists in
+both, pinned to one shared table in `testdata/csv-sanitize-cases.json`, because a
+trigger added on one side alone would leave the other exporting CSVs a
+spreadsheet runs. CSV *writing* is plumbing, and stays with each language's
+serializer.
+
 ### hdf-utilities vs. hdf-validators
 
 | hdf-utilities | hdf-validators |

package/dist/csv/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/csv/index.ts"],"mappings":";;;;;UAiBiB;EACf;EACA;EACA,mBAAmB,gBAAgB;EACnC;EACA;EACA;;;;;UAMe;EACf;EACA;EACA;EACA;;;;;;;;;iBAwEc,SAAS,IAAI,yBAC3B,aACA,UAAU,QAAQ,mBACjB;;;;;;;;iBAoDa,cACd,aACA,UAAU,QAAQ;;;;;;;;;;;iBAiCJ,SAAS,IAAI,yBAC3B,MAAM,KACN,UAAU,QAAQ;EAAqB;;;;;;;;;;;;iBAuDzB,cACd,kBACA,UAAU,QAAQ;EAAqB;;;;;;;iBA2BzB,WAAW;;;;;;;;;;iBA0BX,iBAAiB;;;;;;;iBAejB,iBAAiB;;;;;;;iBAUjB,kBAAkB,UAAU,yBAC1C,KAAK,IACJ"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/csv/index.ts"],"mappings":";;;;;UAkBiB;EACf;EACA;EACA,mBAAmB,gBAAgB;EACnC;EACA;EACA;;;;;UAMe;EACf;EACA;EACA;EACA;;;;;;;;;iBAwEc,SAAS,IAAI,yBAC3B,aACA,UAAU,QAAQ,mBACjB;;;;;;;;iBAoDa,cACd,aACA,UAAU,QAAQ;;;;;;;;;;;iBAiCJ,SAAS,IAAI,yBAC3B,MAAM,KACN,UAAU,QAAQ;EAAqB;;;;;;;;;;;;iBA6GzB,cACd,kBACA,UAAU,QAAQ;EAAqB;;;;;;;iBA4BzB,WAAW;;;;;;;;;;iBA0BX,iBAAiB;;;;;;;iBAejB,iBAAiB;;;;;;;iBAUjB,kBAAkB,UAAU,yBAC1C,KAAK,IACJ"}

package/dist/csv/index.js

@@ -129,11 +129,58 @@ function buildCsv(data, options) {
 		const rows = processedData.map((row) => Object.values(row).map(String));
 		result = dsv.formatRows(rows);
 	} else result = dsv.format(processedData);
+	result = quoteLeadingWhitespace(result, dsv, opts.delimiter ?? ",");
 	result = terminateFinalRecord(result);
 	if (opts.newline && opts.newline !== "\n") result = result.replace(/\n/g, opts.newline);
 	return result;
 }
 /**
+* Quote any field Go's encoding/csv would quote and d3-dsv would not.
+*
+* d3-dsv quotes only for the delimiter, a quote, or a newline. Go additionally
+* quotes when the field's FIRST rune is Unicode whitespace — so "  padded  "
+* round-trips through a parser that trims — and quotes the literal field `\.`,
+* which some dialects treat as end-of-data. Trailing whitespace alone triggers
+* neither language. Without this a TS CSV differs from its Go twin on any such
+* value: the same class of split terminateFinalRecord exists to close.
+*
+* ONE predicate decides, and it is the same one Go uses. An earlier version
+* tested [ \t] to skip the re-parse cheaply and \s to decide, so a field led by
+* U+00A0 or U+2003 exited before the decision ever ran.
+*
+* Re-parses rather than intercepting the writer because d3-dsv exposes no
+* per-field hook on format(); the parse is over output this function just
+* produced, so it cannot fail on unbalanced quotes.
+*/
+function quoteLeadingWhitespace(csv, dsv, delimiter) {
+	return formatRowsGoCompatible(dsv.parseRows(csv), dsv, delimiter);
+}
+/** The one writer both public builders go through, so a field cannot come out
+* quoted from one and bare from the other. */
+function formatRowsGoCompatible(rows, dsv, delimiter) {
+	return rows.map((row) => row.map((field) => requote(field, dsv)).join(delimiter)).join("\n");
+}
+/**
+* Go's encoding/csv fieldNeedsQuotes, minus the conditions d3-dsv already
+* covers: a leading Unicode space, or the literal `\.`.
+*
+* The class is Go's unicode.IsSpace, spelled out rather than borrowed from
+* JavaScript's \s, which is not the same set: \s omits U+0085 (NEL) and adds
+* U+FEFF, which Unicode 4.0.1 removed from White_Space. Borrowing \s left a
+* field led by U+0085 unquoted here but quoted in Go, and the reverse for
+* U+FEFF.
+*/
+const GO_LEADING_SPACE = /^[\t\n\v\f\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]/;
+function goWouldQuote(field) {
+	return field === "\\." || GO_LEADING_SPACE.test(field);
+}
+/** One field, formatted by d3-dsv, then quoted if Go would quote it and d3-dsv did not. */
+function requote(field, dsv) {
+	const formatted = dsv.formatValue(field);
+	if (formatted.startsWith("\"") || !goWouldQuote(field)) return formatted;
+	return `"${field.replace(/"/g, "\"\"")}"`;
+}
+/**
 * Terminate the final record with a newline. d3-dsv leaves it off, but Go's
 * encoding/csv (which the Go converters use) always writes it, so without this
 * every TS CSV would differ from its Go twin by exactly one trailing byte.
@@ -162,7 +209,9 @@ function buildCsvArray(data, options) {
 	if (data.length === 0) return "";
 	let processedData = data;
 	if (sanitize) processedData = data.map((row) => sanitizeCsvArray(row));
-	let result = terminateFinalRecord(dsvFormat(opts.delimiter ?? ",").formatRows(processedData));
+	const delimiter = opts.delimiter ?? ",";
+	const dsv = dsvFormat(delimiter);
+	let result = terminateFinalRecord(formatRowsGoCompatible(processedData, dsv, delimiter));
 	if (opts.newline && opts.newline !== "\n") result = result.replace(/\n/g, opts.newline);
 	return result;
 }

package/dist/csv/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/csv/index.ts"],"sourcesContent":["/**\n * CSV parsing and generation utilities using d3-dsv\n *\n * SECURITY WARNING: CSV files opened in Excel/LibreOffice may execute formulas.\n * Use sanitization options when exporting data that may contain user-controlled content.\n */\n\nimport { dsvFormat } from 'd3-dsv';\n\nexport {\n  extractColumn as extractCsvColumn,\n  findRows as findCsvRows,\n} from '../object/index.js';\n\n/**\n * Options for parsing CSV\n */\nexport interface CsvParseOptions {\n  header?: boolean;\n  skipEmptyLines?: boolean;\n  transformHeader?: (header: string, index: number) => string;\n  dynamicTyping?: boolean;\n  delimiter?: string;\n  maxSize?: number;\n}\n\n/**\n * Options for building CSV\n */\nexport interface CsvBuildOptions {\n  header?: boolean;\n  newline?: string;\n  skipEmptyLines?: boolean;\n  delimiter?: string;\n}\n\n/**\n * Default options for parsing CSV with headers\n */\nconst DEFAULT_PARSE_OPTIONS: CsvParseOptions = {\n  header: true,\n  skipEmptyLines: true,\n  transformHeader: undefined,\n  dynamicTyping: false,\n};\n\n/**\n * Default options for parsing CSV without headers\n */\nconst DEFAULT_PARSE_ARRAY_OPTIONS: CsvParseOptions = {\n  header: false,\n  skipEmptyLines: true,\n  dynamicTyping: false,\n};\n\n/**\n * Default options for building CSV\n */\nconst DEFAULT_BUILD_OPTIONS: CsvBuildOptions = {\n  header: true,\n  newline: '\\n',\n  skipEmptyLines: true,\n};\n\n/**\n * Validate CSV quoting — throws if unclosed quotes are found\n */\nfunction validateQuoting(csv: string): void {\n  let inQuotes = false;\n  let row = 0;\n  for (let i = 0; i < csv.length; i++) {\n    if (csv[i] === '\"') {\n      if (inQuotes && i + 1 < csv.length && csv[i + 1] === '\"') {\n        i++; // skip escaped quote \"\"\n      } else {\n        inQuotes = !inQuotes;\n      }\n    } else if (csv[i] === '\\n' && !inQuotes) {\n      row++;\n    }\n  }\n  if (inQuotes) {\n    throw new Error(`CSV parsing failed: Row ${row}: Unclosed quote`);\n  }\n}\n\n/**\n * Convert string value to number or boolean when appropriate\n */\nfunction dynamicTypeConvert(value: string): unknown {\n  if (value === '') return value;\n  if (value === 'true') return true;\n  if (value === 'false') return false;\n  const num = Number(value);\n  if (!isNaN(num) && value.trim() !== '') return num;\n  return value;\n}\n\n/**\n * Parse CSV string into array of objects with headers as keys\n * @param csv - CSV string to parse\n * @param options - Optional parse configuration\n * @returns Array of objects representing rows\n * @throws Error if parsing fails\n */\nexport function parseCsv<T = Record<string, unknown>>(\n  csv: string,\n  options?: Partial<CsvParseOptions>\n): T[] {\n  if (options?.maxSize !== undefined && csv.length > options.maxSize) {\n    throw new Error(\n      `Input exceeds maximum allowed size: ${csv.length} bytes exceeds limit of ${options.maxSize} bytes`\n    );\n  }\n\n  const opts = { ...DEFAULT_PARSE_OPTIONS, ...options };\n  const trimmed = csv.trim();\n\n  validateQuoting(trimmed);\n\n  const dsv = dsvFormat(opts.delimiter ?? ',');\n  const parsed = dsv.parse(trimmed);\n  const { columns } = parsed;\n\n  // Pre-compute transformed headers\n  const headers = opts.transformHeader\n    ? columns.map((col, i) => opts.transformHeader!(col, i))\n    : columns;\n\n  let rows: Record<string, unknown>[] = parsed.map((row) => {\n    const obj: Record<string, unknown> = {};\n    columns.forEach((col, i) => {\n      let value: unknown = row[col] ?? '';\n      if (opts.dynamicTyping && typeof value === 'string') {\n        value = dynamicTypeConvert(value);\n      }\n      const key = headers[i];\n      if (key !== undefined) {\n        obj[key] = value;\n      }\n    });\n    return obj;\n  });\n\n  if (opts.skipEmptyLines) {\n    rows = rows.filter((row) =>\n      Object.values(row).some((v) => v !== '' && v !== null && v !== undefined)\n    );\n  }\n\n  return rows as T[];\n}\n\n/**\n * Parse CSV string into array of arrays without treating first row as headers\n * @param csv - CSV string to parse\n * @param options - Optional parse configuration\n * @returns Array of arrays representing rows\n * @throws Error if parsing fails\n */\nexport function parseCsvArray(\n  csv: string,\n  options?: Partial<CsvParseOptions>\n): string[][] {\n  if (options?.maxSize !== undefined && csv.length > options.maxSize) {\n    throw new Error(\n      `Input exceeds maximum allowed size: ${csv.length} bytes exceeds limit of ${options.maxSize} bytes`\n    );\n  }\n\n  const opts = { ...DEFAULT_PARSE_ARRAY_OPTIONS, ...options };\n  const trimmed = csv.trim();\n\n  validateQuoting(trimmed);\n\n  const dsv = dsvFormat(opts.delimiter ?? ',');\n  let rows = dsv.parseRows(trimmed);\n\n  if (opts.skipEmptyLines) {\n    rows = rows.filter((row) => !(row.length === 1 && row[0] === ''));\n  }\n\n  return rows;\n}\n\n/**\n * Build CSV string from array of objects\n *\n * SECURITY: Set sanitize=true when data may contain user-controlled content\n * to prevent CSV formula injection attacks in Excel/LibreOffice.\n *\n * @param data - Array of objects to convert to CSV\n * @param options - Optional build configuration and sanitize flag\n * @returns CSV string\n */\nexport function buildCsv<T = Record<string, unknown>>(\n  data: T[],\n  options?: Partial<CsvBuildOptions> & { sanitize?: boolean }\n): string {\n  const { sanitize, ...buildOpts } = options || {};\n  const opts = { ...DEFAULT_BUILD_OPTIONS, ...buildOpts };\n\n  if (data.length === 0) return '';\n\n  let processedData = data;\n  if (sanitize) {\n    processedData = data.map((row) =>\n      sanitizeCsvObject(row as Record<string, unknown>)\n    ) as T[];\n  }\n\n  const dsv = dsvFormat(opts.delimiter ?? ',');\n  let result: string;\n\n  if (opts.header === false) {\n    const rows = processedData.map((row) =>\n      Object.values(row as Record<string, unknown>).map(String)\n    );\n    result = dsv.formatRows(rows);\n  } else {\n    result = dsv.format(processedData as Record<string, unknown>[]);\n  }\n\n  result = terminateFinalRecord(result);\n\n  if (opts.newline && opts.newline !== '\\n') {\n    result = result.replace(/\\n/g, opts.newline);\n  }\n\n  return result;\n}\n\n/**\n * Terminate the final record with a newline. d3-dsv leaves it off, but Go's\n * encoding/csv (which the Go converters use) always writes it, so without this\n * every TS CSV would differ from its Go twin by exactly one trailing byte.\n * Applied before the newline substitution so a \\r\\n dialect gets it too.\n */\nfunction terminateFinalRecord(csv: string): string {\n  return csv.endsWith('\\n') ? csv : `${csv}\\n`;\n}\n\n/**\n * Build CSV string from array of arrays\n *\n * SECURITY: Set sanitize=true when data may contain user-controlled content\n * to prevent CSV formula injection attacks in Excel/LibreOffice.\n *\n * @param data - Array of arrays to convert to CSV\n * @param options - Optional build configuration and sanitize flag\n * @returns CSV string\n */\nexport function buildCsvArray(\n  data: string[][],\n  options?: Partial<CsvBuildOptions> & { sanitize?: boolean }\n): string {\n  const { sanitize, ...buildOpts } = options || {};\n  const opts = { ...DEFAULT_BUILD_OPTIONS, header: false, ...buildOpts };\n\n  if (data.length === 0) return '';\n\n  let processedData = data;\n  if (sanitize) {\n    processedData = data.map((row) => sanitizeCsvArray(row));\n  }\n\n  const dsv = dsvFormat(opts.delimiter ?? ',');\n  let result = terminateFinalRecord(dsv.formatRows(processedData));\n\n  if (opts.newline && opts.newline !== '\\n') {\n    result = result.replace(/\\n/g, opts.newline);\n  }\n\n  return result;\n}\n\n/**\n * Validate CSV format\n * @param csv - CSV string to validate\n * @returns True if valid CSV, false otherwise\n */\nexport function isValidCsv(csv: string): boolean {\n  if (!csv || csv.trim().length === 0) return false;\n\n  const trimmed = csv.trim();\n\n  // CSV must have at least one delimiter (comma) to be considered CSV structure\n  if (!trimmed.includes(',')) return false;\n\n  try {\n    validateQuoting(trimmed);\n  } catch {\n    return false;\n  }\n\n  return true;\n}\n\n/**\n * Sanitize a single CSV value to prevent formula injection\n *\n * Prefixes values starting with =, +, -, @, |, or % with a single quote\n * to prevent Excel/LibreOffice from interpreting them as formulas.\n *\n * @param value - Value to sanitize\n * @returns Sanitized value\n */\nexport function sanitizeCsvValue(value: unknown): string {\n  const str = String(value);\n  // Check if string starts with formula trigger characters\n  if (/^[=+\\-@|%]/.test(str)) {\n    return `'${str}`;\n  }\n  return str;\n}\n\n/**\n * Sanitize all values in an array to prevent formula injection\n *\n * @param values - Array of values to sanitize\n * @returns Array with sanitized values\n */\nexport function sanitizeCsvArray(values: unknown[]): string[] {\n  return values.map(sanitizeCsvValue);\n}\n\n/**\n * Sanitize all values in an object to prevent formula injection\n *\n * @param obj - Object with values to sanitize\n * @returns New object with sanitized values\n */\nexport function sanitizeCsvObject<T extends Record<string, unknown>>(\n  obj: T\n): Record<string, string> {\n  const sanitized: Record<string, string> = {};\n  for (const [key, value] of Object.entries(obj)) {\n    sanitized[key] = sanitizeCsvValue(value);\n  }\n  return sanitized;\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/csv/index.ts"],"sourcesContent":["/**\n * CSV parsing and generation utilities using d3-dsv\n *\n * SECURITY WARNING: CSV files opened in Excel/LibreOffice may execute formulas.\n * Use sanitization options when exporting data that may contain user-controlled content.\n */\n\nimport { dsvFormat } from 'd3-dsv';\nimport type { DSV } from 'd3-dsv';\n\nexport {\n  extractColumn as extractCsvColumn,\n  findRows as findCsvRows,\n} from '../object/index.js';\n\n/**\n * Options for parsing CSV\n */\nexport interface CsvParseOptions {\n  header?: boolean;\n  skipEmptyLines?: boolean;\n  transformHeader?: (header: string, index: number) => string;\n  dynamicTyping?: boolean;\n  delimiter?: string;\n  maxSize?: number;\n}\n\n/**\n * Options for building CSV\n */\nexport interface CsvBuildOptions {\n  header?: boolean;\n  newline?: string;\n  skipEmptyLines?: boolean;\n  delimiter?: string;\n}\n\n/**\n * Default options for parsing CSV with headers\n */\nconst DEFAULT_PARSE_OPTIONS: CsvParseOptions = {\n  header: true,\n  skipEmptyLines: true,\n  transformHeader: undefined,\n  dynamicTyping: false,\n};\n\n/**\n * Default options for parsing CSV without headers\n */\nconst DEFAULT_PARSE_ARRAY_OPTIONS: CsvParseOptions = {\n  header: false,\n  skipEmptyLines: true,\n  dynamicTyping: false,\n};\n\n/**\n * Default options for building CSV\n */\nconst DEFAULT_BUILD_OPTIONS: CsvBuildOptions = {\n  header: true,\n  newline: '\\n',\n  skipEmptyLines: true,\n};\n\n/**\n * Validate CSV quoting — throws if unclosed quotes are found\n */\nfunction validateQuoting(csv: string): void {\n  let inQuotes = false;\n  let row = 0;\n  for (let i = 0; i < csv.length; i++) {\n    if (csv[i] === '\"') {\n      if (inQuotes && i + 1 < csv.length && csv[i + 1] === '\"') {\n        i++; // skip escaped quote \"\"\n      } else {\n        inQuotes = !inQuotes;\n      }\n    } else if (csv[i] === '\\n' && !inQuotes) {\n      row++;\n    }\n  }\n  if (inQuotes) {\n    throw new Error(`CSV parsing failed: Row ${row}: Unclosed quote`);\n  }\n}\n\n/**\n * Convert string value to number or boolean when appropriate\n */\nfunction dynamicTypeConvert(value: string): unknown {\n  if (value === '') return value;\n  if (value === 'true') return true;\n  if (value === 'false') return false;\n  const num = Number(value);\n  if (!isNaN(num) && value.trim() !== '') return num;\n  return value;\n}\n\n/**\n * Parse CSV string into array of objects with headers as keys\n * @param csv - CSV string to parse\n * @param options - Optional parse configuration\n * @returns Array of objects representing rows\n * @throws Error if parsing fails\n */\nexport function parseCsv<T = Record<string, unknown>>(\n  csv: string,\n  options?: Partial<CsvParseOptions>\n): T[] {\n  if (options?.maxSize !== undefined && csv.length > options.maxSize) {\n    throw new Error(\n      `Input exceeds maximum allowed size: ${csv.length} bytes exceeds limit of ${options.maxSize} bytes`\n    );\n  }\n\n  const opts = { ...DEFAULT_PARSE_OPTIONS, ...options };\n  const trimmed = csv.trim();\n\n  validateQuoting(trimmed);\n\n  const dsv = dsvFormat(opts.delimiter ?? ',');\n  const parsed = dsv.parse(trimmed);\n  const { columns } = parsed;\n\n  // Pre-compute transformed headers\n  const headers = opts.transformHeader\n    ? columns.map((col, i) => opts.transformHeader!(col, i))\n    : columns;\n\n  let rows: Record<string, unknown>[] = parsed.map((row) => {\n    const obj: Record<string, unknown> = {};\n    columns.forEach((col, i) => {\n      let value: unknown = row[col] ?? '';\n      if (opts.dynamicTyping && typeof value === 'string') {\n        value = dynamicTypeConvert(value);\n      }\n      const key = headers[i];\n      if (key !== undefined) {\n        obj[key] = value;\n      }\n    });\n    return obj;\n  });\n\n  if (opts.skipEmptyLines) {\n    rows = rows.filter((row) =>\n      Object.values(row).some((v) => v !== '' && v !== null && v !== undefined)\n    );\n  }\n\n  return rows as T[];\n}\n\n/**\n * Parse CSV string into array of arrays without treating first row as headers\n * @param csv - CSV string to parse\n * @param options - Optional parse configuration\n * @returns Array of arrays representing rows\n * @throws Error if parsing fails\n */\nexport function parseCsvArray(\n  csv: string,\n  options?: Partial<CsvParseOptions>\n): string[][] {\n  if (options?.maxSize !== undefined && csv.length > options.maxSize) {\n    throw new Error(\n      `Input exceeds maximum allowed size: ${csv.length} bytes exceeds limit of ${options.maxSize} bytes`\n    );\n  }\n\n  const opts = { ...DEFAULT_PARSE_ARRAY_OPTIONS, ...options };\n  const trimmed = csv.trim();\n\n  validateQuoting(trimmed);\n\n  const dsv = dsvFormat(opts.delimiter ?? ',');\n  let rows = dsv.parseRows(trimmed);\n\n  if (opts.skipEmptyLines) {\n    rows = rows.filter((row) => !(row.length === 1 && row[0] === ''));\n  }\n\n  return rows;\n}\n\n/**\n * Build CSV string from array of objects\n *\n * SECURITY: Set sanitize=true when data may contain user-controlled content\n * to prevent CSV formula injection attacks in Excel/LibreOffice.\n *\n * @param data - Array of objects to convert to CSV\n * @param options - Optional build configuration and sanitize flag\n * @returns CSV string\n */\nexport function buildCsv<T = Record<string, unknown>>(\n  data: T[],\n  options?: Partial<CsvBuildOptions> & { sanitize?: boolean }\n): string {\n  const { sanitize, ...buildOpts } = options || {};\n  const opts = { ...DEFAULT_BUILD_OPTIONS, ...buildOpts };\n\n  if (data.length === 0) return '';\n\n  let processedData = data;\n  if (sanitize) {\n    processedData = data.map((row) =>\n      sanitizeCsvObject(row as Record<string, unknown>)\n    ) as T[];\n  }\n\n  const dsv = dsvFormat(opts.delimiter ?? ',');\n  let result: string;\n\n  if (opts.header === false) {\n    const rows = processedData.map((row) =>\n      Object.values(row as Record<string, unknown>).map(String)\n    );\n    result = dsv.formatRows(rows);\n  } else {\n    result = dsv.format(processedData as Record<string, unknown>[]);\n  }\n\n  result = quoteLeadingWhitespace(result, dsv, opts.delimiter ?? ',');\n  result = terminateFinalRecord(result);\n\n  if (opts.newline && opts.newline !== '\\n') {\n    result = result.replace(/\\n/g, opts.newline);\n  }\n\n  return result;\n}\n\n/**\n * Quote any field Go's encoding/csv would quote and d3-dsv would not.\n *\n * d3-dsv quotes only for the delimiter, a quote, or a newline. Go additionally\n * quotes when the field's FIRST rune is Unicode whitespace — so \"  padded  \"\n * round-trips through a parser that trims — and quotes the literal field `\\.`,\n * which some dialects treat as end-of-data. Trailing whitespace alone triggers\n * neither language. Without this a TS CSV differs from its Go twin on any such\n * value: the same class of split terminateFinalRecord exists to close.\n *\n * ONE predicate decides, and it is the same one Go uses. An earlier version\n * tested [ \\t] to skip the re-parse cheaply and \\s to decide, so a field led by\n * U+00A0 or U+2003 exited before the decision ever ran.\n *\n * Re-parses rather than intercepting the writer because d3-dsv exposes no\n * per-field hook on format(); the parse is over output this function just\n * produced, so it cannot fail on unbalanced quotes.\n */\nfunction quoteLeadingWhitespace(csv: string, dsv: DSV, delimiter: string): string {\n  return formatRowsGoCompatible(dsv.parseRows(csv), dsv, delimiter);\n}\n\n/** The one writer both public builders go through, so a field cannot come out\n * quoted from one and bare from the other. */\nfunction formatRowsGoCompatible(rows: string[][], dsv: DSV, delimiter: string): string {\n  return rows.map((row) => row.map((field) => requote(field, dsv)).join(delimiter)).join('\\n');\n}\n\n/**\n * Go's encoding/csv fieldNeedsQuotes, minus the conditions d3-dsv already\n * covers: a leading Unicode space, or the literal `\\.`.\n *\n * The class is Go's unicode.IsSpace, spelled out rather than borrowed from\n * JavaScript's \\s, which is not the same set: \\s omits U+0085 (NEL) and adds\n * U+FEFF, which Unicode 4.0.1 removed from White_Space. Borrowing \\s left a\n * field led by U+0085 unquoted here but quoted in Go, and the reverse for\n * U+FEFF.\n */\nconst GO_LEADING_SPACE = /^[\\t\\n\\v\\f\\r \\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]/;\n\nfunction goWouldQuote(field: string): boolean {\n  return field === '\\\\.' || GO_LEADING_SPACE.test(field);\n}\n\n/** One field, formatted by d3-dsv, then quoted if Go would quote it and d3-dsv did not. */\nfunction requote(field: string, dsv: DSV): string {\n  const formatted = dsv.formatValue(field);\n  if (formatted.startsWith('\"') || !goWouldQuote(field)) {\n    return formatted;\n  }\n  return `\"${field.replace(/\"/g, '\"\"')}\"`;\n}\n\n/**\n * Terminate the final record with a newline. d3-dsv leaves it off, but Go's\n * encoding/csv (which the Go converters use) always writes it, so without this\n * every TS CSV would differ from its Go twin by exactly one trailing byte.\n * Applied before the newline substitution so a \\r\\n dialect gets it too.\n */\nfunction terminateFinalRecord(csv: string): string {\n  return csv.endsWith('\\n') ? csv : `${csv}\\n`;\n}\n\n/**\n * Build CSV string from array of arrays\n *\n * SECURITY: Set sanitize=true when data may contain user-controlled content\n * to prevent CSV formula injection attacks in Excel/LibreOffice.\n *\n * @param data - Array of arrays to convert to CSV\n * @param options - Optional build configuration and sanitize flag\n * @returns CSV string\n */\nexport function buildCsvArray(\n  data: string[][],\n  options?: Partial<CsvBuildOptions> & { sanitize?: boolean }\n): string {\n  const { sanitize, ...buildOpts } = options || {};\n  const opts = { ...DEFAULT_BUILD_OPTIONS, header: false, ...buildOpts };\n\n  if (data.length === 0) return '';\n\n  let processedData = data;\n  if (sanitize) {\n    processedData = data.map((row) => sanitizeCsvArray(row));\n  }\n\n  const delimiter = opts.delimiter ?? ',';\n  const dsv = dsvFormat(delimiter);\n  let result = terminateFinalRecord(formatRowsGoCompatible(processedData, dsv, delimiter));\n\n  if (opts.newline && opts.newline !== '\\n') {\n    result = result.replace(/\\n/g, opts.newline);\n  }\n\n  return result;\n}\n\n/**\n * Validate CSV format\n * @param csv - CSV string to validate\n * @returns True if valid CSV, false otherwise\n */\nexport function isValidCsv(csv: string): boolean {\n  if (!csv || csv.trim().length === 0) return false;\n\n  const trimmed = csv.trim();\n\n  // CSV must have at least one delimiter (comma) to be considered CSV structure\n  if (!trimmed.includes(',')) return false;\n\n  try {\n    validateQuoting(trimmed);\n  } catch {\n    return false;\n  }\n\n  return true;\n}\n\n/**\n * Sanitize a single CSV value to prevent formula injection\n *\n * Prefixes values starting with =, +, -, @, |, or % with a single quote\n * to prevent Excel/LibreOffice from interpreting them as formulas.\n *\n * @param value - Value to sanitize\n * @returns Sanitized value\n */\nexport function sanitizeCsvValue(value: unknown): string {\n  const str = String(value);\n  // Check if string starts with formula trigger characters\n  if (/^[=+\\-@|%]/.test(str)) {\n    return `'${str}`;\n  }\n  return str;\n}\n\n/**\n * Sanitize all values in an array to prevent formula injection\n *\n * @param values - Array of values to sanitize\n * @returns Array with sanitized values\n */\nexport function sanitizeCsvArray(values: unknown[]): string[] {\n  return values.map(sanitizeCsvValue);\n}\n\n/**\n * Sanitize all values in an object to prevent formula injection\n *\n * @param obj - Object with values to sanitize\n * @returns New object with sanitized values\n */\nexport function sanitizeCsvObject<T extends Record<string, unknown>>(\n  obj: T\n): Record<string, string> {\n  const sanitized: Record<string, string> = {};\n  for (const [key, value] of Object.entries(obj)) {\n    sanitized[key] = sanitizeCsvValue(value);\n  }\n  return sanitized;\n}\n"],"mappings":"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"}

package/dist/index-i4P63h9e.d.ts

@@ -0,0 +1,83 @@
+//#region src/json/canonical.d.ts
+/**
+ * Canonical JSON — the encoding HDF uses for content-addressed checksums, such
+ * as the amendment chain's `previousChecksum`.
+ *
+ * The form is Go's `encoding/json` object encoding of the value's JSON shape:
+ *
+ * - object keys sorted by UTF-8 byte order;
+ * - `<`, `>`, `&`, U+2028 and U+2029 escaped;
+ * - keys whose value is `null` removed, so a document that spells an absent
+ *   optional field as an explicit null hashes the same as one that omits it;
+ * - unpaired surrogates replaced with U+FFFD, in keys and string values alike,
+ *   because Go's `json.Unmarshal` substitutes them at parse time while JS's
+ *   `JSON.parse` preserves them — without this the two disagree on any string
+ *   carrying a truncated UTF-16 sequence;
+ * - negative zero emitted as `-0`, which `JSON.stringify` renders as `0`;
+ * - NaN and Infinity rejected, as Go's encoder rejects them.
+ *
+ * Every one of those points is a place the two languages would otherwise
+ * diverge, and a divergence means a chain written by one is reported as
+ * tampered by the other. The Go counterpart is `hdfutil.CanonicalJSON`, and the
+ * two are pinned against shared vectors in
+ * `hdf-utilities/testdata/canonical-json-vectors.json`.
+ */
+/** Returns the canonical JSON encoding of a value. */
+declare function canonicalJson(value: unknown): string;
+/** Returns the hex-encoded SHA-256 of a value's canonical JSON encoding. */
+declare function canonicalChecksum(value: unknown): Promise<string>;
+//#endregion
+//#region src/json/index.d.ts
+/**
+ * Options for JSON stringification
+ */
+interface StringifyOptions {
+  /** Enable pretty printing with indentation */
+  pretty?: boolean;
+  /** Number of spaces for indentation (default: 2) */
+  indent?: number;
+}
+/**
+ * Safely parse a JSON string
+ * @param input - JSON string to parse
+ * @returns Parsed JSON value
+ * @throws Error if input is not valid JSON
+ */
+declare function parseJSON<T = unknown>(input: string): T;
+/**
+ * Safely stringify a value to JSON
+ * @param value - Value to stringify
+ * @param options - Stringification options
+ * @returns JSON string
+ * @throws Error if value contains circular references or cannot be stringified
+ */
+declare function stringifyJSON(value: unknown, options?: StringifyOptions): string;
+/**
+ * Check if a string is valid JSON
+ * @param input - String to validate
+ * @returns true if input is valid JSON, false otherwise
+ */
+declare function isValidJSON(input: unknown): boolean;
+/**
+ * Render a FINITE JSON number as text the way Go's
+ * strconv.FormatFloat(v, 'f', -1, 64) does: shortest round-trip digits,
+ * positional always, never exponent notation.
+ *
+ * JavaScript's own Number-to-string switches to exponent at and above 1e21 and
+ * below 1e-6, and drops the sign of negative zero, so a converter that emits
+ * String(n) diverges from its Go peer at both magnitude extremes and at -0.
+ * Expansion works on the digit string rather than toFixed, which caps at 100
+ * fraction digits and so cannot render the smallest denormals at all.
+ *
+ * Non-finite values are passed through as JavaScript renders them and do NOT
+ * match Go: this returns "Infinity"/"-Infinity" where FormatFloat returns
+ * "+Inf"/"-Inf" ("NaN" agrees). JSON has no literal for any of them, but
+ * JSON.parse manufactures Infinity from an overflow literal such as 1e400, so
+ * the case is reachable. The Go peer never renders that value at all -- its
+ * ParseFloat fails and it emits the original token text instead -- which is a
+ * documented cross-language divergence, not something this helper can close.
+ */
+declare function formatJsonNumber(value: number): string;
+//#endregion
+export { stringifyJSON as a, parseJSON as i, formatJsonNumber as n, canonicalChecksum as o, isValidJSON as r, canonicalJson as s, StringifyOptions as t };
+//# sourceMappingURL=index-i4P63h9e.d.ts.map

package/dist/index-i4P63h9e.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-i4P63h9e.d.ts","names":[],"sources":["../src/json/canonical.ts","../src/json/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;iBAkIgB,cAAc;;iBAKR,kBAAkB,iBAAiB;;;;;;UCjIxC;;EAEf;;EAEA;;;;;;;;iBASc,UAAU,aAAa,gBAAgB;;;;;;;;iBAuBvC,cAAc,gBAAgB,UAAS;;;;;;iBAkBvC,YAAY;;;;;;;;;;;;;;;;;;;;iBAoCZ,iBAAiB"}

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { extractColumn, findRows, findValuesByKey } from "./object/index.js";
 import { CsvBuildOptions, CsvParseOptions, buildCsv, buildCsvArray, isValidCsv, parseCsv, parseCsvArray, sanitizeCsvArray, sanitizeCsvObject, sanitizeCsvValue } from "./csv/index.js";
 import { HashAlgorithm, HashEncoding, HashOptions, generateHash, hashObject, sha256, sha512, verifyHash } from "./hash/index.js";
-import { StringifyOptions, isValidJSON, parseJSON, stringifyJSON } from "./json/index.js";
-import { buildXml, extractTextFromXml, isValidXml, parseXml, parseXmlWithArrays } from "./xml/index.js";
-import { formatTimestamp, formatTimestampSeconds, normalizeHdfTimestamps, parseTimestamp, replaceHtmlTags, stripHtml, trimUtcFraction } from "./string/index.js";
+import { a as stringifyJSON, i as parseJSON, n as formatJsonNumber, o as canonicalChecksum, r as isValidJSON, s as canonicalJson, t as StringifyOptions } from "./index-i4P63h9e.js";
+import { buildXml, extractTextFromXml, isValidXml, isXmlChar, parseXml, parseXmlWithArrays, xmlSafeText } from "./xml/index.js";
+import { encodeBase64Utf8, formatTimestamp, formatTimestampSeconds, normalizeHdfTimestamps, parseTimestamp, replaceHtmlTags, stripHtml, trimUtcFraction } from "./string/index.js";
 //#region src/severity/index.d.ts
 /**
  * Severity-to-impact mapping utilities.
@@ -385,5 +385,5 @@ declare const DEFAULT_MAX_INPUT_SIZE: number;
  */
 declare function validateInputSize(input: string | Uint8Array, maxSize?: number): void;
 //#endregion
-export { type CpePart, type CsvBuildOptions, type CsvParseOptions, type CvssScore, type CvssValidationResult, DEFAULT_MAX_INPUT_SIZE, type EffectiveStatusInput, type HashAlgorithm, type HashEncoding, type HashOptions, type ParsedCpe, type ParsedCvssVector, type ParsedPurl, STATUS_SEVERITY_ORDER, type StatusOverrideInput, type StatusSeverity, type StringifyOptions, buildCsv, buildCsvArray, buildXml, computeCvss40Score, computeCvssScore, computeEffectiveStatus, cvss40MacroVector, cvssScoreToSeverity, extractColumn, extractColumn as extractCsvColumn, extractTextFromXml, findRows as findCsvRows, findRows, findValuesByKey as findJsonValues, findValuesByKey, findValuesByKey as findXmlValues, formatTimestamp, formatTimestampSeconds, generateHash, governingOverrideIndex, governingStatusOverride, governingStatusOverrideIndex, hashObject, impactToSeverity, isUnratedSeverity, isValidCsv, isValidJSON, isValidXml, normalizeHdfTimestamps, parseCpe, parseCsv, parseCsvArray, parseCvssVector, parseJSON, parsePurl, parseTimestamp, parseXml, parseXmlWithArrays, replaceHtmlTags, roundImpact, sanitizeCsvArray, sanitizeCsvObject, sanitizeCsvValue, severityToImpact, severityToImpactWithAliases, sha256, sha512, statusRank, stringifyJSON, stripHtml, trimUtcFraction, validateCvssVector, validateInputSize, verifyHash, worstStatus };
+export { type CpePart, type CsvBuildOptions, type CsvParseOptions, type CvssScore, type CvssValidationResult, DEFAULT_MAX_INPUT_SIZE, type EffectiveStatusInput, type HashAlgorithm, type HashEncoding, type HashOptions, type ParsedCpe, type ParsedCvssVector, type ParsedPurl, STATUS_SEVERITY_ORDER, type StatusOverrideInput, type StatusSeverity, type StringifyOptions, buildCsv, buildCsvArray, buildXml, canonicalChecksum, canonicalJson, computeCvss40Score, computeCvssScore, computeEffectiveStatus, cvss40MacroVector, cvssScoreToSeverity, encodeBase64Utf8, extractColumn, extractColumn as extractCsvColumn, extractTextFromXml, findRows as findCsvRows, findRows, findValuesByKey as findJsonValues, findValuesByKey, findValuesByKey as findXmlValues, formatJsonNumber, formatTimestamp, formatTimestampSeconds, generateHash, governingOverrideIndex, governingStatusOverride, governingStatusOverrideIndex, hashObject, impactToSeverity, isUnratedSeverity, isValidCsv, isValidJSON, isValidXml, isXmlChar, normalizeHdfTimestamps, parseCpe, parseCsv, parseCsvArray, parseCvssVector, parseJSON, parsePurl, parseTimestamp, parseXml, parseXmlWithArrays, replaceHtmlTags, roundImpact, sanitizeCsvArray, sanitizeCsvObject, sanitizeCsvValue, severityToImpact, severityToImpactWithAliases, sha256, sha512, statusRank, stringifyJSON, stripHtml, trimUtcFraction, validateCvssVector, validateInputSize, verifyHash, worstStatus, xmlSafeText };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,9 +1,9 @@
+import { a as canonicalChecksum, i as stringifyJSON, n as isValidJSON, o as canonicalJson, r as parseJSON, t as formatJsonNumber } from "./json-DdbPTX2g.js";
 import { extractColumn, findRows, findValuesByKey } from "./object/index.js";
-import { isValidJSON, parseJSON, stringifyJSON } from "./json/index.js";
 import { generateHash, hashObject, sha256, sha512, verifyHash } from "./hash/index.js";
-import { buildXml, extractTextFromXml, isValidXml, parseXml, parseXmlWithArrays } from "./xml/index.js";
+import { buildXml, extractTextFromXml, isValidXml, isXmlChar, parseXml, parseXmlWithArrays, xmlSafeText } from "./xml/index.js";
 import { buildCsv, buildCsvArray, isValidCsv, parseCsv, parseCsvArray, sanitizeCsvArray, sanitizeCsvObject, sanitizeCsvValue } from "./csv/index.js";
-import { formatTimestamp, formatTimestampSeconds, normalizeHdfTimestamps, parseTimestamp, replaceHtmlTags, stripHtml, trimUtcFraction } from "./string/index.js";
+import { encodeBase64Utf8, formatTimestamp, formatTimestampSeconds, normalizeHdfTimestamps, parseTimestamp, replaceHtmlTags, stripHtml, trimUtcFraction } from "./string/index.js";
 //#region src/severity/index.ts
 /**
 * Severity-to-impact mapping utilities.
@@ -1808,10 +1808,37 @@ const DEFAULT_MAX_INPUT_SIZE = 50 * 1024 * 1024;
 */
 function validateInputSize(input, maxSize = 0) {
 	const limit = maxSize > 0 ? maxSize : DEFAULT_MAX_INPUT_SIZE;
-	const len = typeof input === "string" ? new TextEncoder().encode(input).length : input.length;
-	if (len > limit) throw new Error(`input exceeds maximum allowed size of ${limit} bytes (${len} bytes provided)`);
+	if (typeof input !== "string") {
+		if (input.length > limit) throw tooLarge(limit, input.length);
+		return;
+	}
+	if (input.length * 3 <= limit) return;
+	const len = utf8ByteLength(input);
+	if (len > limit) throw tooLarge(limit, len);
+}
+function tooLarge(limit, len) {
+	return /* @__PURE__ */ new Error(`input exceeds maximum allowed size of ${limit} bytes (${len} bytes provided)`);
+}
+/**
+* UTF-8 byte length, counted rather than encoded: a TextEncoder pass would
+* allocate a full copy of the very input this guard exists to reject.
+* An unpaired surrogate counts as the three-byte replacement character, which
+* is what TextEncoder emits for one.
+*/
+function utf8ByteLength(s) {
+	let bytes = 0;
+	for (let i = 0; i < s.length; i++) {
+		const c = s.charCodeAt(i);
+		if (c < 128) bytes += 1;
+		else if (c < 2048) bytes += 2;
+		else if (c >= 55296 && c <= 56319 && (s.charCodeAt(i + 1) & 64512) === 56320) {
+			bytes += 4;
+			i++;
+		} else bytes += 3;
+	}
+	return bytes;
 }
 //#endregion
-export { DEFAULT_MAX_INPUT_SIZE, STATUS_SEVERITY_ORDER, buildCsv, buildCsvArray, buildXml, computeCvss40Score, computeCvssScore, computeEffectiveStatus, cvss40MacroVector, cvssScoreToSeverity, extractColumn, extractColumn as extractCsvColumn, extractTextFromXml, findRows as findCsvRows, findRows, findValuesByKey as findJsonValues, findValuesByKey, findValuesByKey as findXmlValues, formatTimestamp, formatTimestampSeconds, generateHash, governingOverrideIndex, governingStatusOverride, governingStatusOverrideIndex, hashObject, impactToSeverity, isUnratedSeverity, isValidCsv, isValidJSON, isValidXml, normalizeHdfTimestamps, parseCpe, parseCsv, parseCsvArray, parseCvssVector, parseJSON, parsePurl, parseTimestamp, parseXml, parseXmlWithArrays, replaceHtmlTags, roundImpact, sanitizeCsvArray, sanitizeCsvObject, sanitizeCsvValue, severityToImpact, severityToImpactWithAliases, sha256, sha512, statusRank, stringifyJSON, stripHtml, trimUtcFraction, validateCvssVector, validateInputSize, verifyHash, worstStatus };
+export { DEFAULT_MAX_INPUT_SIZE, STATUS_SEVERITY_ORDER, buildCsv, buildCsvArray, buildXml, canonicalChecksum, canonicalJson, computeCvss40Score, computeCvssScore, computeEffectiveStatus, cvss40MacroVector, cvssScoreToSeverity, encodeBase64Utf8, extractColumn, extractColumn as extractCsvColumn, extractTextFromXml, findRows as findCsvRows, findRows, findValuesByKey as findJsonValues, findValuesByKey, findValuesByKey as findXmlValues, formatJsonNumber, formatTimestamp, formatTimestampSeconds, generateHash, governingOverrideIndex, governingStatusOverride, governingStatusOverrideIndex, hashObject, impactToSeverity, isUnratedSeverity, isValidCsv, isValidJSON, isValidXml, isXmlChar, normalizeHdfTimestamps, parseCpe, parseCsv, parseCsvArray, parseCvssVector, parseJSON, parsePurl, parseTimestamp, parseXml, parseXmlWithArrays, replaceHtmlTags, roundImpact, sanitizeCsvArray, sanitizeCsvObject, sanitizeCsvValue, severityToImpact, severityToImpactWithAliases, sha256, sha512, statusRank, stringifyJSON, stripHtml, trimUtcFraction, validateCvssVector, validateInputSize, verifyHash, worstStatus, xmlSafeText };
 
 //# sourceMappingURL=index.js.map