@bcts/dcbor 1.0.0-alpha.10

package/src/dump.ts

@@ -0,0 +1,277 @@
+/**
+ * Hex dump utilities for CBOR data.
+ *
+ * Affordances for viewing the encoded binary representation of CBOR as hexadecimal.
+ * Optionally annotates the output, breaking it up into semantically meaningful lines,
+ * formatting dates, and adding names of known tags.
+ *
+ * @module dump
+ */
+
+import { type Cbor, MajorType, cborData } from "./cbor";
+import { encodeVarInt } from "./varint";
+import { flanked, sanitized } from "./string-util";
+import type { TagsStore } from "./tags-store";
+import { getGlobalTagsStore } from "./tags-store";
+import { createTag } from "./tag";
+import { CborError } from "./error";
+
+/**
+ * Options for hex formatting.
+ */
+export interface HexFormatOpts {
+  /** Whether to annotate the hex dump with semantic information */
+  annotate?: boolean;
+  /** Optional tags store for resolving tag names */
+  tagsStore?: TagsStore;
+}
+
+/**
+ * Convert bytes to hex string.
+ */
+export const bytesToHex = (bytes: Uint8Array): string => {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+};
+
+/**
+ * Convert hex string to bytes.
+ */
+export const hexToBytes = (hexString: string): Uint8Array => {
+  const hex = hexString.replace(/\s/g, "");
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+  }
+  return bytes;
+};
+
+/**
+ * Returns the encoded hexadecimal representation of CBOR.
+ *
+ * @param cbor - CBOR value to convert
+ * @returns Hex string
+ */
+export const hex = (cbor: Cbor): string => bytesToHex(cborData(cbor));
+
+/**
+ * Returns the encoded hexadecimal representation of CBOR with options.
+ *
+ * Optionally annotates the output, e.g., breaking the output up into
+ * semantically meaningful lines, formatting dates, and adding names of
+ * known tags.
+ *
+ * @param cbor - CBOR value to convert
+ * @param opts - Formatting options
+ * @returns Hex string (possibly annotated)
+ */
+export const hexOpt = (cbor: Cbor, opts: HexFormatOpts = {}): string => {
+  if (opts.annotate !== true) {
+    return hex(cbor);
+  }
+
+  const items = dumpItems(cbor, 0, opts);
+  const noteColumn = items.reduce((largest, item) => {
+    return Math.max(largest, item.formatFirstColumn().length);
+  }, 0);
+
+  // Round up to nearest multiple of 4
+  const roundedNoteColumn = ((noteColumn + 4) & ~3) - 1;
+
+  const lines = items.map((item) => item.format(roundedNoteColumn));
+  return lines.join("\n");
+};
+
+/**
+ * Returns the encoded hexadecimal representation of CBOR, with annotations.
+ *
+ * @param cbor - CBOR value to convert
+ * @param tagsStore - Optional tags store for tag name resolution
+ * @returns Annotated hex string
+ */
+export const hexAnnotated = (cbor: Cbor, tagsStore?: TagsStore): string => {
+  // Use global tags store if not provided
+  tagsStore ??= getGlobalTagsStore();
+  return hexOpt(cbor, { annotate: true, tagsStore });
+};
+
+/**
+ * Internal structure for dump items.
+ */
+class DumpItem {
+  constructor(
+    public level: number,
+    public data: Uint8Array[],
+    public note?: string,
+  ) {}
+
+  format(noteColumn: number): string {
+    const column1 = this.formatFirstColumn();
+    let column2 = "";
+    let padding = "";
+
+    if (this.note !== undefined) {
+      const paddingCount = Math.max(1, Math.min(39, noteColumn) - column1.length + 1);
+      padding = " ".repeat(paddingCount);
+      column2 = `# ${this.note}`;
+    }
+
+    return column1 + padding + column2;
+  }
+
+  formatFirstColumn(): string {
+    const indent = " ".repeat(this.level * 4);
+    const hexParts = this.data.map(bytesToHex).filter((x) => x.length > 0);
+    const hexStr = hexParts.join(" ");
+    return indent + hexStr;
+  }
+}
+
+/**
+ * Generate dump items for a CBOR value (recursive).
+ */
+function dumpItems(cbor: Cbor, level: number, opts: HexFormatOpts): DumpItem[] {
+  const items: DumpItem[] = [];
+
+  switch (cbor.type) {
+    case MajorType.Unsigned: {
+      const data = cborData(cbor);
+      items.push(new DumpItem(level, [data], `unsigned(${cbor.value})`));
+      break;
+    }
+
+    case MajorType.Negative: {
+      const data = cborData(cbor);
+      const actualValue = typeof cbor.value === "bigint" ? -1n - cbor.value : -1 - cbor.value;
+      items.push(new DumpItem(level, [data], `negative(${actualValue})`));
+      break;
+    }
+
+    case MajorType.ByteString: {
+      const header = encodeVarInt(cbor.value.length, MajorType.ByteString);
+      items.push(new DumpItem(level, [header], `bytes(${cbor.value.length})`));
+
+      if (cbor.value.length > 0) {
+        let note: string | undefined = undefined;
+        // Try to decode as UTF-8 string for annotation
+        try {
+          const text = new TextDecoder("utf-8", { fatal: true }).decode(cbor.value);
+          const sanitizedText = sanitized(text);
+          if (sanitizedText !== undefined && sanitizedText !== "") {
+            note = flanked(sanitizedText, '"', '"');
+          }
+        } catch {
+          // Not valid UTF-8, no annotation
+        }
+
+        items.push(new DumpItem(level + 1, [cbor.value], note));
+      }
+      break;
+    }
+
+    case MajorType.Text: {
+      const utf8Data = new TextEncoder().encode(cbor.value);
+      const header = encodeVarInt(utf8Data.length, MajorType.Text);
+      const firstByte = header[0];
+      if (firstByte === undefined) {
+        throw new CborError({ type: "Custom", message: "Invalid varint encoding" });
+      }
+      const headerData = [new Uint8Array([firstByte]), header.slice(1)];
+
+      items.push(new DumpItem(level, headerData, `text(${utf8Data.length})`));
+
+      items.push(new DumpItem(level + 1, [utf8Data], flanked(cbor.value, '"', '"')));
+      break;
+    }
+
+    case MajorType.Array: {
+      const header = encodeVarInt(cbor.value.length, MajorType.Array);
+      const firstByte = header[0];
+      if (firstByte === undefined) {
+        throw new CborError({ type: "Custom", message: "Invalid varint encoding" });
+      }
+      const headerData = [new Uint8Array([firstByte]), header.slice(1)];
+
+      items.push(new DumpItem(level, headerData, `array(${cbor.value.length})`));
+
+      for (const item of cbor.value) {
+        items.push(...dumpItems(item, level + 1, opts));
+      }
+      break;
+    }
+
+    case MajorType.Map: {
+      const header = encodeVarInt(cbor.value.size, MajorType.Map);
+      const firstByte = header[0];
+      if (firstByte === undefined) {
+        throw new CborError({ type: "Custom", message: "Invalid varint encoding" });
+      }
+      const headerData = [new Uint8Array([firstByte]), header.slice(1)];
+
+      items.push(new DumpItem(level, headerData, `map(${cbor.value.size})`));
+
+      for (const entry of cbor.value.entriesArray) {
+        items.push(...dumpItems(entry.key, level + 1, opts));
+        items.push(...dumpItems(entry.value, level + 1, opts));
+      }
+      break;
+    }
+
+    case MajorType.Tagged: {
+      const tagValue = cbor.tag;
+      if (tagValue === undefined) {
+        throw new CborError({ type: "Custom", message: "Tagged CBOR value must have a tag" });
+      }
+      const header = encodeVarInt(
+        typeof tagValue === "bigint" ? Number(tagValue) : tagValue,
+        MajorType.Tagged,
+      );
+      const firstByte = header[0];
+      if (firstByte === undefined) {
+        throw new CborError({ type: "Custom", message: "Invalid varint encoding" });
+      }
+      const headerData = [new Uint8Array([firstByte]), header.slice(1)];
+
+      const noteComponents: string[] = [`tag(${tagValue})`];
+
+      // Add tag name if tags store is provided
+      const numericTagValue = typeof tagValue === "bigint" ? Number(tagValue) : tagValue;
+      const tag = createTag(numericTagValue);
+      const tagName = opts.tagsStore?.assignedNameForTag(tag);
+      if (tagName !== undefined) {
+        noteComponents.push(tagName);
+      }
+
+      const tagNote = noteComponents.join(" ");
+
+      items.push(new DumpItem(level, headerData, tagNote));
+
+      items.push(...dumpItems(cbor.value, level + 1, opts));
+      break;
+    }
+
+    case MajorType.Simple: {
+      const data = cborData(cbor);
+      const simple = cbor.value;
+      let note: string;
+
+      if (simple.type === "True") {
+        note = "true";
+      } else if (simple.type === "False") {
+        note = "false";
+      } else if (simple.type === "Null") {
+        note = "null";
+      } else if (simple.type === "Float") {
+        note = `${simple.value}`;
+      } else {
+        note = "simple";
+      }
+
+      items.push(new DumpItem(level, [data], note));
+      break;
+    }
+  }
+
+  return items;
+}

