@mitre/hdf-utilities 3.6.0-rc.1 → 3.6.0-rc.3

package/README.md

@@ -15,6 +15,37 @@ 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.
+
+`hash` and `json` have no Go counterpart because Go's standard library already
+provides them: `crypto/sha256`, `encoding/json`. Wrapping those in Go would add a
+layer with no decision in it. The TypeScript side needs wrappers because
+JavaScript ships no equivalent, and the wrapper is where safe defaults get
+centralised.
+
+`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;;;;;;;;;;;;iBA0GzB,cACd,kBACA,UAAU,QAAQ;EAAqB;;;;;;;iBA2BzB,WAAW;;;;;;;;;;iBA0BX,iBAAiB;;;;;;;iBAejB,iBAAiB;;;;;;;iBAUjB,kBAAkB,UAAU,yBAC1C,KAAK,IACJ"}

package/dist/csv/index.js

@@ -129,11 +129,53 @@ 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 dsv.parseRows(csv).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.

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 dsv\n    .parseRows(csv)\n    .map((row) => row.map((field) => requote(field, dsv)).join(delimiter))\n    .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 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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"}

package/dist/index-b6zg3fBr.d.ts

@@ -0,0 +1,63 @@
+//#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;
+//#endregion
+export { canonicalChecksum as a, stringifyJSON as i, isValidJSON as n, canonicalJson as o, parseJSON as r, StringifyOptions as t };
+//# sourceMappingURL=index-b6zg3fBr.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-b6zg3fBr.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"}

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 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 { a as canonicalChecksum, i as stringifyJSON, n as isValidJSON, o as canonicalJson, r as parseJSON, t as StringifyOptions } from "./index-b6zg3fBr.js";
+import { buildXml, extractTextFromXml, isValidXml, isXmlChar, parseXml, parseXmlWithArrays, xmlSafeText } from "./xml/index.js";
 import { formatTimestamp, formatTimestampSeconds, normalizeHdfTimestamps, parseTimestamp, replaceHtmlTags, stripHtml, trimUtcFraction } from "./string/index.js";
 //#region src/severity/index.d.ts
 /**
@@ -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, 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, 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,7 +1,7 @@
+import { a as canonicalJson, i as canonicalChecksum, n as parseJSON, r as stringifyJSON, t as isValidJSON } from "./json-DIcA65Nf.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";
 //#region src/severity/index.ts
@@ -1812,6 +1812,6 @@ function validateInputSize(input, maxSize = 0) {
 	if (len > limit) throw new Error(`input exceeds maximum allowed size of ${limit} bytes (${len} bytes provided)`);
 }
 //#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, 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, 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

package/dist/json/index.d.ts

@@ -1,35 +1,3 @@
 import { findValuesByKey } from "../object/index.js";
-//#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;
-//#endregion
-export { StringifyOptions, findValuesByKey as findJsonValues, isValidJSON, parseJSON, stringifyJSON };
-//# sourceMappingURL=index.d.ts.map
+import { a as canonicalChecksum, i as stringifyJSON, n as isValidJSON, o as canonicalJson, r as parseJSON, t as StringifyOptions } from "../index-b6zg3fBr.js";
+export { StringifyOptions, canonicalChecksum, canonicalJson, findValuesByKey as findJsonValues, isValidJSON, parseJSON, stringifyJSON };

package/dist/json/index.js

@@ -1,52 +1,3 @@
+import { a as canonicalJson, i as canonicalChecksum, n as parseJSON, r as stringifyJSON, t as isValidJSON } from "../json-DIcA65Nf.js";
 import { findValuesByKey } from "../object/index.js";
-//#region src/json/index.ts
-/**
-* Safely parse a JSON string
-* @param input - JSON string to parse
-* @returns Parsed JSON value
-* @throws Error if input is not valid JSON
-*/
-function parseJSON(input) {
-	if (typeof input !== "string") throw new Error("Input must be a string");
-	if (input.trim() === "") throw new Error("Input cannot be empty");
-	try {
-		return JSON.parse(input);
-	} catch (error) {
-		throw new Error(`Invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
-	}
-}
-/**
-* 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
-*/
-function stringifyJSON(value, options = {}) {
-	const { pretty = false, indent = 2 } = options;
-	try {
-		if (pretty) return JSON.stringify(value, null, indent);
-		return JSON.stringify(value);
-	} catch (error) {
-		throw new Error(`Failed to stringify JSON: ${error instanceof Error ? error.message : String(error)}`);
-	}
-}
-/**
-* Check if a string is valid JSON
-* @param input - String to validate
-* @returns true if input is valid JSON, false otherwise
-*/
-function isValidJSON(input) {
-	if (typeof input !== "string") return false;
-	if (input.trim() === "") return false;
-	try {
-		JSON.parse(input);
-		return true;
-	} catch {
-		return false;
-	}
-}
-//#endregion
-export { findValuesByKey as findJsonValues, isValidJSON, parseJSON, stringifyJSON };
-
-//# sourceMappingURL=index.js.map
+export { canonicalChecksum, canonicalJson, findValuesByKey as findJsonValues, isValidJSON, parseJSON, stringifyJSON };

package/dist/json-DIcA65Nf.js

