@fgv/ts-web-extras 5.1.0-18 → 5.1.0-19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-web-extras",
-  "version": "5.1.0-18",
+  "version": "5.1.0-19",
   "description": "Browser-compatible utilities and FileTree implementations",
   "main": "lib/index.js",
   "types": "dist/ts-web-extras.d.ts",
@@ -46,19 +46,19 @@
     "@types/react": "~19.2.8",
     "typedoc": "~0.28.16",
     "typedoc-plugin-markdown": "~4.9.0",
-    "@fgv/heft-dual-rig": "5.1.0-18",
-    "@fgv/typedoc-compact-theme": "5.1.0-18",
-    "@fgv/ts-json-base": "5.1.0-18",
-    "@fgv/ts-utils": "5.1.0-18",
-    "@fgv/ts-utils-jest": "5.1.0-18",
-    "@fgv/ts-extras": "5.1.0-18"
+    "@fgv/heft-dual-rig": "5.1.0-19",
+    "@fgv/typedoc-compact-theme": "5.1.0-19",
+    "@fgv/ts-utils": "5.1.0-19",
+    "@fgv/ts-extras": "5.1.0-19",
+    "@fgv/ts-json-base": "5.1.0-19",
+    "@fgv/ts-utils-jest": "5.1.0-19"
   },
   "peerDependencies": {
     "react": ">=18 <20",
     "react-dom": ">=18 <20",
-    "@fgv/ts-utils": "5.1.0-18",
-    "@fgv/ts-json-base": "5.1.0-18",
-    "@fgv/ts-extras": "5.1.0-18"
+    "@fgv/ts-extras": "5.1.0-19",
+    "@fgv/ts-utils": "5.1.0-19",
+    "@fgv/ts-json-base": "5.1.0-19"
   },
   "exports": {
     ".": {
@@ -81,14 +81,14 @@
     "idb-keyval": "^6.2.2"
   },
   "scripts": {
-    "build": "heft test --clean",
+    "build": "NODE_OPTIONS=--disable-warning=DEP0040 heft test --clean",
     "clean": "heft clean",
-    "test": "heft test --clean",
+    "test": "NODE_OPTIONS=--disable-warning=DEP0040 heft test --clean",
     "build-docs": "typedoc --options ./config/typedoc.json",
     "build-all": "rushx build; rushx build-docs",
-    "test-handles": "jest --runInBand --detectOpenHandles",
+    "test-handles": "NODE_OPTIONS=--disable-warning=DEP0040 jest --runInBand --detectOpenHandles",
     "clean-jest": "jest --clear-cache",
-    "coverage": "jest --coverage",
+    "coverage": "NODE_OPTIONS=--disable-warning=DEP0040 jest --coverage",
     "lint": "eslint src --ext .ts",
     "fixlint": "eslint src --ext .ts --fix"
   }

package/rush-logs/ts-web-extras.build.cache.log

@@ -1,3 +1,3 @@
 Caching build output folders: dist, lib, temp, .rush/temp/operation/build
 Successfully set cache entry.
-Cache key: 680645452ebdb4d7f294f08d3b45f143d69c3f5d
+Cache key: 42a7a953924ae898114e7b6231a2408228d92433

package/rush-logs/ts-web-extras.build.log

@@ -1,42 +1,44 @@
-Invoking: heft test --clean 
+Invoking: NODE_OPTIONS=--disable-warning=DEP0040 heft test --clean 
  ---- build started ---- 
 [build:typescript] The TypeScript compiler version 5.9.3 is newer than the latest version that was tested with Heft (5.8); it may not work correctly.
 [build:typescript] Using TypeScript version 5.9.3
 [build:api-extractor] Using API Extractor version 7.57.7
 [build:api-extractor] Analysis will use the bundled TypeScript version 5.8.2
 [build:api-extractor] *** The target project appears to use TypeScript 5.9.3 which is newer than the bundled compiler engine; consider upgrading API Extractor.
- ---- build finished (24.801s) ---- 
+ ---- build finished (23.128s) ---- 
  ---- test started ---- 
 [test:jest] Using Jest version 29.5.0
 [test:jest] 
-[test:jest] Run start. 9 test suites
+[test:jest] Run start. 10 test suites
 [test:jest] START lib/test/unit/httpTreeAccessors.test.js
 [test:jest] START lib/test/unit/fileApiTreeAccessors.test.js
 [test:jest] START lib/test/unit/localStorageTreeAccessors.test.js
 [test:jest] START lib/test/unit/fileSystemAccessTreeAccessors.test.js
-[test:jest] PASS lib/test/unit/localStorageTreeAccessors.test.js (duration: 2.975s, 44 passed, 0 failed)
+[test:jest] PASS lib/test/unit/localStorageTreeAccessors.test.js (duration: 1.702s, 44 passed, 0 failed)
 [test:jest] START lib/test/unit/fileTreeHelpers.test.js
-[test:jest] PASS lib/test/unit/httpTreeAccessors.test.js (duration: 3.203s, 61 passed, 0 failed)
+[test:jest] PASS lib/test/unit/httpTreeAccessors.test.js (duration: 2.103s, 61 passed, 0 failed)
 [test:jest] START lib/test/unit/fileApiTypes.test.js
-[test:jest] PASS lib/test/unit/fileApiTreeAccessors.test.js (duration: 3.464s, 65 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileApiTreeAccessors.test.js (duration: 2.550s, 65 passed, 0 failed)
 [test:jest] START lib/test/unit/urlParams.test.js
-[test:jest] PASS lib/test/unit/fileSystemAccessTreeAccessors.test.js (duration: 1.300s, 44 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileSystemAccessTreeAccessors.test.js (duration: 1.592s, 44 passed, 0 failed)
+[test:jest] START lib/test/unit/browserCryptoProvider.wrapBytes.test.js
+[test:jest] PASS lib/test/unit/fileApiTypes.test.js (duration: 1.647s, 36 passed, 0 failed)
 [test:jest] START lib/test/unit/directoryHandleStore.test.js
-[test:jest] PASS lib/test/unit/fileTreeHelpers.test.js (duration: 1.819s, 35 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileTreeHelpers.test.js (duration: 2.006s, 35 passed, 0 failed)
 [test:jest] START lib/test/unit/browserHashProvider.test.js
-[test:jest] PASS lib/test/unit/fileApiTypes.test.js (duration: 1.579s, 36 passed, 0 failed)
-[test:jest] PASS lib/test/unit/urlParams.test.js (duration: 1.586s, 60 passed, 0 failed)
-[test:jest] PASS lib/test/unit/directoryHandleStore.test.js (duration: 1.282s, 19 passed, 0 failed)
-[test:jest] PASS lib/test/unit/browserHashProvider.test.js (duration: 1.520s, 15 passed, 0 failed)
+[test:jest] PASS lib/test/unit/directoryHandleStore.test.js (duration: 1.362s, 19 passed, 0 failed)
+[test:jest] PASS lib/test/unit/urlParams.test.js (duration: 1.974s, 60 passed, 0 failed)
+[test:jest] PASS lib/test/unit/browserCryptoProvider.wrapBytes.test.js (duration: 2.015s, 26 passed, 0 failed)
+[test:jest] PASS lib/test/unit/browserHashProvider.test.js (duration: 1.383s, 15 passed, 0 failed)
 [test:jest] 
 [test:jest] Tests finished:
-[test:jest]   Successes: 379
+[test:jest]   Successes: 405
 [test:jest]   Failures: 0
-[test:jest]   Total: 380
+[test:jest]   Total: 406
 -----------------------------------|---------|----------|---------|---------|-------------------
 File                               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
 -----------------------------------|---------|----------|---------|---------|-------------------
-All files                          |     100 |    99.62 |     100 |     100 |                   
+All files                          |     100 |    99.64 |     100 |     100 |                   
  crypto-utils                      |     100 |      100 |     100 |     100 |                   
   browserCryptoProvider.ts         |     100 |      100 |     100 |     100 |                   
   browserHashProvider.ts           |     100 |      100 |     100 |     100 |                   
@@ -51,5 +53,5 @@ All files                          |     100 |    99.62 |     100 |     100 |
  url-utils                         |     100 |      100 |     100 |     100 |                   
   urlParams.ts                     |     100 |      100 |     100 |     100 |                   
 -----------------------------------|---------|----------|---------|---------|-------------------
- ---- test finished (10.229s) ---- 
--------------------- Finished (35.048s) --------------------
+ ---- test finished (9.881s) ---- 
+-------------------- Finished (33.035s) --------------------

package/src/packlets/crypto-utils/browserCryptoProvider.ts

@@ -18,10 +18,10 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
-/* c8 ignore start - Browser-only implementation cannot be tested in Node.js environment */
 import { captureAsyncResult, captureResult, fail, Failure, Result, succeed, Success } from '@fgv/ts-utils';
 import { CryptoUtils } from '@fgv/ts-extras';
 
+/* c8 ignore start - Used only by browser-only methods that cannot be tested in Node.js environment */
 /**
  * Extracts an `ArrayBuffer` from a Uint8Array, handling the potential SharedArrayBuffer case.
  * @param arr - The Uint8Array to extract from
@@ -33,6 +33,25 @@ function toArrayBuffer(arr: Uint8Array): ArrayBuffer {
   new Uint8Array(buffer).set(arr);
   return buffer;
 }
+/* c8 ignore stop */
+
+/**
+ * Returns a fresh Uint8Array view over a non-shared ArrayBuffer copy of `arr`.
+ * Used by {@link BrowserCryptoProvider.wrapBytes | wrapBytes} and
+ * {@link BrowserCryptoProvider.unwrapBytes | unwrapBytes}: Node 20's
+ * webcrypto.subtle rejects raw `ArrayBuffer` for several `BufferSource`
+ * parameters with "is not instance of ArrayBuffer, Buffer, TypedArray, or
+ * DataView" even though `ArrayBuffer` should be valid per the spec; a
+ * TypedArray view is accepted on Node 20+ and on browsers, and the explicit
+ * `Uint8Array<ArrayBuffer>` return type also satisfies TypeScript's `BufferSource`
+ * (which excludes the `SharedArrayBuffer` branch of `Uint8Array`'s buffer type).
+ */
+function toBufferView(arr: Uint8Array): Uint8Array<ArrayBuffer> {
+  const buffer = new ArrayBuffer(arr.byteLength);
+  const view = new Uint8Array(buffer);
+  view.set(arr);
+  return view;
+}
 
 /**
  * Browser implementation of `ICryptoProvider` using the Web Crypto API.
@@ -46,6 +65,7 @@ function toArrayBuffer(arr: Uint8Array): ArrayBuffer {
 export class BrowserCryptoProvider implements CryptoUtils.ICryptoProvider {
   private readonly _crypto: Crypto;
 
+  /* c8 ignore start - Existing browser-only methods cannot be tested in Node.js environment */
   /**
    * Creates a new {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider}.
    * @param cryptoApi - Optional Crypto instance (defaults to globalThis.crypto)
@@ -372,8 +392,155 @@ export class BrowserCryptoProvider implements CryptoUtils.ICryptoProvider {
     );
     return result.withErrorFormat((e) => `Failed to import ${algorithm} public key from JWK: ${e}`);
   }
+  /* c8 ignore stop */
+
+  /**
+   * Wraps `plaintext` for the holder of `recipientPublicKey` using
+   * ECIES (ECDH P-256 + HKDF-SHA256 + AES-GCM-256). See
+   * {@link CryptoUtils.ICryptoProvider.wrapBytes | ICryptoProvider.wrapBytes}.
+   * @param plaintext - The bytes to wrap.
+   * @param recipientPublicKey - The recipient's ECDH P-256 public `CryptoKey`.
+   * @param options - HKDF salt and info; see {@link CryptoUtils.IWrapBytesOptions | IWrapBytesOptions}.
+   * @returns `Success` with the wrapped payload, or `Failure` with an error.
+   */
+  public async wrapBytes(
+    plaintext: Uint8Array,
+    recipientPublicKey: CryptoKey,
+    options: CryptoUtils.IWrapBytesOptions
+  ): Promise<Result<CryptoUtils.IWrappedBytes>> {
+    const recipientCheck = checkEcdhP256(recipientPublicKey, 'public', 'recipient public key');
+    if (recipientCheck.isFailure()) {
+      return Failure.with(`wrapBytes failed: ${recipientCheck.message}`);
+    }
+    const subtle = this._crypto.subtle;
+    const result = await captureAsyncResult(async () => {
+      const ephemeral = (await subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, [
+        'deriveKey'
+      ])) as CryptoKeyPair;
+      const hkdfBase = await subtle.deriveKey(
+        { name: 'ECDH', public: recipientPublicKey },
+        ephemeral.privateKey,
+        { name: 'HKDF' },
+        false,
+        ['deriveKey']
+      );
+      const wrapKey = await subtle.deriveKey(
+        { name: 'HKDF', salt: toBufferView(options.salt), info: toBufferView(options.info), hash: 'SHA-256' },
+        hkdfBase,
+        { name: 'AES-GCM', length: 256 },
+        false,
+        ['encrypt']
+      );
+      const nonce = this._crypto.getRandomValues(new Uint8Array(CryptoUtils.Constants.GCM_IV_SIZE));
+      const ctBuf = await subtle.encrypt({ name: 'AES-GCM', iv: nonce }, wrapKey, toBufferView(plaintext));
+      const ephemeralPublicKey = await subtle.exportKey('jwk', ephemeral.publicKey);
+      return {
+        ephemeralPublicKey,
+        nonce: this.toBase64(nonce),
+        ciphertext: this.toBase64(new Uint8Array(ctBuf))
+      };
+    });
+    return result.withErrorFormat((e) => `wrapBytes failed: ${e}`);
+  }
+
+  /**
+   * Unwraps a payload produced by `wrapBytes` using the recipient's private
+   * key. See {@link CryptoUtils.ICryptoProvider.unwrapBytes | ICryptoProvider.unwrapBytes}.
+   * @param wrapped - The wrapped payload.
+   * @param recipientPrivateKey - The recipient's ECDH P-256 private `CryptoKey`.
+   * @param options - HKDF salt and info matching the wrap call.
+   * @returns `Success` with the original `plaintext`, or `Failure` with an error.
+   */
+  public async unwrapBytes(
+    wrapped: CryptoUtils.IWrappedBytes,
+    recipientPrivateKey: CryptoKey,
+    options: CryptoUtils.IWrapBytesOptions
+  ): Promise<Result<Uint8Array>> {
+    const recipientCheck = checkEcdhP256(recipientPrivateKey, 'private', 'recipient private key');
+    if (recipientCheck.isFailure()) {
+      return Failure.with(`unwrapBytes failed: ${recipientCheck.message}`);
+    }
+    const nonceResult = this.fromBase64(wrapped.nonce);
+    if (nonceResult.isFailure()) {
+      return Failure.with(`unwrapBytes failed: nonce: ${nonceResult.message}`);
+    }
+    if (nonceResult.value.length !== CryptoUtils.Constants.GCM_IV_SIZE) {
+      return Failure.with(
+        `unwrapBytes failed: nonce must be ${CryptoUtils.Constants.GCM_IV_SIZE} bytes (got ${nonceResult.value.length})`
+      );
+    }
+    const ciphertextResult = this.fromBase64(wrapped.ciphertext);
+    if (ciphertextResult.isFailure()) {
+      return Failure.with(`unwrapBytes failed: ciphertext: ${ciphertextResult.message}`);
+    }
+    if (ciphertextResult.value.length < CryptoUtils.Constants.GCM_AUTH_TAG_SIZE) {
+      return Failure.with(
+        `unwrapBytes failed: ciphertext must be at least ${CryptoUtils.Constants.GCM_AUTH_TAG_SIZE} bytes (got ${ciphertextResult.value.length})`
+      );
+    }
+    const subtle = this._crypto.subtle;
+    const result = await captureAsyncResult(async () => {
+      const ephemeralPub = await subtle.importKey(
+        'jwk',
+        wrapped.ephemeralPublicKey,
+        { name: 'ECDH', namedCurve: 'P-256' },
+        false,
+        []
+      );
+      const hkdfBase = await subtle.deriveKey(
+        { name: 'ECDH', public: ephemeralPub },
+        recipientPrivateKey,
+        { name: 'HKDF' },
+        false,
+        ['deriveKey']
+      );
+      const wrapKey = await subtle.deriveKey(
+        { name: 'HKDF', salt: toBufferView(options.salt), info: toBufferView(options.info), hash: 'SHA-256' },
+        hkdfBase,
+        { name: 'AES-GCM', length: 256 },
+        false,
+        ['decrypt']
+      );
+      const ptBuf = await subtle.decrypt(
+        { name: 'AES-GCM', iv: toBufferView(nonceResult.value) },
+        wrapKey,
+        toBufferView(ciphertextResult.value)
+      );
+      return new Uint8Array(ptBuf);
+    });
+    return result.withErrorFormat((e) => `unwrapBytes failed: ${e}`);
+  }
+}
+
+/**
+ * Verifies that `key` is an ECDH P-256 `CryptoKey` of the expected `keyType`
+ * (public or private). Used by the wrap/unwrap methods to surface a clean
+ * `Failure` instead of letting the WebCrypto deriveKey call throw a less
+ * informative error later in the pipeline. Key usages are intentionally not
+ * checked here: WebCrypto already produces a specific error if `deriveKey` is
+ * not in `usages`, and `deriveBits` is an equally valid alternative usage that
+ * an explicit check would have to track.
+ * @param key - The CryptoKey to validate.
+ * @param keyType - The required `key.type` ('public' for wrap, 'private' for unwrap).
+ * @param label - Human-readable role label included in the failure message.
+ * @returns `Success` with the key (unchanged) when the algorithm, curve, and
+ * type all match; otherwise `Failure` with `<label> must be ECDH P-256 (...)`.
+ */
+function checkEcdhP256(key: CryptoKey, keyType: 'public' | 'private', label: string): Result<CryptoKey> {
+  if (key.algorithm.name !== 'ECDH') {
+    return Failure.with(`${label} must be ECDH P-256 (got algorithm '${key.algorithm.name}')`);
+  }
+  const namedCurve = (key.algorithm as EcKeyAlgorithm).namedCurve;
+  if (namedCurve !== 'P-256') {
+    return Failure.with(`${label} must be ECDH P-256 (got curve '${namedCurve}')`);
+  }
+  if (key.type !== keyType) {
+    return Failure.with(`${label} must be a ${keyType} CryptoKey (got '${key.type}')`);
+  }
+  return succeed(key);
 }
 
+/* c8 ignore start - Constructs a provider; only meaningful in a real browser environment */
 /**
  * Creates a {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider} if Web
  * Crypto API is available.

package/src/test/unit/browserCryptoProvider.wrapBytes.test.ts

@@ -0,0 +1,325 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import '@fgv/ts-utils-jest';
+
+import { CryptoUtils } from '@fgv/ts-extras';
+import { BrowserCryptoProvider } from '../../packlets/crypto-utils';
+
+const provider = new BrowserCryptoProvider();
+const subtle = globalThis.crypto.subtle;
+
+async function generateEcdhPair(curve: 'P-256' | 'P-384' = 'P-256'): Promise<CryptoKeyPair> {
+  return (await subtle.generateKey({ name: 'ECDH', namedCurve: curve }, true, [
+    'deriveKey',
+    'deriveBits'
+  ])) as CryptoKeyPair;
+}
+
+async function generateEcdsaPair(): Promise<CryptoKeyPair> {
+  return (await subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, [
+    'sign',
+    'verify'
+  ])) as CryptoKeyPair;
+}
+
+describe('BrowserCryptoProvider — wrapBytes/unwrapBytes', () => {
+  const defaultOptions: CryptoUtils.IWrapBytesOptions = {
+    salt: new TextEncoder().encode('test-salt'),
+    info: new TextEncoder().encode('test-info')
+  };
+
+  describe('round-trip', () => {
+    test.each<[string, Uint8Array]>([
+      ['32-byte plaintext (AES-256 key shape)', globalThis.crypto.getRandomValues(new Uint8Array(32))],
+      ['1-byte plaintext', new Uint8Array([0x42])],
+      ['1KB plaintext', globalThis.crypto.getRandomValues(new Uint8Array(1024))],
+      ['empty plaintext', new Uint8Array(0)],
+      ['high-bit-set bytes', new Uint8Array(64).fill(0xff)]
+    ])('round-trips %s', async (__label, plaintext) => {
+      const pair = await generateEcdhPair();
+      const wrapped = (await provider.wrapBytes(plaintext, pair.publicKey, defaultOptions)).orThrow();
+      expect(wrapped.ephemeralPublicKey.kty).toBe('EC');
+      expect(wrapped.ephemeralPublicKey.crv).toBe('P-256');
+      const recovered = (await provider.unwrapBytes(wrapped, pair.privateKey, defaultOptions)).orThrow();
+      expect(new Uint8Array(recovered)).toEqual(plaintext);
+    });
+  });
+
+  describe('determinism / freshness', () => {
+    test('two wraps of identical inputs produce different ephemeral keys and ciphertexts', async () => {
+      const pair = await generateEcdhPair();
+      const plaintext = new TextEncoder().encode('same payload');
+      const w1 = (await provider.wrapBytes(plaintext, pair.publicKey, defaultOptions)).orThrow();
+      const w2 = (await provider.wrapBytes(plaintext, pair.publicKey, defaultOptions)).orThrow();
+      expect(w1.ephemeralPublicKey).not.toEqual(w2.ephemeralPublicKey);
+      expect(w1.ciphertext).not.toEqual(w2.ciphertext);
+      expect(w1.nonce).not.toEqual(w2.nonce);
+    });
+  });
+
+  describe('tampering', () => {
+    test('flipping a bit in the nonce fails GCM authentication', async () => {
+      const pair = await generateEcdhPair();
+      const wrapped = (
+        await provider.wrapBytes(new TextEncoder().encode('payload'), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const nonce = provider.fromBase64(wrapped.nonce).orThrow();
+      nonce[0] ^= 0xff;
+      const tampered: CryptoUtils.IWrappedBytes = { ...wrapped, nonce: provider.toBase64(nonce) };
+      expect(await provider.unwrapBytes(tampered, pair.privateKey, defaultOptions)).toFailWith(
+        /unwrapBytes failed/i
+      );
+    });
+
+    test('flipping a bit in the ciphertext fails GCM authentication', async () => {
+      const pair = await generateEcdhPair();
+      const wrapped = (
+        await provider.wrapBytes(new TextEncoder().encode('payload'), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const ct = provider.fromBase64(wrapped.ciphertext).orThrow();
+      ct[0] ^= 0x01;
+      const tampered: CryptoUtils.IWrappedBytes = { ...wrapped, ciphertext: provider.toBase64(ct) };
+      expect(await provider.unwrapBytes(tampered, pair.privateKey, defaultOptions)).toFailWith(
+        /unwrapBytes failed/i
+      );
+    });
+
+    test('truncating ciphertext by one byte fails GCM authentication (still ≥ 16 bytes)', async () => {
+      const pair = await generateEcdhPair();
+      // 16-byte plaintext → 32-byte ciphertext (16 ct + 16 tag); truncate by 1 → 31 bytes ≥ 16
+      const wrapped = (
+        await provider.wrapBytes(new Uint8Array(16).fill(0xab), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const ct = provider.fromBase64(wrapped.ciphertext).orThrow();
+      const truncated = ct.slice(0, ct.length - 1);
+      const tampered: CryptoUtils.IWrappedBytes = { ...wrapped, ciphertext: provider.toBase64(truncated) };
+      expect(await provider.unwrapBytes(tampered, pair.privateKey, defaultOptions)).toFailWith(
+        /unwrapBytes failed/i
+      );
+    });
+
+    test('substituting a different ephemeral public key fails authentication', async () => {
+      const pair = await generateEcdhPair();
+      const wrapped = (
+        await provider.wrapBytes(new TextEncoder().encode('payload'), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const other = (
+        await provider.wrapBytes(new TextEncoder().encode('payload'), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const tampered: CryptoUtils.IWrappedBytes = {
+        ...wrapped,
+        ephemeralPublicKey: other.ephemeralPublicKey
+      };
+      expect(await provider.unwrapBytes(tampered, pair.privateKey, defaultOptions)).toFailWith(
+        /unwrapBytes failed/i
+      );
+    });
+  });
+
+  describe('wrong-key / wrong-options', () => {
+    test('unwrap with a different recipient private key fails', async () => {
+      const pair = await generateEcdhPair();
+      const other = await generateEcdhPair();
+      const wrapped = (
+        await provider.wrapBytes(new TextEncoder().encode('payload'), pair.publicKey, defaultOptions)
+      ).orThrow();
+      expect(await provider.unwrapBytes(wrapped, other.privateKey, defaultOptions)).toFailWith(
+        /unwrapBytes failed/i
+      );
+    });
+
+    test('unwrap with a different HKDF salt fails authentication', async () => {
+      const pair = await generateEcdhPair();
+      const wrapped = (
+        await provider.wrapBytes(new TextEncoder().encode('payload'), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const wrongSalt: CryptoUtils.IWrapBytesOptions = {
+        salt: new TextEncoder().encode('different-salt'),
+        info: defaultOptions.info
+      };
+      expect(await provider.unwrapBytes(wrapped, pair.privateKey, wrongSalt)).toFailWith(
+        /unwrapBytes failed/i
+      );
+    });
+
+    test('unwrap with a different HKDF info fails authentication', async () => {
+      const pair = await generateEcdhPair();
+      const wrapped = (
+        await provider.wrapBytes(new TextEncoder().encode('payload'), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const wrongInfo: CryptoUtils.IWrapBytesOptions = {
+        salt: defaultOptions.salt,
+        info: new TextEncoder().encode('different-info')
+      };
+      expect(await provider.unwrapBytes(wrapped, pair.privateKey, wrongInfo)).toFailWith(
+        /unwrapBytes failed/i
+      );
+    });
+
+    test('empty salt and info round-trip when both sides agree', async () => {
+      const pair = await generateEcdhPair();
+      const empty: CryptoUtils.IWrapBytesOptions = { salt: new Uint8Array(0), info: new Uint8Array(0) };
+      const plaintext = globalThis.crypto.getRandomValues(new Uint8Array(16));
+      const wrapped = (await provider.wrapBytes(plaintext, pair.publicKey, empty)).orThrow();
+      const recovered = (await provider.unwrapBytes(wrapped, pair.privateKey, empty)).orThrow();
+      expect(new Uint8Array(recovered)).toEqual(plaintext);
+    });
+  });
+
+  describe('malformed input', () => {
+    test('malformed ephemeralPublicKey JWK fails', async () => {
+      const pair = await generateEcdhPair();
+      const wrapped = (
+        await provider.wrapBytes(new TextEncoder().encode('payload'), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const bogus: CryptoUtils.IWrappedBytes = {
+        ...wrapped,
+        ephemeralPublicKey: { kty: 'EC', crv: 'P-256' } as JsonWebKey
+      };
+      expect(await provider.unwrapBytes(bogus, pair.privateKey, defaultOptions)).toFailWith(
+        /unwrapBytes failed/i
+      );
+    });
+
+    test('ephemeralPublicKey on the wrong curve (P-384) fails', async () => {
+      const pair = await generateEcdhPair();
+      const wrongCurve = await generateEcdhPair('P-384');
+      const wrongJwk = await subtle.exportKey('jwk', wrongCurve.publicKey);
+      const wrapped = (
+        await provider.wrapBytes(new TextEncoder().encode('payload'), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const tampered: CryptoUtils.IWrappedBytes = { ...wrapped, ephemeralPublicKey: wrongJwk };
+      expect(await provider.unwrapBytes(tampered, pair.privateKey, defaultOptions)).toFailWith(
+        /unwrapBytes failed/i
+      );
+    });
+
+    test('non-base64 nonce fails with a clean error', async () => {
+      const pair = await generateEcdhPair();
+      const wrapped = (
+        await provider.wrapBytes(new TextEncoder().encode('payload'), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const tampered: CryptoUtils.IWrappedBytes = { ...wrapped, nonce: 'not!base64!' };
+      expect(await provider.unwrapBytes(tampered, pair.privateKey, defaultOptions)).toFailWith(
+        /unwrapBytes failed: nonce/i
+      );
+    });
+
+    test('non-base64 ciphertext fails with a clean error', async () => {
+      const pair = await generateEcdhPair();
+      const wrapped = (
+        await provider.wrapBytes(new TextEncoder().encode('payload'), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const tampered: CryptoUtils.IWrappedBytes = { ...wrapped, ciphertext: 'not!base64!' };
+      expect(await provider.unwrapBytes(tampered, pair.privateKey, defaultOptions)).toFailWith(
+        /unwrapBytes failed: ciphertext/i
+      );
+    });
+
+    test('wrong-length nonce (after base64 decode) fails before reaching AES-GCM', async () => {
+      const pair = await generateEcdhPair();
+      const wrapped = (
+        await provider.wrapBytes(new TextEncoder().encode('payload'), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const shortNonce = new Uint8Array(8);
+      const tampered: CryptoUtils.IWrappedBytes = { ...wrapped, nonce: provider.toBase64(shortNonce) };
+      expect(await provider.unwrapBytes(tampered, pair.privateKey, defaultOptions)).toFailWith(
+        /unwrapBytes failed: nonce must be 12 bytes \(got 8\)/i
+      );
+    });
+
+    test('ciphertext shorter than the GCM auth tag fails before reaching AES-GCM', async () => {
+      const pair = await generateEcdhPair();
+      const wrapped = (
+        await provider.wrapBytes(new TextEncoder().encode('payload'), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const shortCt = new Uint8Array(8);
+      const tampered: CryptoUtils.IWrappedBytes = { ...wrapped, ciphertext: provider.toBase64(shortCt) };
+      expect(await provider.unwrapBytes(tampered, pair.privateKey, defaultOptions)).toFailWith(
+        /unwrapBytes failed: ciphertext must be at least 16 bytes \(got 8\)/i
+      );
+    });
+  });
+
+  describe('algorithm / type mismatch on recipient key', () => {
+    test('wrap fails when recipient public key is RSA-OAEP, not ECDH', async () => {
+      const rsa = (await subtle.generateKey(
+        {
+          name: 'RSA-OAEP',
+          modulusLength: 2048,
+          publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
+          hash: 'SHA-256'
+        },
+        true,
+        ['encrypt', 'decrypt']
+      )) as CryptoKeyPair;
+      const result = await provider.wrapBytes(new Uint8Array([1, 2, 3]), rsa.publicKey, defaultOptions);
+      expect(result).toFailWith(/wrapBytes failed: recipient public key must be ECDH P-256.*RSA-OAEP/i);
+    });
+
+    test('wrap fails when recipient public key is ECDSA P-256, not ECDH', async () => {
+      const ecdsa = await generateEcdsaPair();
+      const result = await provider.wrapBytes(new Uint8Array([1, 2, 3]), ecdsa.publicKey, defaultOptions);
+      expect(result).toFailWith(/wrapBytes failed: recipient public key must be ECDH P-256.*ECDSA/i);
+    });
+
+    test('wrap fails when recipient public key is ECDH P-384, not P-256', async () => {
+      const wrongCurve = await generateEcdhPair('P-384');
+      const result = await provider.wrapBytes(
+        new Uint8Array([1, 2, 3]),
+        wrongCurve.publicKey,
+        defaultOptions
+      );
+      expect(result).toFailWith(/wrapBytes failed: recipient public key must be ECDH P-256.*P-384/i);
+    });
+
+    test('unwrap fails when recipient private key is ECDH P-384, not P-256', async () => {
+      const pair = await generateEcdhPair();
+      const wrapped = (
+        await provider.wrapBytes(new Uint8Array([1, 2, 3]), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const wrongCurve = await generateEcdhPair('P-384');
+      const result = await provider.unwrapBytes(wrapped, wrongCurve.privateKey, defaultOptions);
+      expect(result).toFailWith(/unwrapBytes failed: recipient private key must be ECDH P-256.*P-384/i);
+    });
+
+    test('wrap fails when recipient is an ECDH private key (not public)', async () => {
+      const pair = await generateEcdhPair();
+      const result = await provider.wrapBytes(new Uint8Array([1, 2, 3]), pair.privateKey, defaultOptions);
+      expect(result).toFailWith(
+        /wrapBytes failed: recipient public key must be a public CryptoKey \(got 'private'\)/i
+      );
+    });
+
+    test('unwrap fails when recipient is an ECDH public key (not private)', async () => {
+      const pair = await generateEcdhPair();
+      const wrapped = (
+        await provider.wrapBytes(new Uint8Array([1, 2, 3]), pair.publicKey, defaultOptions)
+      ).orThrow();
+      const result = await provider.unwrapBytes(wrapped, pair.publicKey, defaultOptions);
+      expect(result).toFailWith(
+        /unwrapBytes failed: recipient private key must be a private CryptoKey \(got 'public'\)/i
+      );
+    });
+  });
+});