@bcts/dcbor 1.0.0-alpha.16 → 1.0.0-alpha.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bcts/dcbor",
-  "version": "1.0.0-alpha.16",
+  "version": "1.0.0-alpha.18",
   "type": "module",
   "description": "Blockchain Commons Deterministic CBOR (dCBOR) for TypeScript",
   "license": "BSD-2-Clause-Patent",
@@ -71,15 +71,15 @@
     "@bcts/tsconfig": "^0.1.0",
     "@eslint/js": "^9.39.2",
     "@types/collections": "^5.1.5",
-    "@types/node": "^25.0.6",
-    "@typescript-eslint/eslint-plugin": "^8.52.0",
-    "@typescript-eslint/parser": "^8.52.0",
+    "@types/node": "^25.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
     "eslint": "^9.39.2",
     "ts-node": "^10.9.2",
-    "tsdown": "^0.18.4",
-    "typedoc": "^0.28.15",
+    "tsdown": "^0.20.1",
+    "typedoc": "^0.28.16",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.18"
   },
   "dependencies": {
     "byte-data": "^19.0.1",

package/src/bignum.ts

@@ -0,0 +1,334 @@
+/**
+ * CBOR bignum (tags 2 and 3) support.
+ *
+ * This module provides conversion between CBOR and JavaScript BigInt types,
+ * implementing RFC 8949 §3.4.3 (Bignums) with dCBOR/CDE canonical encoding rules.
+ *
+ * Encoding:
+ * - `biguintToCbor` always encodes as tag 2 (positive bignum) with a byte
+ *   string content.
+ * - `bigintToCbor` encodes as tag 2 for non-negative values or tag 3
+ *   (negative bignum) for negative values.
+ * - No numeric reduction is performed: values are always encoded as bignums,
+ *   even if they would fit in normal CBOR integers.
+ *
+ * Decoding:
+ * - Accepts CBOR integers (major types 0 and 1) and converts them to bigints.
+ * - Accepts tag 2 (positive bignum) and tag 3 (negative bignum) with byte
+ *   string content.
+ * - Enforces shortest-form canonical representation for bignum magnitudes.
+ * - Rejects floating-point values.
+ *
+ * @module bignum
+ */
+
+import { type Cbor, MajorType, toTaggedValue } from "./cbor";
+import { CborError } from "./error";
+
+// CBOR tag values (local constants matching tags.ts, avoiding circular import)
+const TAG_2_POSITIVE_BIGNUM = 2;
+const TAG_3_NEGATIVE_BIGNUM = 3;
+
+/**
+ * Validates that a bignum magnitude byte string is in shortest canonical form.
+ *
+ * Matches Rust's `validate_bignum_magnitude()`.
+ *
+ * Rules:
+ * - For positive bignums (tag 2): empty byte string represents zero;
+ *   non-empty must not have leading zero bytes.
+ * - For negative bignums (tag 3): byte string must not be empty
+ *   (magnitude zero is encoded as `0x00`); must not have leading zero bytes
+ *   except when the magnitude is zero (single `0x00`).
+ *
+ * @param bytes - The magnitude byte string to validate
+ * @param isNegative - Whether this is for a negative bignum (tag 3)
+ * @throws CborError with type NonCanonicalNumeric on validation failure
+ */
+export function validateBignumMagnitude(bytes: Uint8Array, isNegative: boolean): void {
+  if (isNegative) {
+    // Tag 3: byte string must not be empty
+    if (bytes.length === 0) {
+      throw new CborError({ type: "NonCanonicalNumeric" });
+    }
+    // No leading zeros unless the entire magnitude is zero (single 0x00 byte)
+    if (bytes.length > 1 && bytes[0] === 0) {
+      throw new CborError({ type: "NonCanonicalNumeric" });
+    }
+  } else {
+    // Tag 2: empty byte string is valid (represents zero)
+    // Non-empty must not have leading zeros
+    if (bytes.length > 0 && bytes[0] === 0) {
+      throw new CborError({ type: "NonCanonicalNumeric" });
+    }
+  }
+}
+
+/**
+ * Strips leading zero bytes from a byte array, returning the minimal
+ * representation.
+ *
+ * Matches Rust's `strip_leading_zeros()`.
+ *
+ * @param bytes - The byte array to strip
+ * @returns A subarray with leading zeros removed
+ */
+export function stripLeadingZeros(bytes: Uint8Array): Uint8Array {
+  let start = 0;
+  while (start < bytes.length && bytes[start] === 0) {
+    start++;
+  }
+  return bytes.subarray(start);
+}
+
+/**
+ * Convert a non-negative bigint to a big-endian byte array.
+ *
+ * Zero returns an empty Uint8Array.
+ *
+ * @param value - A non-negative bigint value
+ * @returns Big-endian byte representation
+ */
+export function bigintToBytes(value: bigint): Uint8Array {
+  if (value === 0n) return new Uint8Array(0);
+  const hex = value.toString(16);
+  const padded = hex.length % 2 !== 0 ? `0${hex}` : hex;
+  const bytes = new Uint8Array(padded.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(padded.substring(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Convert a big-endian byte array to a bigint.
+ *
+ * Empty array returns 0n.
+ *
+ * @param bytes - Big-endian byte representation
+ * @returns The bigint value
+ */
+export function bytesToBigint(bytes: Uint8Array): bigint {
+  if (bytes.length === 0) return 0n;
+  let result = 0n;
+  for (const byte of bytes) {
+    result = (result << 8n) | BigInt(byte);
+  }
+  return result;
+}
+
+/**
+ * Encode a non-negative bigint as a CBOR tag 2 (positive bignum).
+ *
+ * Matches Rust's `From<BigUint> for CBOR`.
+ *
+ * The value is always encoded as a bignum regardless of size.
+ * Zero is encoded as tag 2 with an empty byte string.
+ *
+ * @param value - A non-negative bigint (must be >= 0n)
+ * @returns CBOR tagged value
+ * @throws CborError with type OutOfRange if value is negative
+ */
+export function biguintToCbor(value: bigint): Cbor {
+  if (value < 0n) {
+    throw new CborError({ type: "OutOfRange" });
+  }
+  const bytes = bigintToBytes(value);
+  const stripped = stripLeadingZeros(bytes);
+  return toTaggedValue(TAG_2_POSITIVE_BIGNUM, stripped);
+}
+
+/**
+ * Encode a bigint as a CBOR tag 2 or tag 3 bignum.
+ *
+ * Matches Rust's `From<BigInt> for CBOR`.
+ *
+ * - Non-negative values use tag 2 (positive bignum).
+ * - Negative values use tag 3 (negative bignum), where the encoded
+ *   magnitude is `|value| - 1` per RFC 8949.
+ *
+ * @param value - Any bigint value
+ * @returns CBOR tagged value
+ */
+export function bigintToCbor(value: bigint): Cbor {
+  if (value >= 0n) {
+    return biguintToCbor(value);
+  }
+  // Negative: use tag 3 with magnitude = |value| - 1
+  // For value = -1, magnitude = 1, so n = 0 -> encode as 0x00
+  // For value = -2, magnitude = 2, so n = 1 -> encode as 0x01
+  const magnitude = -value;
+  const n = magnitude - 1n;
+  const bytes = bigintToBytes(n);
+  const stripped = stripLeadingZeros(bytes);
+  // For n = 0 (value = -1), bigintToBytes returns empty, but we need 0x00
+  const contentBytes = stripped.length === 0 ? new Uint8Array([0]) : stripped;
+  return toTaggedValue(TAG_3_NEGATIVE_BIGNUM, contentBytes);
+}
+
+/**
+ * Decode a BigUint from an untagged CBOR byte string.
+ *
+ * Matches Rust's `biguint_from_untagged_cbor()`.
+ *
+ * This function is intended for use in tag summarizers where the tag has
+ * already been stripped. It expects a CBOR byte string representing the
+ * big-endian magnitude of a positive bignum (tag 2 content).
+ *
+ * Enforces canonical encoding: no leading zero bytes (except empty for zero).
+ *
+ * @param cbor - A CBOR value that should be a byte string
+ * @returns Non-negative bigint
+ * @throws CborError with type WrongType if not a byte string
+ * @throws CborError with type NonCanonicalNumeric if encoding is non-canonical
+ */
+export function biguintFromUntaggedCbor(cbor: Cbor): bigint {
+  if (cbor.type !== MajorType.ByteString) {
+    throw new CborError({ type: "WrongType" });
+  }
+  const bytes = cbor.value;
+  validateBignumMagnitude(bytes, false);
+  return bytesToBigint(bytes);
+}
+
+/**
+ * Decode a BigInt from an untagged CBOR byte string for a negative bignum.
+ *
+ * Matches Rust's `bigint_from_negative_untagged_cbor()`.
+ *
+ * This function is intended for use in tag summarizers where the tag has
+ * already been stripped. It expects a CBOR byte string representing `n` where
+ * the actual value is `-1 - n` (tag 3 content per RFC 8949).
+ *
+ * Enforces canonical encoding: no leading zero bytes (except single `0x00`
+ * for -1).
+ *
+ * @param cbor - A CBOR value that should be a byte string
+ * @returns Negative bigint
+ * @throws CborError with type WrongType if not a byte string
+ * @throws CborError with type NonCanonicalNumeric if encoding is non-canonical
+ */
+export function bigintFromNegativeUntaggedCbor(cbor: Cbor): bigint {
+  if (cbor.type !== MajorType.ByteString) {
+    throw new CborError({ type: "WrongType" });
+  }
+  const bytes = cbor.value;
+  validateBignumMagnitude(bytes, true);
+  const n = bytesToBigint(bytes);
+  const magnitude = n + 1n;
+  return -magnitude;
+}
+
+/**
+ * Convert CBOR to a non-negative bigint.
+ *
+ * Matches Rust's `TryFrom<CBOR> for BigUint`.
+ *
+ * Accepts:
+ * - Major type 0 (unsigned integer)
+ * - Tag 2 (positive bignum) with canonical byte string
+ *
+ * Rejects:
+ * - Major type 1 (negative integer) -> OutOfRange
+ * - Tag 3 (negative bignum) -> OutOfRange
+ * - Floating-point values -> WrongType
+ * - Non-canonical bignum encodings -> NonCanonicalNumeric
+ *
+ * @param cbor - The CBOR value to convert
+ * @returns Non-negative bigint
+ * @throws CborError
+ */
+export function cborToBiguint(cbor: Cbor): bigint {
+  switch (cbor.type) {
+    case MajorType.Unsigned:
+      return BigInt(cbor.value);
+    case MajorType.Negative:
+      throw new CborError({ type: "OutOfRange" });
+    case MajorType.Tagged: {
+      const tagValue = Number(cbor.tag);
+      if (tagValue === TAG_2_POSITIVE_BIGNUM) {
+        const inner = cbor.value;
+        if (inner.type !== MajorType.ByteString) {
+          throw new CborError({ type: "WrongType" });
+        }
+        const bytes = inner.value;
+        validateBignumMagnitude(bytes, false);
+        return bytesToBigint(bytes);
+      } else if (tagValue === TAG_3_NEGATIVE_BIGNUM) {
+        throw new CborError({ type: "OutOfRange" });
+      }
+      throw new CborError({ type: "WrongType" });
+    }
+    case MajorType.ByteString:
+    case MajorType.Text:
+    case MajorType.Array:
+    case MajorType.Map:
+    case MajorType.Simple:
+      throw new CborError({ type: "WrongType" });
+  }
+}
+
+/**
+ * Convert CBOR to a bigint (any sign).
+ *
+ * Matches Rust's `TryFrom<CBOR> for BigInt`.
+ *
+ * Accepts:
+ * - Major type 0 (unsigned integer)
+ * - Major type 1 (negative integer)
+ * - Tag 2 (positive bignum) with canonical byte string
+ * - Tag 3 (negative bignum) with canonical byte string
+ *
+ * Rejects:
+ * - Floating-point values -> WrongType
+ * - Non-canonical bignum encodings -> NonCanonicalNumeric
+ *
+ * @param cbor - The CBOR value to convert
+ * @returns A bigint value
+ * @throws CborError
+ */
+export function cborToBigint(cbor: Cbor): bigint {
+  switch (cbor.type) {
+    case MajorType.Unsigned:
+      return BigInt(cbor.value);
+    case MajorType.Negative: {
+      // CBOR negative: value stored is n where actual = -1 - n
+      const n = BigInt(cbor.value);
+      const magnitude = n + 1n;
+      return -magnitude;
+    }
+    case MajorType.Tagged: {
+      const tagValue = Number(cbor.tag);
+      if (tagValue === TAG_2_POSITIVE_BIGNUM) {
+        const inner = cbor.value;
+        if (inner.type !== MajorType.ByteString) {
+          throw new CborError({ type: "WrongType" });
+        }
+        const bytes = inner.value;
+        validateBignumMagnitude(bytes, false);
+        const mag = bytesToBigint(bytes);
+        if (mag === 0n) {
+          return 0n;
+        }
+        return mag;
+      } else if (tagValue === TAG_3_NEGATIVE_BIGNUM) {
+        const inner = cbor.value;
+        if (inner.type !== MajorType.ByteString) {
+          throw new CborError({ type: "WrongType" });
+        }
+        const bytes = inner.value;
+        validateBignumMagnitude(bytes, true);
+        const n = bytesToBigint(bytes);
+        const magnitude = n + 1n;
+        return -magnitude;
+      }
+      throw new CborError({ type: "WrongType" });
+    }
+    case MajorType.ByteString:
+    case MajorType.Text:
+    case MajorType.Array:
+    case MajorType.Map:
+    case MajorType.Simple:
+      throw new CborError({ type: "WrongType" });
+  }
+}

package/src/byte-string.ts

@@ -44,7 +44,7 @@ import { CborError } from "./error";
  * ```
  */
 export class ByteString {
-  #data: Uint8Array;
+  private _data: Uint8Array;
 
   /**
    * Creates a new `ByteString` from a Uint8Array or array of bytes.
@@ -62,9 +62,9 @@ export class ByteString {
    */
   constructor(data: Uint8Array | number[]) {
     if (Array.isArray(data)) {
-      this.#data = new Uint8Array(data);
+      this._data = new Uint8Array(data);
     } else {
-      this.#data = new Uint8Array(data);
+      this._data = new Uint8Array(data);
     }
   }
 
@@ -103,7 +103,7 @@ export class ByteString {
    * ```
    */
   data(): Uint8Array {
-    return this.#data;
+    return this._data;
   }
 
   /**
@@ -121,7 +121,7 @@ export class ByteString {
    * ```
    */
   len(): number {
-    return this.#data.length;
+    return this._data.length;
   }
 
   /**
@@ -139,7 +139,7 @@ export class ByteString {
    * ```
    */
   isEmpty(): boolean {
-    return this.#data.length === 0;
+    return this._data.length === 0;
   }
 
   /**
@@ -160,10 +160,10 @@ export class ByteString {
    */
   extend(other: Uint8Array | number[]): void {
     const otherArray = Array.isArray(other) ? new Uint8Array(other) : other;
-    const newData = new Uint8Array(this.#data.length + otherArray.length);
-    newData.set(this.#data, 0);
-    newData.set(otherArray, this.#data.length);
-    this.#data = newData;
+    const newData = new Uint8Array(this._data.length + otherArray.length);
+    newData.set(this._data, 0);
+    newData.set(otherArray, this._data.length);
+    this._data = newData;
   }
 
   /**
@@ -184,7 +184,7 @@ export class ByteString {
    * ```
    */
   toUint8Array(): Uint8Array {
-    return new Uint8Array(this.#data);
+    return new Uint8Array(this._data);
   }
 
   /**
@@ -211,7 +211,7 @@ export class ByteString {
    * ```
    */
   iter(): Iterator<number> {
-    return this.#data.values();
+    return this._data.values();
   }
 
   /**
@@ -233,7 +233,7 @@ export class ByteString {
    * ```
    */
   toCbor(): Cbor {
-    return toCbor(this.#data);
+    return toCbor(this._data);
   }
 
   /**
@@ -272,7 +272,7 @@ export class ByteString {
    * @returns Byte at index or undefined
    */
   at(index: number): number | undefined {
-    return this.#data[index];
+    return this._data[index];
   }
 
   /**
@@ -282,9 +282,9 @@ export class ByteString {
    * @returns true if equal
    */
   equals(other: ByteString): boolean {
-    if (this.#data.length !== other.#data.length) return false;
-    for (let i = 0; i < this.#data.length; i++) {
-      if (this.#data[i] !== other.#data[i]) return false;
+    if (this._data.length !== other._data.length) return false;
+    for (let i = 0; i < this._data.length; i++) {
+      if (this._data[i] !== other._data[i]) return false;
     }
     return true;
   }

package/src/date.ts

@@ -67,7 +67,7 @@ import { CborError } from "./error";
  * ```
  */
 export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDecodable<CborDate> {
-  #datetime: Date;
+  private _datetime: Date;
 
   /**
    * Creates a new `CborDate` from the given JavaScript `Date`.
@@ -87,7 +87,7 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
    */
   static fromDatetime(dateTime: Date): CborDate {
     const instance = new CborDate();
-    instance.#datetime = new Date(dateTime);
+    instance._datetime = new Date(dateTime);
     return instance;
   }
 
@@ -265,7 +265,7 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
    * ```
    */
   datetime(): Date {
-    return new Date(this.#datetime);
+    return new Date(this._datetime);
   }
 
   /**
@@ -285,8 +285,8 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
    * ```
    */
   timestamp(): number {
-    const wholeSecondsSinceUnixEpoch = Math.trunc(this.#datetime.getTime() / 1000);
-    const msecs = this.#datetime.getTime() % 1000;
+    const wholeSecondsSinceUnixEpoch = Math.trunc(this._datetime.getTime() / 1000);
+    const msecs = this._datetime.getTime() % 1000;
     return wholeSecondsSinceUnixEpoch + msecs / 1000.0;
   }
 
@@ -430,7 +430,7 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
     }
 
     const date = CborDate.fromTimestamp(timestamp);
-    this.#datetime = date.#datetime;
+    this._datetime = date._datetime;
     return this;
   }
 
@@ -495,7 +495,7 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
    * ```
    */
   toString(): string {
-    const dt = this.#datetime;
+    const dt = this._datetime;
     // Check only hours, minutes, and seconds (not milliseconds) to match Rust behavior
     const hasTime = dt.getUTCHours() !== 0 || dt.getUTCMinutes() !== 0 || dt.getUTCSeconds() !== 0;
 
@@ -521,7 +521,7 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
    * @returns true if dates represent the same moment in time
    */
   equals(other: CborDate): boolean {
-    return this.#datetime.getTime() === other.#datetime.getTime();
+    return this._datetime.getTime() === other._datetime.getTime();
   }
 
   /**
@@ -531,8 +531,8 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
    * @returns -1 if this < other, 0 if equal, 1 if this > other
    */
   compare(other: CborDate): number {
-    const thisTime = this.#datetime.getTime();
-    const otherTime = other.#datetime.getTime();
+    const thisTime = this._datetime.getTime();
+    const otherTime = other._datetime.getTime();
     if (thisTime < otherTime) return -1;
     if (thisTime > otherTime) return 1;
     return 0;
@@ -548,6 +548,6 @@ export class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDeco
   }
 
   private constructor() {
-    this.#datetime = new Date();
+    this._datetime = new Date();
   }
 }

package/src/index.ts

@@ -88,6 +88,16 @@ export { type Error, type Result, Ok, Err, errorMsg, errorToString, CborError }
 // Note: conveniences.ts is an internal module (not exported in Rust either)
 // The main convenience functions are exported from cbor.ts above
 
+// BigNum support (CBOR tags 2/3, RFC 8949 §3.4.3)
+export {
+  biguintToCbor,
+  bigintToCbor,
+  cborToBiguint,
+  cborToBigint,
+  biguintFromUntaggedCbor,
+  bigintFromNegativeUntaggedCbor,
+} from "./bignum";
+
 // Float utilities
 export { hasFractionalPart } from "./float";