package/src/error.ts

@@ -0,0 +1,259 @@
+/**
+ * Error types for CBOR encoding and decoding.
+ *
+ * @module error
+ */
+
+import type { Tag } from "./tag";
+import { tagToString } from "./tag";
+
+/**
+ * A comprehensive set of errors that can occur during CBOR encoding and
+ * decoding operations with special focus on enforcing the deterministic
+ * encoding rules specified in the dCBOR specification.
+ *
+ * The dCBOR implementation validates all encoded CBOR against the
+ * deterministic encoding requirements of RFC 8949 §4.2.1, plus additional
+ * constraints defined in the dCBOR application profile. These errors represent
+ * all the possible validation failures and decoding issues that can arise.
+ */
+export type Error =
+  /**
+   * The CBOR data ended prematurely during decoding, before a complete CBOR
+   * item could be decoded. This typically happens when a CBOR item's
+   * structure indicates more data than is actually present.
+   */
+  | { readonly type: "Underrun" }
+  /**
+   * An unsupported or invalid value was encountered in a CBOR header byte.
+   * The parameter contains the unsupported header byte value.
+   * This can occur when decoding CBOR that uses unsupported features or is
+   * malformed.
+   */
+  | { readonly type: "UnsupportedHeaderValue"; readonly value: number }
+  /**
+   * A CBOR numeric value was encoded in a non-canonical form, violating the
+   * deterministic encoding requirement of dCBOR (per Section 2.3 of the
+   * dCBOR specification).
+   *
+   * This error is triggered when:
+   * - An integer is not encoded in its shortest possible form
+   * - A floating point value that could be represented as an integer was not
+   *   reduced
+   * - A NaN value was not encoded in its canonical form (`f97e00`)
+   */
+  | { readonly type: "NonCanonicalNumeric" }
+  /**
+   * An invalid CBOR simple value was encountered during decoding.
+   *
+   * Per Section 2.4 of the dCBOR specification, only `false`, `true`,
+   * `null`, and floating point values are valid simple values in dCBOR.
+   * All other major type 7 values are invalid.
+   */
+  | { readonly type: "InvalidSimpleValue" }
+  /**
+   * A CBOR text string was not valid UTF-8. The parameter contains the
+   * specific error message.
+   *
+   * All CBOR text strings (major type 3) must be valid UTF-8 per RFC 8949.
+   */
+  | { readonly type: "InvalidString"; readonly message: string }
+  /**
+   * A CBOR text string was not encoded in Unicode Canonical Normalization
+   * Form C (NFC).
+   *
+   * Per Section 2.5 of the dCBOR specification, all text strings must be in
+   * NFC form, and decoders must reject any encoded text strings that are
+   * not in NFC.
+   */
+  | { readonly type: "NonCanonicalString" }
+  /**
+   * The decoded CBOR item didn't consume all input data.
+   * The parameter contains the number of unused bytes.
+   *
+   * This error occurs when decoding functions expect exactly one CBOR item
+   * but the input contains additional data after a valid CBOR item.
+   */
+  | { readonly type: "UnusedData"; readonly count: number }
+  /**
+   * The keys in a decoded CBOR map were not in the canonical lexicographic order
+   * of their encoding.
+   *
+   * Per the CDE specification and Section 2.1 of dCBOR, map keys must be in
+   * ascending lexicographic order of their encoded representation for
+   * deterministic encoding.
+   */
+  | { readonly type: "MisorderedMapKey" }
+  /**
+   * A decoded CBOR map contains duplicate keys, which is invalid.
+   *
+   * Per Section 2.2 of the dCBOR specification, CBOR maps must not contain
+   * duplicate keys, and decoders must reject encoded maps with duplicate
+   * keys.
+   */
+  | { readonly type: "DuplicateMapKey" }
+  /**
+   * A requested key was not found in a CBOR map during data extraction.
+   */
+  | { readonly type: "MissingMapKey" }
+  /**
+   * A CBOR numeric value could not be represented in the specified target
+   * numeric type.
+   *
+   * This occurs when attempting to convert a CBOR number to a numeric
+   * type that is too small to represent the value without loss of
+   * precision.
+   */
+  | { readonly type: "OutOfRange" }
+  /**
+   * The CBOR value is not of the expected type for a conversion or
+   * operation.
+   *
+   * This occurs when attempting to convert a CBOR value to a type that
+   * doesn't match the actual CBOR item's type (e.g., trying to convert a
+   * string to an integer).
+   */
+  | { readonly type: "WrongType" }
+  /**
+   * The CBOR tagged value had a different tag than expected.
+   * Contains the expected tag and the actual tag found.
+   */
+  | { readonly type: "WrongTag"; readonly expected: Tag; readonly actual: Tag }
+  /**
+   * Invalid UTF‑8 in a text string.
+   */
+  | { readonly type: "InvalidUtf8"; readonly message: string }
+  /**
+   * Invalid ISO 8601 date format.
+   */
+  | { readonly type: "InvalidDate"; readonly message: string }
+  /**
+   * Custom error message.
+   */
+  | { readonly type: "Custom"; readonly message: string };
+
+/**
+ * Create a custom error with a message.
+ *
+ * Matches Rust's `Error::msg()` method.
+ */
+export const errorMsg = (message: string): Error => ({
+  type: "Custom",
+  message,
+});
+
+/**
+ * Convert an Error to a display string.
+ *
+ * Matches Rust's `Display` trait / `to_string()` method.
+ */
+export const errorToString = (error: Error): string => {
+  switch (error.type) {
+    case "Underrun":
+      return "early end of CBOR data";
+    case "UnsupportedHeaderValue":
+      return "unsupported value in CBOR header";
+    case "NonCanonicalNumeric":
+      return "a CBOR numeric value was encoded in non-canonical form";
+    case "InvalidSimpleValue":
+      return "an invalid CBOR simple value was encountered";
+    case "InvalidString":
+      return `an invalidly-encoded UTF-8 string was encountered in the CBOR (${error.message})`;
+    case "NonCanonicalString":
+      return "a CBOR string was not encoded in Unicode Canonical Normalization Form C";
+    case "UnusedData":
+      return `the decoded CBOR had ${error.count} extra bytes at the end`;
+    case "MisorderedMapKey":
+      return "the decoded CBOR map has keys that are not in canonical order";
+    case "DuplicateMapKey":
+      return "the decoded CBOR map has a duplicate key";
+    case "MissingMapKey":
+      return "missing CBOR map key";
+    case "OutOfRange":
+      return "the CBOR numeric value could not be represented in the specified numeric type";
+    case "WrongType":
+      return "the decoded CBOR value was not the expected type";
+    case "WrongTag":
+      return `expected CBOR tag ${tagToString(error.expected)}, but got ${tagToString(error.actual)}`;
+    case "InvalidUtf8":
+      return `invalid UTF‑8 string: ${error.message}`;
+    case "InvalidDate":
+      return `invalid ISO 8601 date string: ${error.message}`;
+    case "Custom":
+      return error.message;
+  }
+};
+
+/**
+ * Result type matching Rust's `Result<T, Error>`.
+ *
+ * In TypeScript, we use a discriminated union for Result instead of
+ * try/catch for better type safety and Rust compatibility.
+ */
+export type Result<T> = { ok: true; value: T } | { ok: false; error: Error };
+
+/**
+ * Create a successful Result.
+ */
+export const Ok = <T>(value: T): Result<T> => ({
+  ok: true,
+  value,
+});
+
+/**
+ * Create a failed Result.
+ */
+export const Err = <T>(error: Error): Result<T> => ({
+  ok: false,
+  error,
+});
+
+/**
+ * Typed error class for all CBOR-related errors.
+ *
+ * Wraps the discriminated union Error type in a JavaScript Error object
+ * for proper error handling with stack traces.
+ *
+ * @example
+ * ```typescript
+ * throw new CborError({ type: 'Underrun' });
+ * throw new CborError({ type: 'WrongTag', expected: tag1, actual: tag2 });
+ * ```
+ */
+export class CborError extends Error {
+  /**
+   * The structured error information.
+   */
+  public readonly errorType: Error;
+
+  /**
+   * Create a new CborError.
+   *
+   * @param errorType - The discriminated union error type
+   * @param message - Optional custom message (defaults to errorToString(errorType))
+   */
+  constructor(errorType: Error, message?: string) {
+    super(message ?? errorToString(errorType));
+    this.name = "CborError";
+    this.errorType = errorType;
+
+    // Maintains proper stack trace for where error was thrown (V8 only)
+    if ("captureStackTrace" in Error) {
+      (
+        Error as {
+          captureStackTrace(target: object, constructor: typeof CborError): void;
+        }
+      ).captureStackTrace(this, CborError);
+    }
+  }
+
+  /**
+   * Check if an error is a CborError.
+   *
+   * @param error - Error to check
+   * @returns True if error is a CborError
+   */
+  static isCborError(error: unknown): error is CborError {
+    return error instanceof CborError;
+  }
+}