@bsv/sdk 1.9.24 → 1.9.29

package/docs/reference/primitives.md

@@ -1756,6 +1756,7 @@ export default class Point extends BasePoint {
     x: BigNumber | null;
     y: BigNumber | null;
     inf: boolean;
+    static _assertOnCurve(p: Point): Point 
     static fromDER(bytes: number[]): Point 
     static fromString(str: string): Point 
     static fromX(x: BigNumber | number | number[] | string, odd: boolean): Point 
@@ -4958,20 +4959,16 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 ## Functions
 
-| |
-| --- |
-| [AES](#function-aes) |
-| [AESGCM](#function-aesgcm) |
-| [AESGCMDecrypt](#function-aesgcmdecrypt) |
-| [assertValidHex](#function-assertvalidhex) |
-| [base64ToArray](#function-base64toarray) |
-| [ghash](#function-ghash) |
-| [normalizeHex](#function-normalizehex) |
-| [pbkdf2](#function-pbkdf2) |
-| [red](#function-red) |
-| [toArray](#function-toarray) |
-| [toBase64](#function-tobase64) |
-| [verifyNotNull](#function-verifynotnull) |
+| | |
+| --- | --- |
+| [AES](#function-aes) | [pbkdf2](#function-pbkdf2) |
+| [AESGCM](#function-aesgcm) | [realHtonl](#function-realhtonl) |
+| [AESGCMDecrypt](#function-aesgcmdecrypt) | [red](#function-red) |
+| [assertValidHex](#function-assertvalidhex) | [swapBytes32](#function-swapbytes32) |
+| [base64ToArray](#function-base64toarray) | [toArray](#function-toarray) |
+| [ghash](#function-ghash) | [toBase64](#function-tobase64) |
+| [htonl](#function-htonl) | [verifyNotNull](#function-verifynotnull) |
+| [normalizeHex](#function-normalizehex) |  |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
@@ -4988,10 +4985,56 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 ### Function: AESGCM
 
-```ts
-export function AESGCM(plainText: number[], additionalAuthenticatedData: number[], initializationVector: number[], key: number[]): {
-    result: number[];
-    authenticationTag: number[];
+SECURITY NOTE – NON-STANDARD AES-GCM PADDING
+
+This implementation intentionally deviates from NIST SP 800-38D’s AES-GCM
+specification in how the GHASH input is formed when the additional
+authenticated data (AAD) or ciphertext length is zero.
+
+In the standard, AAD and ciphertext are each padded with the minimum number
+of zero bytes required to reach a multiple of 16 bytes; when the length is
+already a multiple of 16 (including the case length = 0), no padding block
+is added. In this implementation, when AAD.length === 0 or ciphertext.length
+=== 0, an extra 16-byte block of zeros is appended before the length fields
+are processed. The same formatting logic is used symmetrically in both
+AESGCM (encryption) and AESGCMDecrypt (decryption).
+
+As a result:
+  - Authentication tags produced here are NOT compatible with tags produced
+    by standards-compliant AES-GCM implementations in the cases where AAD
+    or ciphertext are empty.
+  - Ciphertexts generated by this code must be decrypted by this exact
+    implementation (or one that reproduces the same GHASH formatting), and
+    must not be mixed with ciphertexts produced by a strictly standard
+    AES-GCM library.
+
+Cryptographic impact: this change alters only the encoding of the message
+that is input to GHASH; it does not change the block cipher, key derivation,
+IV handling, or the basic “encrypt-then-MAC over (AAD, ciphertext, lengths)”
+structure of AES-GCM. Under the usual assumptions that AES is a secure block
+cipher and GHASH with a secret subkey is a secure polynomial MAC, this
+variant continues to provide confidentiality and integrity for data encrypted
+and decrypted consistently with this implementation. We are not aware of any
+attack that exploits the presence of this extra zero block when AAD or
+ciphertext are empty.
+
+However, this padding behavior is non-compliant with NIST SP 800-38D and has
+not been analyzed as extensively as standard AES-GCM. Code that requires
+strict standards compliance or interoperability with external AES-GCM
+implementations SHOULD NOT use this module as-is. Any future migration to a
+fully compliant AES-GCM encoding will require a compatibility strategy, as
+existing ciphertexts produced by this implementation will otherwise become
+undecryptable.
+
+This non-standard padding behavior is retained intentionally for backward
+compatibility: existing ciphertexts in production were generated with this
+encoding, and changing it would render previously encrypted data
+undecryptable by newer versions of the library.
+
+```ts
+export function AESGCM(plainText: Bytes, initializationVector: Bytes, key: Bytes): {
+    result: Bytes;
+    authenticationTag: Bytes;
 } 
 ```
 
@@ -5001,7 +5044,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Function: AESGCMDecrypt
 
 ```ts
-export function AESGCMDecrypt(cipherText: number[], additionalAuthenticatedData: number[], initializationVector: number[], authenticationTag: number[], key: number[]): number[] | null 
+export function AESGCMDecrypt(cipherText: Bytes, initializationVector: Bytes, authenticationTag: Bytes, key: Bytes): Bytes | null 
 ```
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
@@ -5028,7 +5071,16 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Function: ghash
 
 ```ts
-export function ghash(input: number[], hashSubKey: number[]): number[] 
+export function ghash(input: Bytes, hashSubKey: Bytes): Bytes 
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Function: htonl
+
+```ts
+export function htonl(w: number): number 
 ```
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
@@ -5070,6 +5122,42 @@ Argument Details
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
+---
+### Function: realHtonl
+
+Converts a 32-bit unsigned integer from host byte order to network byte order.
+
+Unlike the legacy `htonl()` implementation (which always swapped bytes),
+this function behaves like the traditional C `htonl()`:
+
+- On **little-endian** machines → performs a byte swap.
+- On **big-endian** machines → returns the value unchanged.
+
+This function is provided to resolve TOB-20, which identified that the
+previous `htonl()` implementation had a misleading name and did not match
+platform-dependent semantics.
+
+Example
+
+```ts
+realHtonl(0x11223344) // → 0x44332211 on little-endian systems
+```
+
+```ts
+export function realHtonl(w: number): number 
+```
+
+Returns
+
+The value converted to network byte order.
+
+Argument Details
+
++ **w**
+  + A 32-bit unsigned integer.
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
 ---
 ### Function: red
 
@@ -5079,6 +5167,41 @@ export function red(x: bigint): bigint
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
+---
+### Function: swapBytes32
+
+Unconditionally swaps the byte order of a 32-bit unsigned integer.
+
+This function performs a strict 32-bit byte swap regardless of host
+endianness. It is equivalent to the behavior commonly referred to as
+`bswap32` in low-level libraries.
+
+This function is introduced as part of TOB-20 to provide a clearly-named
+alternative to `htonl()`, which was previously implemented as an
+unconditional byte swap and did not match the semantics of the traditional
+C `htonl()` function.
+
+Example
+
+```ts
+swapBytes32(0x11223344) // → 0x44332211
+```
+
+```ts
+export function swapBytes32(w: number): number 
+```
+
+Returns
+
+The value with its byte order reversed.
+
+Argument Details
+
++ **w**
+  + A 32-bit unsigned integer.
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
 ---
 ### Function: toArray
 
@@ -5177,24 +5300,24 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | | | |
 | --- | --- | --- |
-| [BI_EIGHT](#variable-bi_eight) | [biModSqrt](#variable-bimodsqrt) | [multiply](#variable-multiply) |
-| [BI_FOUR](#variable-bi_four) | [biModSub](#variable-bimodsub) | [rightShift](#variable-rightshift) |
-| [BI_ONE](#variable-bi_one) | [checkBit](#variable-checkbit) | [ripemd160](#variable-ripemd160) |
-| [BI_THREE](#variable-bi_three) | [encode](#variable-encode) | [scalarMultiplyWNAF](#variable-scalarmultiplywnaf) |
-| [BI_TWO](#variable-bi_two) | [exclusiveOR](#variable-exclusiveor) | [sha1](#variable-sha1) |
-| [BI_ZERO](#variable-bi_zero) | [fromBase58](#variable-frombase58) | [sha256](#variable-sha256) |
-| [GX_BIGINT](#variable-gx_bigint) | [fromBase58Check](#variable-frombase58check) | [sha256hmac](#variable-sha256hmac) |
-| [GY_BIGINT](#variable-gy_bigint) | [getBytes](#variable-getbytes) | [sha512](#variable-sha512) |
-| [MASK_256](#variable-mask_256) | [hash160](#variable-hash160) | [sha512hmac](#variable-sha512hmac) |
-| [N_BIGINT](#variable-n_bigint) | [hash256](#variable-hash256) | [sign](#variable-sign) |
-| [P_BIGINT](#variable-p_bigint) | [incrementLeastSignificantThirtyTwoBits](#variable-incrementleastsignificantthirtytwobits) | [toArray](#variable-toarray) |
-| [P_PLUS1_DIV4](#variable-p_plus1_div4) | [jpAdd](#variable-jpadd) | [toBase58](#variable-tobase58) |
-| [biMod](#variable-bimod) | [jpDouble](#variable-jpdouble) | [toBase58Check](#variable-tobase58check) |
-| [biModAdd](#variable-bimodadd) | [jpNeg](#variable-jpneg) | [toHex](#variable-tohex) |
-| [biModInv](#variable-bimodinv) | [minimallyEncode](#variable-minimallyencode) | [toUTF8](#variable-toutf8) |
-| [biModMul](#variable-bimodmul) | [modInvN](#variable-modinvn) | [verify](#variable-verify) |
-| [biModPow](#variable-bimodpow) | [modMulN](#variable-modmuln) | [zero2](#variable-zero2) |
-| [biModSqr](#variable-bimodsqr) | [modN](#variable-modn) |  |
+| [BI_EIGHT](#variable-bi_eight) | [biModSqrt](#variable-bimodsqrt) | [modN](#variable-modn) |
+| [BI_FOUR](#variable-bi_four) | [biModSub](#variable-bimodsub) | [multiply](#variable-multiply) |
+| [BI_ONE](#variable-bi_one) | [checkBit](#variable-checkbit) | [rightShift](#variable-rightshift) |
+| [BI_THREE](#variable-bi_three) | [encode](#variable-encode) | [ripemd160](#variable-ripemd160) |
+| [BI_TWO](#variable-bi_two) | [exclusiveOR](#variable-exclusiveor) | [scalarMultiplyWNAF](#variable-scalarmultiplywnaf) |
+| [BI_ZERO](#variable-bi_zero) | [fromBase58](#variable-frombase58) | [sha1](#variable-sha1) |
+| [GX_BIGINT](#variable-gx_bigint) | [fromBase58Check](#variable-frombase58check) | [sha256](#variable-sha256) |
+| [GY_BIGINT](#variable-gy_bigint) | [getBytes](#variable-getbytes) | [sha256hmac](#variable-sha256hmac) |
+| [MASK_256](#variable-mask_256) | [getBytes64](#variable-getbytes64) | [sha512](#variable-sha512) |
+| [N_BIGINT](#variable-n_bigint) | [hash160](#variable-hash160) | [sha512hmac](#variable-sha512hmac) |
+| [P_BIGINT](#variable-p_bigint) | [hash256](#variable-hash256) | [sign](#variable-sign) |
+| [P_PLUS1_DIV4](#variable-p_plus1_div4) | [incrementLeastSignificantThirtyTwoBits](#variable-incrementleastsignificantthirtytwobits) | [toArray](#variable-toarray) |
+| [biMod](#variable-bimod) | [jpAdd](#variable-jpadd) | [toBase58](#variable-tobase58) |
+| [biModAdd](#variable-bimodadd) | [jpDouble](#variable-jpdouble) | [toBase58Check](#variable-tobase58check) |
+| [biModInv](#variable-bimodinv) | [jpNeg](#variable-jpneg) | [toHex](#variable-tohex) |
+| [biModMul](#variable-bimodmul) | [minimallyEncode](#variable-minimallyencode) | [toUTF8](#variable-toutf8) |
+| [biModPow](#variable-bimodpow) | [modInvN](#variable-modinvn) | [verify](#variable-verify) |
+| [biModSqr](#variable-bimodsqr) | [modMulN](#variable-modmuln) | [zero2](#variable-zero2) |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
@@ -5369,20 +5492,20 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ```ts
 biModPow = (base: bigint, exp: bigint): bigint => {
-    let result = BI_ONE;
+    let result = 1n;
     base = biMod(base);
-    let e = exp;
-    while (e > BI_ZERO) {
-        if ((e & BI_ONE) === BI_ONE)
+    while (exp > 0n) {
+        if ((exp & 1n) !== 0n) {
             result = biModMul(result, base);
+        }
         base = biModMul(base, base);
-        e >>= BI_ONE;
+        exp >>= 1n;
     }
     return result;
 }
 ```
 
-See also: [BI_ONE](./primitives.md#variable-bi_one), [BI_ZERO](./primitives.md#variable-bi_zero), [biMod](./primitives.md#variable-bimod), [biModMul](./primitives.md#variable-bimodmul)
+See also: [biMod](./primitives.md#variable-bimod), [biModMul](./primitives.md#variable-bimodmul)
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
@@ -5403,7 +5526,10 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ```ts
 biModSqrt = (a: bigint): bigint | null => {
     const r = biModPow(a, P_PLUS1_DIV4);
-    return biModMul(r, r) === biMod(a) ? r : null;
+    if (biModMul(r, r) !== biMod(a)) {
+        return null;
+    }
+    return r;
 }
 ```
 
@@ -5457,11 +5583,11 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Variable: exclusiveOR
 
 ```ts
-exclusiveOR = function (block0: number[], block1: number[]): number[] {
+exclusiveOR = function (block0: Bytes, block1: Bytes): Bytes {
     const len = block0.length;
-    const result = new Array(len);
+    const result = new Uint8Array(len);
     for (let i = 0; i < len; i++) {
-        result[i] = block0[i] ^ block1[i];
+        result[i] = block0[i] ^ (block1[i] ?? 0);
     }
     return result;
 }
@@ -5551,6 +5677,31 @@ getBytes = function (numericValue: number): number[] {
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
+---
+### Variable: getBytes64
+
+```ts
+getBytes64 = function (numericValue: number): number[] {
+    if (numericValue < 0 || numericValue > Number.MAX_SAFE_INTEGER) {
+        throw new Error("getBytes64: value out of range");
+    }
+    const hi = Math.floor(numericValue / 4294967296);
+    const lo = numericValue >>> 0;
+    return [
+        (hi >>> 24) & 255,
+        (hi >>> 16) & 255,
+        (hi >>> 8) & 255,
+        hi & 255,
+        (lo >>> 24) & 255,
+        (lo >>> 16) & 255,
+        (lo >>> 8) & 255,
+        lo & 255
+    ];
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
 ---
 ### Variable: hash160
 
@@ -5583,15 +5734,11 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Variable: incrementLeastSignificantThirtyTwoBits
 
 ```ts
-incrementLeastSignificantThirtyTwoBits = function (block: number[]): number[] {
-    let i;
+incrementLeastSignificantThirtyTwoBits = function (block: Bytes): Bytes {
     const result = block.slice();
-    for (i = 15; i !== 11; i--) {
-        result[i] = result[i] + 1;
-        if (result[i] === 256) {
-            result[i] = 0;
-        }
-        else {
+    for (let i = 15; i !== 11; i--) {
+        result[i] = (result[i] + 1) & 255;
+        if (result[i] !== 0) {
             break;
         }
     }
@@ -5763,7 +5910,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Variable: multiply
 
 ```ts
-multiply = function (block0: number[], block1: number[]): number[] {
+multiply = function (block0: Bytes, block1: Bytes): Bytes {
     const v = block1.slice();
     const z = createZeroBlock(16);
     for (let i = 0; i < 16; i++) {
@@ -5792,11 +5939,10 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Variable: rightShift
 
 ```ts
-rightShift = function (block: number[]): number[] {
-    let i: number;
+rightShift = function (block: Bytes): Bytes {
     let carry = 0;
     let oldCarry = 0;
-    for (i = 0; i < block.length; i++) {
+    for (let i = 0; i < block.length; i++) {
         oldCarry = carry;
         carry = block[i] & 1;
         block[i] = block[i] >> 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.9.24",
+  "version": "1.9.29",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",