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

package/README.md

@@ -10,4 +10,4 @@ The current specification of the norms and practices guiding the creation of thi
 
 ## Rust Reference Implementation
 
-This TypeScript implementation is based on [bc-dcbor-rust](https://github.com/BlockchainCommons/bc-dcbor-rust) **v0.24.1** ([commit](https://github.com/BlockchainCommons/bc-dcbor-rust/tree/012be742e89098d1e0630f1f480463b6bdd2e068)).
+This TypeScript implementation is based on [bc-dcbor-rust](https://github.com/BlockchainCommons/bc-dcbor-rust) **v0.25.1** ([commit](https://github.com/BlockchainCommons/bc-dcbor-rust/tree/8344a256cc858b3a626a89e0b805ef0bda4d3b50)).

package/dist/index.cjs

@@ -8045,6 +8045,268 @@ var CborDate = class CborDate {
 	}
 };
 
+//#endregion
+//#region src/bignum.ts
+/**
+* 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
+*/
+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
+*/
+function validateBignumMagnitude(bytes, isNegative) {
+	if (isNegative) {
+		if (bytes.length === 0) throw new CborError({ type: "NonCanonicalNumeric" });
+		if (bytes.length > 1 && bytes[0] === 0) throw new CborError({ type: "NonCanonicalNumeric" });
+	} else 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
+*/
+function stripLeadingZeros(bytes) {
+	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
+*/
+function bigintToBytes(value) {
+	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
+*/
+function bytesToBigint(bytes) {
+	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
+*/
+function biguintToCbor(value) {
+	if (value < 0n) throw new CborError({ type: "OutOfRange" });
+	return toTaggedValue(TAG_2_POSITIVE_BIGNUM, stripLeadingZeros(bigintToBytes(value)));
+}
+/**
+* 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
+*/
+function bigintToCbor(value) {
+	if (value >= 0n) return biguintToCbor(value);
+	const stripped = stripLeadingZeros(bigintToBytes(-value - 1n));
+	return toTaggedValue(TAG_3_NEGATIVE_BIGNUM, stripped.length === 0 ? new Uint8Array([0]) : stripped);
+}
+/**
+* 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
+*/
+function biguintFromUntaggedCbor(cbor) {
+	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
+*/
+function bigintFromNegativeUntaggedCbor(cbor) {
+	if (cbor.type !== MajorType.ByteString) throw new CborError({ type: "WrongType" });
+	const bytes = cbor.value;
+	validateBignumMagnitude(bytes, true);
+	return -(bytesToBigint(bytes) + 1n);
+}
+/**
+* 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
+*/
+function cborToBiguint(cbor) {
+	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
+*/
+function cborToBigint(cbor) {
+	switch (cbor.type) {
+		case MajorType.Unsigned: return BigInt(cbor.value);
+		case MajorType.Negative: return -(BigInt(cbor.value) + 1n);
+		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);
+				return -(bytesToBigint(bytes) + 1n);
+			}
+			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" });
+	}
+}
+
 //#endregion
 //#region src/tags.ts
 /**
@@ -8074,6 +8336,16 @@ const TAG_POSITIVE_BIGNUM = 2;
 */
 const TAG_NEGATIVE_BIGNUM = 3;
 /**
+* Name for tag 2 (positive bignum).
+* Matches Rust's `TAG_NAME_POSITIVE_BIGNUM`.
+*/
+const TAG_NAME_POSITIVE_BIGNUM = "positive-bignum";
+/**
+* Name for tag 3 (negative bignum).
+* Matches Rust's `TAG_NAME_NEGATIVE_BIGNUM`.
+*/
+const TAG_NAME_NEGATIVE_BIGNUM = "negative-bignum";
+/**
 * Tag 4: Decimal fraction [exponent, mantissa]
 */
 const TAG_DECIMAL_FRACTION = 4;
@@ -8164,6 +8436,41 @@ const registerTagsIn = (tagsStore) => {
 			};
 		}
 	});
+	const biguintTag = createTag(TAG_POSITIVE_BIGNUM, TAG_NAME_POSITIVE_BIGNUM);
+	const bigintTag = createTag(TAG_NEGATIVE_BIGNUM, TAG_NAME_NEGATIVE_BIGNUM);
+	tagsStore.insertAll([biguintTag, bigintTag]);
+	tagsStore.setSummarizer(TAG_POSITIVE_BIGNUM, (untaggedCbor, _flat) => {
+		try {
+			return {
+				ok: true,
+				value: `bignum(${biguintFromUntaggedCbor(untaggedCbor)})`
+			};
+		} catch (e) {
+			return {
+				ok: false,
+				error: {
+					type: "Custom",
+					message: e instanceof Error ? e.message : String(e)
+				}
+			};
+		}
+	});
+	tagsStore.setSummarizer(TAG_NEGATIVE_BIGNUM, (untaggedCbor, _flat) => {
+		try {
+			return {
+				ok: true,
+				value: `bignum(${bigintFromNegativeUntaggedCbor(untaggedCbor)})`
+			};
+		} catch (e) {
+			return {
+				ok: false,
+				error: {
+					type: "Custom",
+					message: e instanceof Error ? e.message : String(e)
+				}
+			};
+		}
+	});
 };
 /**
 * Register standard tags in the global tags store.
@@ -8914,6 +9221,8 @@ exports.TAG_EPOCH_DATE = TAG_EPOCH_DATE;
 exports.TAG_EPOCH_DATE_TIME = TAG_EPOCH_DATE_TIME;
 exports.TAG_MIME_MESSAGE = TAG_MIME_MESSAGE;
 exports.TAG_NAME_DATE = TAG_NAME_DATE;
+exports.TAG_NAME_NEGATIVE_BIGNUM = TAG_NAME_NEGATIVE_BIGNUM;
+exports.TAG_NAME_POSITIVE_BIGNUM = TAG_NAME_POSITIVE_BIGNUM;
 exports.TAG_NEGATIVE_BIGNUM = TAG_NEGATIVE_BIGNUM;
 exports.TAG_POSITIVE_BIGNUM = TAG_POSITIVE_BIGNUM;
 exports.TAG_REGEXP = TAG_REGEXP;
@@ -8942,9 +9251,15 @@ exports.asSingle = asSingle;
 exports.asTaggedValue = asTaggedValue;
 exports.asText = asText;
 exports.asUnsigned = asUnsigned;
+exports.bigintFromNegativeUntaggedCbor = bigintFromNegativeUntaggedCbor;
+exports.bigintToCbor = bigintToCbor;
+exports.biguintFromUntaggedCbor = biguintFromUntaggedCbor;
+exports.biguintToCbor = biguintToCbor;
 exports.bytesToHex = bytesToHex;
 exports.cbor = cbor;
 exports.cborData = cborData;
+exports.cborToBigint = cborToBigint;
+exports.cborToBiguint = cborToBiguint;
 exports.createTag = createTag;
 exports.createTaggedCbor = createTaggedCbor;
 exports.decodeCbor = decodeCbor;