@@ -0,0 +1,156 @@
+//#region src/json/canonical.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`.
+*/
+const LINE_SEPARATOR = "\u2028";
+const PARAGRAPH_SEPARATOR = "\u2029";
+/** Characters Go's encoder escapes that `JSON.stringify` leaves literal. */
+const GO_ESCAPES = {
+	"<": "\\u003c",
+	">": "\\u003e",
+	"&": "\\u0026",
+	[LINE_SEPARATOR]: "\\u2028",
+	[PARAGRAPH_SEPARATOR]: "\\u2029"
+};
+const GO_ESCAPE_PATTERN = /[<>&\u2028\u2029]/g;
+/** An unpaired high or low surrogate — a truncated UTF-16 sequence. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+const utf8 = new TextEncoder();
+/**
+* Compares two keys by their UTF-8 bytes, which is how Go orders map keys.
+* `Array.prototype.sort` compares UTF-16 code units instead, and the two
+* disagree for characters outside the BMP.
+*/
+function compareUtf8(a, b) {
+	const left = utf8.encode(a);
+	const right = utf8.encode(b);
+	const shared = Math.min(left.length, right.length);
+	for (let i = 0; i < shared; i++) {
+		const leftByte = left[i] ?? 0;
+		const rightByte = right[i] ?? 0;
+		if (leftByte !== rightByte) return leftByte - rightByte;
+	}
+	return left.length - right.length;
+}
+/**
+* Replaces unpaired surrogates with U+FFFD, matching what Go's `json.Unmarshal`
+* does when it decodes the same bytes. Applied to keys as well as values, and
+* before sorting, so a key that normalizes onto an existing one collides the
+* same way it would in a Go map (last occurrence wins).
+*/
+function replaceLoneSurrogates(value) {
+	return value.replace(LONE_SURROGATE, "�");
+}
+/**
+* Normalizes a value into the shape that gets hashed. This replaces a
+* `JSON.parse(JSON.stringify(...))` round-trip, which would have been simpler
+* but silently destroys negative zero.
+*/
+function normalize(value) {
+	if (value === null || value === void 0) return value;
+	if (typeof value === "object") {
+		const withToJson = value;
+		if (typeof withToJson.toJSON === "function") return normalize(withToJson.toJSON());
+		if (Array.isArray(value)) return value.map((element) => element === void 0 ? null : normalize(element));
+		const out = {};
+		for (const [key, nested] of Object.entries(value)) {
+			if (nested === null || nested === void 0) continue;
+			out[replaceLoneSurrogates(key)] = normalize(nested);
+		}
+		return out;
+	}
+	if (typeof value === "string") return replaceLoneSurrogates(value);
+	if (typeof value === "number" && !Number.isFinite(value)) throw new TypeError(`value is not JSON-encodable: ${String(value)}`);
+	return value;
+}
+/** Serializes with object keys in UTF-8 byte order at every level. */
+function serialize(value) {
+	if (Array.isArray(value)) return `[${value.map(serialize).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.keys(value).sort(compareUtf8).map((key) => `${serialize(key)}:${serialize(value[key])}`).join(",")}}`;
+	if (typeof value === "number" && Object.is(value, -0)) return "-0";
+	const encoded = JSON.stringify(value);
+	if (encoded === void 0) throw new TypeError("value is not JSON-encodable");
+	return encoded.replace(GO_ESCAPE_PATTERN, (c) => GO_ESCAPES[c] ?? c);
+}
+/** Returns the canonical JSON encoding of a value. */
+function canonicalJson(value) {
+	return serialize(normalize(value ?? null));
+}
+/** Returns the hex-encoded SHA-256 of a value's canonical JSON encoding. */
+async function canonicalChecksum(value) {
+	const bytes = utf8.encode(canonicalJson(value));
+	const digest = await crypto.subtle.digest("SHA-256", bytes);
+	return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+//#endregion
+//#region src/json/index.ts
+/**
+* Safely parse a JSON string
+* @param input - JSON string to parse
+* @returns Parsed JSON value
+* @throws Error if input is not valid JSON
+*/
+function parseJSON(input) {
+	if (typeof input !== "string") throw new Error("Input must be a string");
+	if (input.trim() === "") throw new Error("Input cannot be empty");
+	try {
+		return JSON.parse(input);
+	} catch (error) {
+		throw new Error(`Invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* 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
+*/
+function stringifyJSON(value, options = {}) {
+	const { pretty = false, indent = 2 } = options;
+	try {
+		if (pretty) return JSON.stringify(value, null, indent);
+		return JSON.stringify(value);
+	} catch (error) {
+		throw new Error(`Failed to stringify JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Check if a string is valid JSON
+* @param input - String to validate
+* @returns true if input is valid JSON, false otherwise
+*/
+function isValidJSON(input) {
+	if (typeof input !== "string") return false;
+	if (input.trim() === "") return false;
+	try {
+		JSON.parse(input);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { canonicalJson as a, canonicalChecksum as i, parseJSON as n, stringifyJSON as r, isValidJSON as t };
+
+//# sourceMappingURL=json-DIcA65Nf.js.map

package/dist/json-DIcA65Nf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-DIcA65Nf.js","names":[],"sources":["../src/json/canonical.ts","../src/json/index.ts"],"sourcesContent":["/**\n * Canonical JSON — the encoding HDF uses for content-addressed checksums, such\n * as the amendment chain's `previousChecksum`.\n *\n * The form is Go's `encoding/json` object encoding of the value's JSON shape:\n *\n * - object keys sorted by UTF-8 byte order;\n * - `<`, `>`, `&`, U+2028 and U+2029 escaped;\n * - keys whose value is `null` removed, so a document that spells an absent\n *   optional field as an explicit null hashes the same as one that omits it;\n * - unpaired surrogates replaced with U+FFFD, in keys and string values alike,\n *   because Go's `json.Unmarshal` substitutes them at parse time while JS's\n *   `JSON.parse` preserves them — without this the two disagree on any string\n *   carrying a truncated UTF-16 sequence;\n * - negative zero emitted as `-0`, which `JSON.stringify` renders as `0`;\n * - NaN and Infinity rejected, as Go's encoder rejects them.\n *\n * Every one of those points is a place the two languages would otherwise\n * diverge, and a divergence means a chain written by one is reported as\n * tampered by the other. The Go counterpart is `hdfutil.CanonicalJSON`, and the\n * two are pinned against shared vectors in\n * `hdf-utilities/testdata/canonical-json-vectors.json`.\n */\n\nconst LINE_SEPARATOR = '\\u2028';\nconst PARAGRAPH_SEPARATOR = '\\u2029';\n\n/** Characters Go's encoder escapes that `JSON.stringify` leaves literal. */\nconst GO_ESCAPES: Record<string, string> = {\n  '<': '\\\\u003c',\n  '>': '\\\\u003e',\n  '&': '\\\\u0026',\n  [LINE_SEPARATOR]: '\\\\u2028',\n  [PARAGRAPH_SEPARATOR]: '\\\\u2029',\n};\n\nconst GO_ESCAPE_PATTERN = /[<>&\\u2028\\u2029]/g;\n\n/** An unpaired high or low surrogate — a truncated UTF-16 sequence. */\nconst LONE_SURROGATE = /[\\uD800-\\uDBFF](?![\\uDC00-\\uDFFF])|(?<![\\uD800-\\uDBFF])[\\uDC00-\\uDFFF]/g;\n\nconst utf8 = new TextEncoder();\n\n/**\n * Compares two keys by their UTF-8 bytes, which is how Go orders map keys.\n * `Array.prototype.sort` compares UTF-16 code units instead, and the two\n * disagree for characters outside the BMP.\n */\nfunction compareUtf8(a: string, b: string): number {\n  const left = utf8.encode(a);\n  const right = utf8.encode(b);\n  const shared = Math.min(left.length, right.length);\n  for (let i = 0; i < shared; i++) {\n    // Indices below the shared length are always present; the fallbacks keep\n    // this total for the type checker without asserting.\n    const leftByte = left[i] ?? 0;\n    const rightByte = right[i] ?? 0;\n    if (leftByte !== rightByte) return leftByte - rightByte;\n  }\n  return left.length - right.length;\n}\n\n/**\n * Replaces unpaired surrogates with U+FFFD, matching what Go's `json.Unmarshal`\n * does when it decodes the same bytes. Applied to keys as well as values, and\n * before sorting, so a key that normalizes onto an existing one collides the\n * same way it would in a Go map (last occurrence wins).\n */\nfunction replaceLoneSurrogates(value: string): string {\n  return value.replace(LONE_SURROGATE, '\\uFFFD');\n}\n\n/**\n * Normalizes a value into the shape that gets hashed. This replaces a\n * `JSON.parse(JSON.stringify(...))` round-trip, which would have been simpler\n * but silently destroys negative zero.\n */\nfunction normalize(value: unknown): unknown {\n  if (value === null || value === undefined) return value;\n\n  if (typeof value === 'object') {\n    const withToJson = value as { toJSON?: () => unknown };\n    // Dates and anything else that defines toJSON serialize through it, exactly\n    // as JSON.stringify would.\n    if (typeof withToJson.toJSON === 'function') return normalize(withToJson.toJSON());\n\n    if (Array.isArray(value)) {\n      // JSON has no undefined: in an array position it becomes null.\n      return value.map((element) => (element === undefined ? null : normalize(element)));\n    }\n\n    const out: Record<string, unknown> = {};\n    for (const [key, nested] of Object.entries(value as Record<string, unknown>)) {\n      if (nested === null || nested === undefined) continue;\n      out[replaceLoneSurrogates(key)] = normalize(nested);\n    }\n    return out;\n  }\n\n  if (typeof value === 'string') return replaceLoneSurrogates(value);\n\n  if (typeof value === 'number' && !Number.isFinite(value)) {\n    throw new TypeError(`value is not JSON-encodable: ${String(value)}`);\n  }\n\n  return value;\n}\n\n/** Serializes with object keys in UTF-8 byte order at every level. */\nfunction serialize(value: unknown): string {\n  if (Array.isArray(value)) {\n    return `[${value.map(serialize).join(',')}]`;\n  }\n  if (value !== null && typeof value === 'object') {\n    const entries = Object.keys(value as Record<string, unknown>)\n      .sort(compareUtf8)\n      .map((key) => `${serialize(key)}:${serialize((value as Record<string, unknown>)[key])}`);\n    return `{${entries.join(',')}}`;\n  }\n  // Go distinguishes negative zero; JSON.stringify renders it as \"0\".\n  if (typeof value === 'number' && Object.is(value, -0)) return '-0';\n\n  const encoded = JSON.stringify(value);\n  if (encoded === undefined) {\n    throw new TypeError('value is not JSON-encodable');\n  }\n  return encoded.replace(GO_ESCAPE_PATTERN, (c) => GO_ESCAPES[c] ?? c);\n}\n\n/** Returns the canonical JSON encoding of a value. */\nexport function canonicalJson(value: unknown): string {\n  return serialize(normalize(value ?? null));\n}\n\n/** Returns the hex-encoded SHA-256 of a value's canonical JSON encoding. */\nexport async function canonicalChecksum(value: unknown): Promise<string> {\n  const bytes = utf8.encode(canonicalJson(value));\n  const digest = await crypto.subtle.digest('SHA-256', bytes);\n  return Array.from(new Uint8Array(digest))\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('');\n}\n","export { canonicalJson, canonicalChecksum } from './canonical.js';\nexport { findValuesByKey as findJsonValues } from '../object/index.js';\n\n/**\n * Options for JSON stringification\n */\nexport interface StringifyOptions {\n  /** Enable pretty printing with indentation */\n  pretty?: boolean;\n  /** Number of spaces for indentation (default: 2) */\n  indent?: number;\n}\n\n/**\n * Safely parse a JSON string\n * @param input - JSON string to parse\n * @returns Parsed JSON value\n * @throws Error if input is not valid JSON\n */\nexport function parseJSON<T = unknown>(input: string): T {\n  if (typeof input !== 'string') {\n    throw new Error('Input must be a string');\n  }\n\n  if (input.trim() === '') {\n    throw new Error('Input cannot be empty');\n  }\n\n  try {\n    return JSON.parse(input) as T;\n  } catch (error) {\n    throw new Error(`Invalid JSON: ${error instanceof Error ? error.message : String(error)}`);\n  }\n}\n\n/**\n * Safely stringify a value to JSON\n * @param value - Value to stringify\n * @param options - Stringification options\n * @returns JSON string\n * @throws Error if value contains circular references or cannot be stringified\n */\nexport function stringifyJSON(value: unknown, options: StringifyOptions = {}): string {\n  const { pretty = false, indent = 2 } = options;\n\n  try {\n    if (pretty) {\n      return JSON.stringify(value, null, indent);\n    }\n    return JSON.stringify(value);\n  } catch (error) {\n    throw new Error(`Failed to stringify JSON: ${error instanceof Error ? error.message : String(error)}`);\n  }\n}\n\n/**\n * Check if a string is valid JSON\n * @param input - String to validate\n * @returns true if input is valid JSON, false otherwise\n */\nexport function isValidJSON(input: unknown): boolean {\n  if (typeof input !== 'string') {\n    return false;\n  }\n\n  if (input.trim() === '') {\n    return false;\n  }\n\n  try {\n    JSON.parse(input);\n    return true;\n  } catch {\n    return false;\n  }\n}\n"],"mappings":"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"}

package/dist/xml/index.d.ts

@@ -21,7 +21,9 @@ declare function parseXml(xml: string, options?: Partial<X2jOptions> & {
 /**
  * Build XML string from JavaScript object
  *
- * @param obj - JavaScript object to convert to XML
+ * @param obj - JavaScript object to convert to XML, or a preserveOrder node list.
+ *   An array is only meaningful with `preserveOrder: true`; without it the builder
+ *   indexes the array and emits elements named by its numeric keys.
  * @param options - Optional builder configuration (merged with defaults)
  * @returns XML string
  *
@@ -32,7 +34,7 @@ declare function parseXml(xml: string, options?: Partial<X2jOptions> & {
  * // Returns formatted XML string
  * ```
  */
-declare function buildXml(obj: Record<string, unknown>, options?: Partial<XmlBuilderOptions>): string;
+declare function buildXml(obj: Record<string, unknown> | unknown[], options?: Partial<XmlBuilderOptions>): string;
 /**
  * Validate if a string is well-formed XML
  *
@@ -46,6 +48,19 @@ declare function buildXml(obj: Record<string, unknown>, options?: Partial<XmlBui
  * isValidXml('not xml'); // false
  * ```
  */
+/**
+ * Whether a character is legal in an XML 1.0 document, per the Char production.
+ * The one home for this rule: an emitter deciding what to replace and a
+ * validator deciding what to reject must not answer it differently.
+ */
+declare function isXmlChar(ch: string): boolean;
+/**
+ * Replace every character XML 1.0 forbids with U+FFFD, which is what Go's
+ * encoding/xml does. XML defines no escape for these — a numeric reference to a
+ * C0 control is itself illegal — so the choice is a replacement character or a
+ * document no conforming parser will read.
+ */
+declare function xmlSafeText(value: string): string;
 declare function isValidXml(xml: string): boolean;
 /**
  * Parse XML with array handling for repeated elements
@@ -81,5 +96,5 @@ declare function parseXmlWithArrays(xml: string, arrayTags: string[], options?:
  */
 declare function extractTextFromXml(xml: string): string;
 //#endregion
-export { buildXml, extractTextFromXml, findValuesByKey as findXmlValues, isValidXml, parseXml, parseXmlWithArrays };
+export { buildXml, extractTextFromXml, findValuesByKey as findXmlValues, isValidXml, isXmlChar, parseXml, parseXmlWithArrays, xmlSafeText };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/xml/index.ts"],"mappings":";;;;;;;;;;;;;;;;;iBAuDgB,SACd,aACA,UAAU,QAAQ;EAAgB;IACjC;;;;;;;;;;;;;;;iBAoCa,SACd,KAAK,yBACL,UAAU,QAAQ;;;;;;;;;;;;;;iBAwBJ,WAAW;;;;;;;;;;;;;;;;;iBAyBX,mBACd,aACA,qBACA,UAAU,QAAQ;EAAgB;IACjC;;;;;;;;;;;;;;iBAoCa,mBAAmB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/xml/index.ts"],"mappings":";;;;;;;;;;;;;;;;;iBAuDgB,SACd,aACA,UAAU,QAAQ;EAAgB;IACjC;;;;;;;;;;;;;;;;;iBAsCa,SACd,KAAK,qCACL,UAAU,QAAQ;;;;;;;;;;;;;;;;;;;iBA6BJ,UAAU;;;;;;;iBAkBV,YAAY;iBAMZ,WAAW;;;;;;;;;;;;;;;;;iBAgCX,mBACd,aACA,qBACA,UAAU,QAAQ;EAAgB;IACjC;;;;;;;;;;;;;;iBAoCa,mBAAmB"}

package/dist/xml/index.js

@@ -60,7 +60,9 @@ function parseXml(xml, options) {
 /**
 * Build XML string from JavaScript object
 *
-* @param obj - JavaScript object to convert to XML
+* @param obj - JavaScript object to convert to XML, or a preserveOrder node list.
+*   An array is only meaningful with `preserveOrder: true`; without it the builder
+*   indexes the array and emits elements named by its numeric keys.
 * @param options - Optional builder configuration (merged with defaults)
 * @returns XML string
 *
@@ -90,8 +92,29 @@ function buildXml(obj, options) {
 * isValidXml('not xml'); // false
 * ```
 */
+/**
+* Whether a character is legal in an XML 1.0 document, per the Char production.
+* The one home for this rule: an emitter deciding what to replace and a
+* validator deciding what to reject must not answer it differently.
+*/
+function isXmlChar(ch) {
+	const c = ch.codePointAt(0);
+	return c === 9 || c === 10 || c === 13 || c >= 32 && c <= 55295 || c >= 57344 && c <= 65533 || c >= 65536;
+}
+/**
+* Replace every character XML 1.0 forbids with U+FFFD, which is what Go's
+* encoding/xml does. XML defines no escape for these — a numeric reference to a
+* C0 control is itself illegal — so the choice is a replacement character or a
+* document no conforming parser will read.
+*/
+function xmlSafeText(value) {
+	let out = "";
+	for (const ch of value) out += isXmlChar(ch) ? ch : "�";
+	return out;
+}
 function isValidXml(xml) {
 	if (!xml || xml.trim().length === 0) return false;
+	for (const ch of xml) if (!isXmlChar(ch)) return false;
 	return XMLValidator.validate(xml) === true;
 }
 /**
@@ -152,6 +175,6 @@ function extractTextRecursive(obj) {
 	return "";
 }
 //#endregion
-export { buildXml, extractTextFromXml, findValuesByKey as findXmlValues, isValidXml, parseXml, parseXmlWithArrays };
+export { buildXml, extractTextFromXml, findValuesByKey as findXmlValues, isValidXml, isXmlChar, parseXml, parseXmlWithArrays, xmlSafeText };
 
 //# sourceMappingURL=index.js.map

package/dist/xml/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["record"],"sources":["../../src/xml/index.ts"],"sourcesContent":["/**\n * XML parsing utilities for HDF converters\n * Provides XML parsing with sensible defaults for security tool output\n */\n\nimport { XMLParser, XMLBuilder, XMLValidator } from 'fast-xml-parser';\nimport type { X2jOptions, XmlBuilderOptions } from 'fast-xml-parser';\n\nexport { findValuesByKey as findXmlValues } from '../object/index.js';\n\n/**\n * Default options for XML parsing optimized for security tool converters.\n *\n * **XXE Safety**: fast-xml-parser v5.x does not process DTD or external entities\n * by default. The `processEntities: false` option is set as defense-in-depth to\n * ensure entity expansion is disabled even if future versions change defaults.\n * See: https://github.com/NaturalIntelligence/fast-xml-parser/blob/master/docs/v5/2.XMLparseOptions.md\n */\nconst DEFAULT_PARSE_OPTIONS: Partial<X2jOptions> = {\n  attributeNamePrefix: '',\n  textNodeName: '#text',\n  ignoreAttributes: false,\n  ignoreDeclaration: true,\n  parseAttributeValue: false,\n  parseTagValue: false,\n  removeNSPrefix: true,\n  processEntities: false,\n};\n\n/**\n * Default options for XML building\n */\nconst DEFAULT_BUILD_OPTIONS: Partial<XmlBuilderOptions> = {\n  attributeNamePrefix: '',\n  textNodeName: '#text',\n  ignoreAttributes: false,\n  format: true,\n  indentBy: '  ',\n  suppressEmptyNode: false,\n};\n\n/**\n * Parse XML string to JavaScript object\n *\n * @param xml - XML string to parse\n * @param options - Optional parser configuration (merged with defaults)\n * @returns Parsed JavaScript object\n *\n * @example\n * ```typescript\n * const xmlString = '<root><item id=\"1\">Test</item></root>';\n * const result = parseXml(xmlString);\n * // Returns: { root: { item: { id: '1', '#text': 'Test' } } }\n * ```\n */\nexport function parseXml(\n  xml: string,\n  options?: Partial<X2jOptions> & { maxSize?: number }\n): Record<string, unknown> {\n  if (options?.maxSize !== undefined && xml.length > options.maxSize) {\n    throw new Error(\n      `Input exceeds maximum allowed size: ${xml.length} bytes exceeds limit of ${options.maxSize} bytes`\n    );\n  }\n\n  // Validate XML first\n  const validation = XMLValidator.validate(xml);\n  if (validation !== true) {\n    throw new Error(`Invalid XML: ${validation.err.msg}`);\n  }\n\n  const mergedOptions = {\n    ...DEFAULT_PARSE_OPTIONS,\n    ...options,\n  };\n\n  const parser = new XMLParser(mergedOptions);\n  return parser.parse(xml) as Record<string, unknown>;\n}\n\n/**\n * Build XML string from JavaScript object\n *\n * @param obj - JavaScript object to convert to XML\n * @param options - Optional builder configuration (merged with defaults)\n * @returns XML string\n *\n * @example\n * ```typescript\n * const obj = { root: { item: { id: '1', '#text': 'Test' } } };\n * const xml = buildXml(obj);\n * // Returns formatted XML string\n * ```\n */\nexport function buildXml(\n  obj: Record<string, unknown>,\n  options?: Partial<XmlBuilderOptions>\n): string {\n  const mergedOptions = {\n    ...DEFAULT_BUILD_OPTIONS,\n    ...options,\n  };\n\n  const builder = new XMLBuilder(mergedOptions);\n  return builder.build(obj) as string;\n}\n\n/**\n * Validate if a string is well-formed XML\n *\n * @param xml - String to validate\n * @returns True if valid XML, false otherwise\n *\n * @example\n * ```typescript\n * isValidXml('<root><item>Test</item></root>'); // true\n * isValidXml('<root><item>Test</root>'); // false (mismatched tags)\n * isValidXml('not xml'); // false\n * ```\n */\nexport function isValidXml(xml: string): boolean {\n  if (!xml || xml.trim().length === 0) {\n    return false;\n  }\n\n  const result = XMLValidator.validate(xml);\n  return result === true;\n}\n\n/**\n * Parse XML with array handling for repeated elements\n * Forces specified tag names to always be arrays, even if only one element exists\n *\n * @param xml - XML string to parse\n * @param arrayTags - Array of tag names that should always be parsed as arrays\n * @returns Parsed JavaScript object with forced arrays\n *\n * @example\n * ```typescript\n * const xml = '<root><item>Test</item></root>';\n * const result = parseXmlWithArrays(xml, ['item']);\n * // Returns: { root: { item: ['Test'] } }\n * // Without arrayTags, would return: { root: { item: 'Test' } }\n * ```\n */\nexport function parseXmlWithArrays(\n  xml: string,\n  arrayTags: string[],\n  options?: Partial<X2jOptions> & { maxSize?: number }\n): Record<string, unknown> {\n  if (options?.maxSize !== undefined && xml.length > options.maxSize) {\n    throw new Error(\n      `Input exceeds maximum allowed size: ${xml.length} bytes exceeds limit of ${options.maxSize} bytes`\n    );\n  }\n\n  // Validate XML first (consistency with parseXml)\n  const validation = XMLValidator.validate(xml);\n  if (validation !== true) {\n    throw new Error(`Invalid XML: ${validation.err.msg}`);\n  }\n\n  const mergedOptions: Partial<X2jOptions> = {\n    ...DEFAULT_PARSE_OPTIONS,\n    ...options,\n    isArray: (tagName: string) => arrayTags.includes(tagName),\n  };\n\n  const parser = new XMLParser(mergedOptions);\n  return parser.parse(xml) as Record<string, unknown>;\n}\n\n/**\n * Extract text content from XML, stripping all tags\n *\n * @param xml - XML string\n * @returns Plain text content with tags removed\n *\n * @example\n * ```typescript\n * const xml = '<root><b>Bold</b> and <i>italic</i></root>';\n * const text = extractTextFromXml(xml);\n * // Returns: 'Bold and italic'\n * ```\n */\nexport function extractTextFromXml(xml: string): string {\n  if (!isValidXml(xml)) {\n    return '';\n  }\n\n  try {\n    const parsed = parseXml(xml, { ignoreAttributes: true });\n    return extractTextRecursive(parsed).trim();\n  } catch {\n    return '';\n  }\n}\n\n/**\n * Recursively extract text from parsed XML object\n * @private\n */\nfunction extractTextRecursive(obj: unknown): string {\n  if (typeof obj === 'string' || typeof obj === 'number') {\n    return String(obj);\n  }\n\n  if (Array.isArray(obj)) {\n    return obj.map(extractTextRecursive).join(' ');\n  }\n\n  if (typeof obj === 'object' && obj !== null) {\n    const record = obj as Record<string, unknown>;\n\n    // Recursively extract text from all properties\n    return Object.values(record)\n      .map(extractTextRecursive)\n      .filter(text => text.length > 0)\n      .join(' ');\n  }\n\n  return '';\n}\n"],"mappings":";;;;;;;;;;;;;;;AAkBA,MAAM,wBAA6C;CACjD,qBAAqB;CACrB,cAAc;CACd,kBAAkB;CAClB,mBAAmB;CACnB,qBAAqB;CACrB,eAAe;CACf,gBAAgB;CAChB,iBAAiB;AACnB;;;;AAKA,MAAM,wBAAoD;CACxD,qBAAqB;CACrB,cAAc;CACd,kBAAkB;CAClB,QAAQ;CACR,UAAU;CACV,mBAAmB;AACrB;;;;;;;;;;;;;;;AAgBA,SAAgB,SACd,KACA,SACyB;CACzB,IAAI,SAAS,YAAY,KAAA,KAAa,IAAI,SAAS,QAAQ,SACzD,MAAM,IAAI,MACR,uCAAuC,IAAI,OAAO,0BAA0B,QAAQ,QAAQ,OAC9F;CAIF,MAAM,aAAa,aAAa,SAAS,GAAG;CAC5C,IAAI,eAAe,MACjB,MAAM,IAAI,MAAM,gBAAgB,WAAW,IAAI,KAAK;CAStD,OAAO,IADY,UAAU;EAJ3B,GAAG;EACH,GAAG;CAGoC,CAC7B,CAAC,CAAC,MAAM,GAAG;AACzB;;;;;;;;;;;;;;;AAgBA,SAAgB,SACd,KACA,SACQ;CAOR,OAAO,IADa,WAAW;EAJ7B,GAAG;EACH,GAAG;CAGsC,CAC9B,CAAC,CAAC,MAAM,GAAG;AAC1B;;;;;;;;;;;;;;AAeA,SAAgB,WAAW,KAAsB;CAC/C,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC,CAAC,WAAW,GAChC,OAAO;CAIT,OADe,aAAa,SAAS,GACzB,MAAM;AACpB;;;;;;;;;;;;;;;;;AAkBA,SAAgB,mBACd,KACA,WACA,SACyB;CACzB,IAAI,SAAS,YAAY,KAAA,KAAa,IAAI,SAAS,QAAQ,SACzD,MAAM,IAAI,MACR,uCAAuC,IAAI,OAAO,0BAA0B,QAAQ,QAAQ,OAC9F;CAIF,MAAM,aAAa,aAAa,SAAS,GAAG;CAC5C,IAAI,eAAe,MACjB,MAAM,IAAI,MAAM,gBAAgB,WAAW,IAAI,KAAK;CAUtD,OAAO,IADY,UAAU;EAL3B,GAAG;EACH,GAAG;EACH,UAAU,YAAoB,UAAU,SAAS,OAAO;CAGjB,CAC7B,CAAC,CAAC,MAAM,GAAG;AACzB;;;;;;;;;;;;;;AAeA,SAAgB,mBAAmB,KAAqB;CACtD,IAAI,CAAC,WAAW,GAAG,GACjB,OAAO;CAGT,IAAI;EAEF,OAAO,qBADQ,SAAS,KAAK,EAAE,kBAAkB,KAAK,CACrB,CAAC,CAAC,CAAC,KAAK;CAC3C,QAAQ;EACN,OAAO;CACT;AACF;;;;;AAMA,SAAS,qBAAqB,KAAsB;CAClD,IAAI,OAAO,QAAQ,YAAY,OAAO,QAAQ,UAC5C,OAAO,OAAO,GAAG;CAGnB,IAAI,MAAM,QAAQ,GAAG,GACnB,OAAO,IAAI,IAAI,oBAAoB,CAAC,CAAC,KAAK,GAAG;CAG/C,IAAI,OAAO,QAAQ,YAAY,QAAQ,MAIrC,OAAO,OAAO,OAAOA,GAAM,CAAC,CACzB,IAAI,oBAAoB,CAAC,CACzB,QAAO,SAAQ,KAAK,SAAS,CAAC,CAAC,CAC/B,KAAK,GAAG;CAGb,OAAO;AACT"}
+{"version":3,"file":"index.js","names":["record"],"sources":["../../src/xml/index.ts"],"sourcesContent":["/**\n * XML parsing utilities for HDF converters\n * Provides XML parsing with sensible defaults for security tool output\n */\n\nimport { XMLParser, XMLBuilder, XMLValidator } from 'fast-xml-parser';\nimport type { X2jOptions, XmlBuilderOptions } from 'fast-xml-parser';\n\nexport { findValuesByKey as findXmlValues } from '../object/index.js';\n\n/**\n * Default options for XML parsing optimized for security tool converters.\n *\n * **XXE Safety**: fast-xml-parser v5.x does not process DTD or external entities\n * by default. The `processEntities: false` option is set as defense-in-depth to\n * ensure entity expansion is disabled even if future versions change defaults.\n * See: https://github.com/NaturalIntelligence/fast-xml-parser/blob/master/docs/v5/2.XMLparseOptions.md\n */\nconst DEFAULT_PARSE_OPTIONS: Partial<X2jOptions> = {\n  attributeNamePrefix: '',\n  textNodeName: '#text',\n  ignoreAttributes: false,\n  ignoreDeclaration: true,\n  parseAttributeValue: false,\n  parseTagValue: false,\n  removeNSPrefix: true,\n  processEntities: false,\n};\n\n/**\n * Default options for XML building\n */\nconst DEFAULT_BUILD_OPTIONS: Partial<XmlBuilderOptions> = {\n  attributeNamePrefix: '',\n  textNodeName: '#text',\n  ignoreAttributes: false,\n  format: true,\n  indentBy: '  ',\n  suppressEmptyNode: false,\n};\n\n/**\n * Parse XML string to JavaScript object\n *\n * @param xml - XML string to parse\n * @param options - Optional parser configuration (merged with defaults)\n * @returns Parsed JavaScript object\n *\n * @example\n * ```typescript\n * const xmlString = '<root><item id=\"1\">Test</item></root>';\n * const result = parseXml(xmlString);\n * // Returns: { root: { item: { id: '1', '#text': 'Test' } } }\n * ```\n */\nexport function parseXml(\n  xml: string,\n  options?: Partial<X2jOptions> & { maxSize?: number }\n): Record<string, unknown> {\n  if (options?.maxSize !== undefined && xml.length > options.maxSize) {\n    throw new Error(\n      `Input exceeds maximum allowed size: ${xml.length} bytes exceeds limit of ${options.maxSize} bytes`\n    );\n  }\n\n  // Validate XML first\n  const validation = XMLValidator.validate(xml);\n  if (validation !== true) {\n    throw new Error(`Invalid XML: ${validation.err.msg}`);\n  }\n\n  const mergedOptions = {\n    ...DEFAULT_PARSE_OPTIONS,\n    ...options,\n  };\n\n  const parser = new XMLParser(mergedOptions);\n  return parser.parse(xml) as Record<string, unknown>;\n}\n\n/**\n * Build XML string from JavaScript object\n *\n * @param obj - JavaScript object to convert to XML, or a preserveOrder node list.\n *   An array is only meaningful with `preserveOrder: true`; without it the builder\n *   indexes the array and emits elements named by its numeric keys.\n * @param options - Optional builder configuration (merged with defaults)\n * @returns XML string\n *\n * @example\n * ```typescript\n * const obj = { root: { item: { id: '1', '#text': 'Test' } } };\n * const xml = buildXml(obj);\n * // Returns formatted XML string\n * ```\n */\nexport function buildXml(\n  obj: Record<string, unknown> | unknown[],\n  options?: Partial<XmlBuilderOptions>\n): string {\n  const mergedOptions = {\n    ...DEFAULT_BUILD_OPTIONS,\n    ...options,\n  };\n\n  const builder = new XMLBuilder(mergedOptions);\n  return builder.build(obj) as string;\n}\n\n/**\n * Validate if a string is well-formed XML\n *\n * @param xml - String to validate\n * @returns True if valid XML, false otherwise\n *\n * @example\n * ```typescript\n * isValidXml('<root><item>Test</item></root>'); // true\n * isValidXml('<root><item>Test</root>'); // false (mismatched tags)\n * isValidXml('not xml'); // false\n * ```\n */\n/**\n * Whether a character is legal in an XML 1.0 document, per the Char production.\n * The one home for this rule: an emitter deciding what to replace and a\n * validator deciding what to reject must not answer it differently.\n */\nexport function isXmlChar(ch: string): boolean {\n  const c = ch.codePointAt(0) as number;\n  return (\n    c === 0x9 ||\n    c === 0xa ||\n    c === 0xd ||\n    (c >= 0x20 && c <= 0xd7ff) ||\n    (c >= 0xe000 && c <= 0xfffd) ||\n    c >= 0x10000\n  );\n}\n\n/**\n * Replace every character XML 1.0 forbids with U+FFFD, which is what Go's\n * encoding/xml does. XML defines no escape for these — a numeric reference to a\n * C0 control is itself illegal — so the choice is a replacement character or a\n * document no conforming parser will read.\n */\nexport function xmlSafeText(value: string): string {\n  let out = '';\n  for (const ch of value) out += isXmlChar(ch) ? ch : '\\ufffd';\n  return out;\n}\n\nexport function isValidXml(xml: string): boolean {\n  if (!xml || xml.trim().length === 0) {\n    return false;\n  }\n\n  // The structural validator does not enforce XML 1.0's Char production, so it\n  // called a document well-formed that no conforming parser will read — which is\n  // how a converter emitting a raw ESC passed its own well-formedness check.\n  for (const ch of xml) {\n    if (!isXmlChar(ch)) return false;\n  }\n\n  const result = XMLValidator.validate(xml);\n  return result === true;\n}\n\n/**\n * Parse XML with array handling for repeated elements\n * Forces specified tag names to always be arrays, even if only one element exists\n *\n * @param xml - XML string to parse\n * @param arrayTags - Array of tag names that should always be parsed as arrays\n * @returns Parsed JavaScript object with forced arrays\n *\n * @example\n * ```typescript\n * const xml = '<root><item>Test</item></root>';\n * const result = parseXmlWithArrays(xml, ['item']);\n * // Returns: { root: { item: ['Test'] } }\n * // Without arrayTags, would return: { root: { item: 'Test' } }\n * ```\n */\nexport function parseXmlWithArrays(\n  xml: string,\n  arrayTags: string[],\n  options?: Partial<X2jOptions> & { maxSize?: number }\n): Record<string, unknown> {\n  if (options?.maxSize !== undefined && xml.length > options.maxSize) {\n    throw new Error(\n      `Input exceeds maximum allowed size: ${xml.length} bytes exceeds limit of ${options.maxSize} bytes`\n    );\n  }\n\n  // Validate XML first (consistency with parseXml)\n  const validation = XMLValidator.validate(xml);\n  if (validation !== true) {\n    throw new Error(`Invalid XML: ${validation.err.msg}`);\n  }\n\n  const mergedOptions: Partial<X2jOptions> = {\n    ...DEFAULT_PARSE_OPTIONS,\n    ...options,\n    isArray: (tagName: string) => arrayTags.includes(tagName),\n  };\n\n  const parser = new XMLParser(mergedOptions);\n  return parser.parse(xml) as Record<string, unknown>;\n}\n\n/**\n * Extract text content from XML, stripping all tags\n *\n * @param xml - XML string\n * @returns Plain text content with tags removed\n *\n * @example\n * ```typescript\n * const xml = '<root><b>Bold</b> and <i>italic</i></root>';\n * const text = extractTextFromXml(xml);\n * // Returns: 'Bold and italic'\n * ```\n */\nexport function extractTextFromXml(xml: string): string {\n  if (!isValidXml(xml)) {\n    return '';\n  }\n\n  try {\n    const parsed = parseXml(xml, { ignoreAttributes: true });\n    return extractTextRecursive(parsed).trim();\n  } catch {\n    return '';\n  }\n}\n\n/**\n * Recursively extract text from parsed XML object\n * @private\n */\nfunction extractTextRecursive(obj: unknown): string {\n  if (typeof obj === 'string' || typeof obj === 'number') {\n    return String(obj);\n  }\n\n  if (Array.isArray(obj)) {\n    return obj.map(extractTextRecursive).join(' ');\n  }\n\n  if (typeof obj === 'object' && obj !== null) {\n    const record = obj as Record<string, unknown>;\n\n    // Recursively extract text from all properties\n    return Object.values(record)\n      .map(extractTextRecursive)\n      .filter(text => text.length > 0)\n      .join(' ');\n  }\n\n  return '';\n}\n"],"mappings":";;;;;;;;;;;;;;;AAkBA,MAAM,wBAA6C;CACjD,qBAAqB;CACrB,cAAc;CACd,kBAAkB;CAClB,mBAAmB;CACnB,qBAAqB;CACrB,eAAe;CACf,gBAAgB;CAChB,iBAAiB;AACnB;;;;AAKA,MAAM,wBAAoD;CACxD,qBAAqB;CACrB,cAAc;CACd,kBAAkB;CAClB,QAAQ;CACR,UAAU;CACV,mBAAmB;AACrB;;;;;;;;;;;;;;;AAgBA,SAAgB,SACd,KACA,SACyB;CACzB,IAAI,SAAS,YAAY,KAAA,KAAa,IAAI,SAAS,QAAQ,SACzD,MAAM,IAAI,MACR,uCAAuC,IAAI,OAAO,0BAA0B,QAAQ,QAAQ,OAC9F;CAIF,MAAM,aAAa,aAAa,SAAS,GAAG;CAC5C,IAAI,eAAe,MACjB,MAAM,IAAI,MAAM,gBAAgB,WAAW,IAAI,KAAK;CAStD,OAAO,IADY,UAAU;EAJ3B,GAAG;EACH,GAAG;CAGoC,CAC7B,CAAC,CAAC,MAAM,GAAG;AACzB;;;;;;;;;;;;;;;;;AAkBA,SAAgB,SACd,KACA,SACQ;CAOR,OAAO,IADa,WAAW;EAJ7B,GAAG;EACH,GAAG;CAGsC,CAC9B,CAAC,CAAC,MAAM,GAAG;AAC1B;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,UAAU,IAAqB;CAC7C,MAAM,IAAI,GAAG,YAAY,CAAC;CAC1B,OACE,MAAM,KACN,MAAM,MACN,MAAM,MACL,KAAK,MAAQ,KAAK,SAClB,KAAK,SAAU,KAAK,SACrB,KAAK;AAET;;;;;;;AAQA,SAAgB,YAAY,OAAuB;CACjD,IAAI,MAAM;CACV,KAAK,MAAM,MAAM,OAAO,OAAO,UAAU,EAAE,IAAI,KAAK;CACpD,OAAO;AACT;AAEA,SAAgB,WAAW,KAAsB;CAC/C,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC,CAAC,WAAW,GAChC,OAAO;CAMT,KAAK,MAAM,MAAM,KACf,IAAI,CAAC,UAAU,EAAE,GAAG,OAAO;CAI7B,OADe,aAAa,SAAS,GACzB,MAAM;AACpB;;;;;;;;;;;;;;;;;AAkBA,SAAgB,mBACd,KACA,WACA,SACyB;CACzB,IAAI,SAAS,YAAY,KAAA,KAAa,IAAI,SAAS,QAAQ,SACzD,MAAM,IAAI,MACR,uCAAuC,IAAI,OAAO,0BAA0B,QAAQ,QAAQ,OAC9F;CAIF,MAAM,aAAa,aAAa,SAAS,GAAG;CAC5C,IAAI,eAAe,MACjB,MAAM,IAAI,MAAM,gBAAgB,WAAW,IAAI,KAAK;CAUtD,OAAO,IADY,UAAU;EAL3B,GAAG;EACH,GAAG;EACH,UAAU,YAAoB,UAAU,SAAS,OAAO;CAGjB,CAC7B,CAAC,CAAC,MAAM,GAAG;AACzB;;;;;;;;;;;;;;AAeA,SAAgB,mBAAmB,KAAqB;CACtD,IAAI,CAAC,WAAW,GAAG,GACjB,OAAO;CAGT,IAAI;EAEF,OAAO,qBADQ,SAAS,KAAK,EAAE,kBAAkB,KAAK,CACrB,CAAC,CAAC,CAAC,KAAK;CAC3C,QAAQ;EACN,OAAO;CACT;AACF;;;;;AAMA,SAAS,qBAAqB,KAAsB;CAClD,IAAI,OAAO,QAAQ,YAAY,OAAO,QAAQ,UAC5C,OAAO,OAAO,GAAG;CAGnB,IAAI,MAAM,QAAQ,GAAG,GACnB,OAAO,IAAI,IAAI,oBAAoB,CAAC,CAAC,KAAK,GAAG;CAG/C,IAAI,OAAO,QAAQ,YAAY,QAAQ,MAIrC,OAAO,OAAO,OAAOA,GAAM,CAAC,CACzB,IAAI,oBAAoB,CAAC,CACzB,QAAO,SAAQ,KAAK,SAAS,CAAC,CAAC,CAC/B,KAAK,GAAG;CAGb,OAAO;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mitre/hdf-utilities",
-  "version": "3.6.0-rc.1",
+  "version": "3.6.0-rc.3",
   "description": "Utility functions for HDF libraries (JSON parsing, validation helpers)",
   "publishConfig": {
     "access": "public"
@@ -76,8 +76,6 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "type-check": "tsc --noEmit",
-    "lint": "eslint src test",
-    "lint:go": "cd go && golangci-lint run",
-    "lint:fix": "eslint src test --fix"
+    "lint:go": "cd go && golangci-lint run"
   }
 }

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

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

package/dist/json/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/json/index.ts"],"sourcesContent":["export { findValuesByKey as findJsonValues } from '../object/index.js';\n\n/**\n * Options for JSON stringification\n */\nexport interface StringifyOptions {\n  /** Enable pretty printing with indentation */\n  pretty?: boolean;\n  /** Number of spaces for indentation (default: 2) */\n  indent?: number;\n}\n\n/**\n * Safely parse a JSON string\n * @param input - JSON string to parse\n * @returns Parsed JSON value\n * @throws Error if input is not valid JSON\n */\nexport function parseJSON<T = unknown>(input: string): T {\n  if (typeof input !== 'string') {\n    throw new Error('Input must be a string');\n  }\n\n  if (input.trim() === '') {\n    throw new Error('Input cannot be empty');\n  }\n\n  try {\n    return JSON.parse(input) as T;\n  } catch (error) {\n    throw new Error(`Invalid JSON: ${error instanceof Error ? error.message : String(error)}`);\n  }\n}\n\n/**\n * Safely stringify a value to JSON\n * @param value - Value to stringify\n * @param options - Stringification options\n * @returns JSON string\n * @throws Error if value contains circular references or cannot be stringified\n */\nexport function stringifyJSON(value: unknown, options: StringifyOptions = {}): string {\n  const { pretty = false, indent = 2 } = options;\n\n  try {\n    if (pretty) {\n      return JSON.stringify(value, null, indent);\n    }\n    return JSON.stringify(value);\n  } catch (error) {\n    throw new Error(`Failed to stringify JSON: ${error instanceof Error ? error.message : String(error)}`);\n  }\n}\n\n/**\n * Check if a string is valid JSON\n * @param input - String to validate\n * @returns true if input is valid JSON, false otherwise\n */\nexport function isValidJSON(input: unknown): boolean {\n  if (typeof input !== 'string') {\n    return false;\n  }\n\n  if (input.trim() === '') {\n    return false;\n  }\n\n  try {\n    JSON.parse(input);\n    return true;\n  } catch {\n    return false;\n  }\n}\n"],"mappings":";;;;;;;;AAkBA,SAAgB,UAAuB,OAAkB;CACvD,IAAI,OAAO,UAAU,UACnB,MAAM,IAAI,MAAM,wBAAwB;CAG1C,IAAI,MAAM,KAAK,MAAM,IACnB,MAAM,IAAI,MAAM,uBAAuB;CAGzC,IAAI;EACF,OAAO,KAAK,MAAM,KAAK;CACzB,SAAS,OAAO;EACd,MAAM,IAAI,MAAM,iBAAiB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAAG;CAC3F;AACF;;;;;;;;AASA,SAAgB,cAAc,OAAgB,UAA4B,CAAC,GAAW;CACpF,MAAM,EAAE,SAAS,OAAO,SAAS,MAAM;CAEvC,IAAI;EACF,IAAI,QACF,OAAO,KAAK,UAAU,OAAO,MAAM,MAAM;EAE3C,OAAO,KAAK,UAAU,KAAK;CAC7B,SAAS,OAAO;EACd,MAAM,IAAI,MAAM,6BAA6B,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAAG;CACvG;AACF;;;;;;AAOA,SAAgB,YAAY,OAAyB;CACnD,IAAI,OAAO,UAAU,UACnB,OAAO;CAGT,IAAI,MAAM,KAAK,MAAM,IACnB,OAAO;CAGT,IAAI;EACF,KAAK,MAAM,KAAK;EAChB,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF"}