fix(sdk): authenticate empty AES-GCM payloads in portable runtimes (#574)

Author: ty-everett

docs/packages/sdk/bsv-sdk.md

@@ -3,10 +3,10 @@ id: bsv-sdk
 title: '@bsv/sdk'
 kind: package
 domain: sdk
-version: '2.8.0'
+version: '2.8.1'
 npm: '@bsv/sdk'
-last_updated: '2026-09-21'
-last_verified: '2026-09-21'
+last_updated: '2026-09-23'
+last_verified: '2026-09-23'
 review_cadence_days: 30
 status: stable
 tags: ['sdk', 'crypto', 'transactions']
@@ -15,7 +15,13 @@ repo: 'https://github.com/bsv-blockchain/ts-stack/tree/main/packages/sdk'
 
 # @bsv/sdk
 
-The current unpublished candidate corrects BUMP offset arithmetic above 32 bits
+The 2.8.1 source candidate repairs portable decryption of authenticated empty
+AES-GCM plaintext. Browser/mobile and native Node envelopes now interoperate
+for empty encrypted fields. Encryption bytes and the full authentication tag
+remain unchanged. No ciphertext, account-data or API migration is required;
+publication remains a separate protected npm workflow.
+
+Version 2.8.0 corrects BUMP offset arithmetic above 32 bits
 through `Number.MAX_SAFE_INTEGER`, preserving existing wire encodings. Root
 calculation, extraction, combination and trimming use the same exact numeric
 domain; malformed non-integer and unsafe offsets fail explicitly. No consumer

docs/reference/package-api-migrations.md

@@ -62,7 +62,7 @@ authorized release action.
 | overlays | `@bsv/overlay-discovery-services` | `2.2.5` | node-library | node-cjs, node-esm | node | `>=22` | [packages/overlays/overlay-discovery-services](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/overlay-discovery-services) |
 | overlays | `@bsv/overlay-express` | `2.7.2` | node-library | node-cjs, node-esm | node | `>=22` | [packages/overlays/overlay-express](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/overlay-express) |
 | overlays | `@bsv/overlay-topics` | `1.8.4` | node-library | node-esm | node | `>=22` | [packages/overlays/topics](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/topics) |
-| sdk | `@bsv/sdk` | `2.8.0` | browser-library | browser-bundler, browser-esm, node-cjs, node-esm, umd-global | browser, node, umd | `>=22` | [packages/sdk](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/sdk) |
+| sdk | `@bsv/sdk` | `2.8.1` | browser-library | browser-bundler, browser-esm, node-cjs, node-esm, umd-global | browser, node, umd | `>=22` | [packages/sdk](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/sdk) |
 | sdk | `@bsv/verifast` | `0.3.6` | wasm-library | browser-bundler, browser-esm, node-cjs, node-esm, umd-global, wasm-worker | browser, node, umd, wasm, worker | `>=22` | [packages/verifast](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/verifast) |
 | wallet | `@bsv/btms` | `1.2.3` | node-library | node-cjs, node-esm | node | `>=22` | [packages/wallet/btms](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/btms) |
 | wallet | `@bsv/btms-permission-module` | `1.2.1` | node-library | node-esm | node | `>=22` | [packages/wallet/btms-permission-module](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/wallet/btms-permission-module) |

docs/reference/stack-facts.md

@@ -167,9 +167,9 @@
     {
       "name": "@bsv/sdk",
       "publishedVersion": "2.8.0",
-      "releaseType": "none",
-      "summary": "Adds TOTP.generateSecure and TOTP.validateSecure for conventional six-digit zero-padded codes while retaining the published legacy methods, and hardens authenticated identity binding, replay state, transaction framing, BEEF ownership, registry payloads, transport deadlines, script-verifier registration, wallet-result ownership, certificate acquisition, and signing context. Corrects empty authenticated HTTP response bodies to use the BRC-104 -1 length sentinel, restoring verification of conforming bodyless responses.",
-      "migration": "Existing TOTP.generate and TOTP.validate calls retain their historical two-digit, unpadded behavior and require no wire migration. New authentication flows should use generateSecure and validateSecure and store or transmit the six-character code as a string so leading zeroes are preserved. Ordinary valid BEEF, BRC-103 v0.1 peers, and public APIs remain compatible; malformed, ambiguous, oversized, identity-mismatched, or value-creating results now fail closed. Validated wallet results retain ordinary object behavior but are returned as owned value snapshots, so callers must not rely on object, array, or byte-buffer identity with the wallet adapter's raw response. Historical numeric-key JSON objects are recovered as bytes only for documented HTTP wallet byte fields; opaque numeric-key metadata remains an object. Deferred signableTransaction results may remain partial, and completed createAction results may use source values from the caller's immutable inputBEEF. Custom wallets must include direct source transactions for every other completed createAction or signAction input; duplicate input outpoints and unresolved or zero-input value-creating completed results are rejected. Browser applications that require DNS rebinding resistance must use a trusted egress proxy. The response-encoding correction is included in the existing unpublished 2.8.0 candidate. Conforming servers and non-empty response bytes require no migration; non-conforming servers signing zero for an empty response must use the BRC-104 -1 sentinel."
+      "releaseType": "patch",
+      "summary": "Fixes portable AES-GCM decryption of valid authenticated empty plaintext, including empty encrypted wallet fields. Preserves historical encryption bytes and full tag verification, and adds native/portable compatibility and negative tests for all supported AES key sizes, IV lengths, block boundaries and SymmetricKey envelopes. SDK 2.8.1 is a source candidate until protected npm publication.",
+      "migration": "None. Public APIs, ciphertext bytes and stored account data are unchanged. Upgrade browser/mobile consumers to SDK 2.8.1 after publication to decrypt valid empty fields. Missing, truncated or altered authentication tags and wrong keys or IVs still fail closed."
     },
     {
       "name": "@bsv/simple",

governance/package-release-notes.json

@@ -322,7 +322,7 @@
     "@bsv/overlay-discovery-services": "2.2.5",
     "@bsv/overlay-express": "2.7.2",
     "@bsv/overlay-topics": "1.8.4",
-    "@bsv/sdk": "2.8.0",
+    "@bsv/sdk": "2.8.1",
     "@bsv/verifast": "0.3.6",
     "@bsv/btms": "1.2.3",
     "@bsv/btms-permission-module": "1.2.1",

governance/repository-health/baselines.json

@@ -214,6 +214,16 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
+### 2.8.1 candidate — portable authenticated empty fields
+
+- Fix portable AES-GCM decryption of valid authenticated empty plaintext. This
+  restores native/browser/mobile interoperability for empty encrypted fields.
+- Preserve historical encryption bytes and full authentication-tag validation;
+  add independent native-oracle tests across AES key sizes, IV lengths and block
+  boundaries, plus tampering and forced-portable SymmetricKey coverage.
+- Migration: none. Existing accounts, ciphertexts and public APIs are unchanged.
+  Publication remains subject to the protected npm workflow.
+
 ### 2.8.0 candidate — authenticated boundaries and additive secure TOTP APIs
 
 - Correct empty authenticated HTTP response preimages to use the BRC-104 `-1`

packages/sdk/CHANGELOG.md

@@ -16,7 +16,7 @@ emits a portable `number[]` settlement artifact so HTTP, WebSocket, Message Box,
 and JSON transports preserve identical transaction bytes. The same boundary
 protects overlay lookup queries and JSON BEEF responses.
 
-The unpublished 2.8.0 candidate verifies bodyless authenticated HTTP responses
+Version 2.8.0 verifies bodyless authenticated HTTP responses
 using the BRC-104 `-1` body-length sentinel. Conforming 204 and empty error
 responses now verify; non-empty response encoding is unchanged. Servers that
 sign a zero body length for an empty response must adopt the specified sentinel.
@@ -45,6 +45,13 @@ in UMD; their reviewed ceilings are 742,500 and 556,000 bytes respectively.
 The combined sync and security candidate measures 560,560 raw bytes with esbuild;
 its reviewed raw ceiling is 561,000 bytes. Compression ceilings are unchanged.
 
+The 2.8.1 candidate fixes portable AES-GCM decryption of authenticated empty
+plaintext, including empty encrypted wallet fields. Browser/mobile runtimes and
+Node now accept the same valid envelopes. Encryption bytes and full 16-byte tag
+verification are unchanged; invalid tags, keys and IVs remain rejected. No API,
+wire, account-data or ciphertext migration is required. This source candidate is
+not published until the protected npm release workflow completes.
+
 ## Table of Contents
 
 1. [Objective](#objective)

packages/sdk/README.md

@@ -5389,51 +5389,13 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 ### Function: AESGCM
 
-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.
+AES-GCM without additional authenticated data.
+
+Keep the historical GHASH input formatting in buildAuthInput unchanged.
+Its leading zero block (and extra zero block for empty ciphertext) does not
+change the tag: GHASH starts at zero, and processing a zero block leaves it
+at zero. Native interoperability tests cover empty and block-boundary inputs.
+Empty ciphertext is valid but still requires the complete, matching tag.
 
 ```ts
 export function AESGCM(plainText: Bytes, initializationVector: Bytes, key: Bytes): {

packages/sdk/docs/reference/primitives.md

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "sideEffects": false,
   "engines": {
     "node": ">=22"

packages/sdk/package.json

@@ -444,51 +444,13 @@ function buildAuthInput (cipherText: Bytes): Bytes {
 }
 
 /**
- * SECURITY NOTE – NON-STANDARD AES-GCM PADDING
+ * AES-GCM without additional authenticated data.
  *
- * 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.
+ * Keep the historical GHASH input formatting in buildAuthInput unchanged.
+ * Its leading zero block (and extra zero block for empty ciphertext) does not
+ * change the tag: GHASH starts at zero, and processing a zero block leaves it
+ * at zero. Native interoperability tests cover empty and block-boundary inputs.
+ * Empty ciphertext is valid but still requires the complete, matching tag.
  */
 export function AESGCM (
   plainText: Bytes,
@@ -551,10 +513,6 @@ export function AESGCMDecrypt (
   authenticationTag: Bytes,
   key: Bytes
 ): Bytes | null {
-  if (cipherText.length === 0) {
-    throw new Error('Cipher text must not be empty')
-  }
-
   if (initializationVector.length === 0) {
     throw new Error('Initialization vector must not be empty')
   }