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

package/dist/index.mjs

@@ -8044,6 +8044,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
 /**
@@ -8073,6 +8335,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;
@@ -8163,6 +8435,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.
@@ -8889,5 +9196,5 @@ var ByteString = class ByteString {
 };
 
 //#endregion
-export { ByteString, Cbor, CborDate, CborError, CborMap, CborSet, Err, MajorType, Ok, TAG_BASE16, TAG_BASE64, TAG_BASE64URL, TAG_BASE64URL_TEXT, TAG_BASE64_TEXT, TAG_BIGFLOAT, TAG_BINARY_UUID, TAG_DATE, TAG_DATE_TIME_STRING, TAG_DECIMAL_FRACTION, TAG_ENCODED_CBOR, TAG_EPOCH_DATE, TAG_EPOCH_DATE_TIME, TAG_MIME_MESSAGE, TAG_NAME_DATE, TAG_NEGATIVE_BIGNUM, TAG_POSITIVE_BIGNUM, TAG_REGEXP, TAG_SELF_DESCRIBE_CBOR, TAG_SET, TAG_STRING_REF_NAMESPACE, TAG_URI, TAG_UUID, TagsStore, arrayIsEmpty, arrayItem, arrayLength, asArray, asBoolean, asByteString, asBytes, asCborArray, asCborMap, asFloat, asInteger, asKeyValue, asMap, asNegative, asNumber, asSingle, asTaggedValue, asText, asUnsigned, bytesToHex, cbor, cborData, createTag, createTaggedCbor, decodeCbor, decodeVarInt, decodeVarIntData, diagnosticOpt, edgeLabel, encodeVarInt, errorMsg, errorToString, expectArray, expectBoolean, expectBoolean as tryIntoBool, expectBytes, expectBytes as tryIntoByteString, expectFloat, expectInteger, expectMap, expectNegative, expectNumber, expectTaggedContent, expectTaggedContent as tryExpectedTaggedValue, expectText, expectText as tryIntoText, expectUnsigned, extractCbor, extractTaggedContent, getGlobalTagsStore, getTaggedContent, hasFractionalPart, hasTag, hexOpt, hexToBytes, isArray, isBoolean, isBytes, isFloat, isInteger, isMap, isNaN$1 as isNaN, isNegative, isNull, isNumber, isSimple, isTagged, isText, isUnsigned, mapHas, mapIsEmpty, mapKeys, mapSize, mapValue, mapValues, registerTags, registerTagsIn, simpleName, summary, tagContent, tagValue, tagsForValues, toByteString, toByteStringFromHex, toTaggedValue, validateTag, walk };
+export { ByteString, Cbor, CborDate, CborError, CborMap, CborSet, Err, MajorType, Ok, TAG_BASE16, TAG_BASE64, TAG_BASE64URL, TAG_BASE64URL_TEXT, TAG_BASE64_TEXT, TAG_BIGFLOAT, TAG_BINARY_UUID, TAG_DATE, TAG_DATE_TIME_STRING, TAG_DECIMAL_FRACTION, TAG_ENCODED_CBOR, TAG_EPOCH_DATE, TAG_EPOCH_DATE_TIME, TAG_MIME_MESSAGE, TAG_NAME_DATE, TAG_NAME_NEGATIVE_BIGNUM, TAG_NAME_POSITIVE_BIGNUM, TAG_NEGATIVE_BIGNUM, TAG_POSITIVE_BIGNUM, TAG_REGEXP, TAG_SELF_DESCRIBE_CBOR, TAG_SET, TAG_STRING_REF_NAMESPACE, TAG_URI, TAG_UUID, TagsStore, arrayIsEmpty, arrayItem, arrayLength, asArray, asBoolean, asByteString, asBytes, asCborArray, asCborMap, asFloat, asInteger, asKeyValue, asMap, asNegative, asNumber, asSingle, asTaggedValue, asText, asUnsigned, bigintFromNegativeUntaggedCbor, bigintToCbor, biguintFromUntaggedCbor, biguintToCbor, bytesToHex, cbor, cborData, cborToBigint, cborToBiguint, createTag, createTaggedCbor, decodeCbor, decodeVarInt, decodeVarIntData, diagnosticOpt, edgeLabel, encodeVarInt, errorMsg, errorToString, expectArray, expectBoolean, expectBoolean as tryIntoBool, expectBytes, expectBytes as tryIntoByteString, expectFloat, expectInteger, expectMap, expectNegative, expectNumber, expectTaggedContent, expectTaggedContent as tryExpectedTaggedValue, expectText, expectText as tryIntoText, expectUnsigned, extractCbor, extractTaggedContent, getGlobalTagsStore, getTaggedContent, hasFractionalPart, hasTag, hexOpt, hexToBytes, isArray, isBoolean, isBytes, isFloat, isInteger, isMap, isNaN$1 as isNaN, isNegative, isNull, isNumber, isSimple, isTagged, isText, isUnsigned, mapHas, mapIsEmpty, mapKeys, mapSize, mapValue, mapValues, registerTags, registerTagsIn, simpleName, summary, tagContent, tagValue, tagsForValues, toByteString, toByteStringFromHex, toTaggedValue, validateTag, walk };
 //# sourceMappingURL=index.mjs.map