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

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

@@ -18,14 +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 { captureResult, fail, Failure, Result, succeed, Success } from '@fgv/ts-utils';
+import { captureAsyncResult, captureResult, fail, Failure, Result, succeed, Success } from '@fgv/ts-utils';
 import { CryptoUtils } from '@fgv/ts-extras';
 
-type ICryptoProvider = CryptoUtils.ICryptoProvider;
-type IEncryptionResult = CryptoUtils.IEncryptionResult;
-const CryptoConstants = CryptoUtils.Constants;
-
+/* 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
@@ -37,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.
@@ -47,9 +62,10 @@ function toArrayBuffer(arr: Uint8Array): ArrayBuffer {
  *
  * @public
  */
-export class BrowserCryptoProvider implements ICryptoProvider {
+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)
@@ -72,14 +88,14 @@ export class BrowserCryptoProvider implements ICryptoProvider {
    * @param key - 32-byte encryption key
    * @returns `Success` with encryption result, or `Failure` with an error.
    */
-  public async encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>> {
-    if (key.length !== CryptoConstants.AES_256_KEY_SIZE) {
-      return Failure.with(`Key must be ${CryptoConstants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+  public async encrypt(plaintext: string, key: Uint8Array): Promise<Result<CryptoUtils.IEncryptionResult>> {
+    if (key.length !== CryptoUtils.Constants.AES_256_KEY_SIZE) {
+      return Failure.with(`Key must be ${CryptoUtils.Constants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
     }
 
     try {
       // Generate random IV
-      const iv = this._crypto.getRandomValues(new Uint8Array(CryptoConstants.GCM_IV_SIZE));
+      const iv = this._crypto.getRandomValues(new Uint8Array(CryptoUtils.Constants.GCM_IV_SIZE));
 
       // Import the key
       const cryptoKey = await this._crypto.subtle.importKey(
@@ -99,7 +115,7 @@ export class BrowserCryptoProvider implements ICryptoProvider {
         {
           name: 'AES-GCM',
           iv: iv,
-          tagLength: CryptoConstants.GCM_AUTH_TAG_SIZE * 8 // bits
+          tagLength: CryptoUtils.Constants.GCM_AUTH_TAG_SIZE * 8 // bits
         },
         cryptoKey,
         plaintextBytes
@@ -109,9 +125,9 @@ export class BrowserCryptoProvider implements ICryptoProvider {
       const encryptedArray = new Uint8Array(encryptedWithTag);
       const encryptedData = encryptedArray.slice(
         0,
-        encryptedArray.length - CryptoConstants.GCM_AUTH_TAG_SIZE
+        encryptedArray.length - CryptoUtils.Constants.GCM_AUTH_TAG_SIZE
       );
-      const authTag = encryptedArray.slice(encryptedArray.length - CryptoConstants.GCM_AUTH_TAG_SIZE);
+      const authTag = encryptedArray.slice(encryptedArray.length - CryptoUtils.Constants.GCM_AUTH_TAG_SIZE);
       return Success.with({
         iv,
         authTag,
@@ -137,15 +153,15 @@ export class BrowserCryptoProvider implements ICryptoProvider {
     iv: Uint8Array,
     authTag: Uint8Array
   ): Promise<Result<string>> {
-    if (key.length !== CryptoConstants.AES_256_KEY_SIZE) {
-      return Failure.with(`Key must be ${CryptoConstants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+    if (key.length !== CryptoUtils.Constants.AES_256_KEY_SIZE) {
+      return Failure.with(`Key must be ${CryptoUtils.Constants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
     }
-    if (iv.length !== CryptoConstants.GCM_IV_SIZE) {
-      return Failure.with(`IV must be ${CryptoConstants.GCM_IV_SIZE} bytes, got ${iv.length}`);
+    if (iv.length !== CryptoUtils.Constants.GCM_IV_SIZE) {
+      return Failure.with(`IV must be ${CryptoUtils.Constants.GCM_IV_SIZE} bytes, got ${iv.length}`);
     }
-    if (authTag.length !== CryptoConstants.GCM_AUTH_TAG_SIZE) {
+    if (authTag.length !== CryptoUtils.Constants.GCM_AUTH_TAG_SIZE) {
       return Failure.with(
-        `Auth tag must be ${CryptoConstants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`
+        `Auth tag must be ${CryptoUtils.Constants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`
       );
     }
 
@@ -169,7 +185,7 @@ export class BrowserCryptoProvider implements ICryptoProvider {
         {
           name: 'AES-GCM',
           iv: toArrayBuffer(iv),
-          tagLength: CryptoConstants.GCM_AUTH_TAG_SIZE * 8 // bits
+          tagLength: CryptoUtils.Constants.GCM_AUTH_TAG_SIZE * 8 // bits
         },
         cryptoKey,
         encryptedWithTag
@@ -190,7 +206,9 @@ export class BrowserCryptoProvider implements ICryptoProvider {
    */
   public async generateKey(): Promise<Result<Uint8Array>> {
     try {
-      return Success.with(this._crypto.getRandomValues(new Uint8Array(CryptoConstants.AES_256_KEY_SIZE)));
+      return Success.with(
+        this._crypto.getRandomValues(new Uint8Array(CryptoUtils.Constants.AES_256_KEY_SIZE))
+      );
     } catch (e) {
       const message = e instanceof Error ? e.message : String(e);
       return Failure.with(`Key generation failed: ${message}`);
@@ -235,7 +253,7 @@ export class BrowserCryptoProvider implements ICryptoProvider {
           hash: 'SHA-256'
         },
         keyMaterial,
-        CryptoConstants.AES_256_KEY_SIZE * 8 // bits
+        CryptoUtils.Constants.AES_256_KEY_SIZE * 8 // bits
       );
 
       return Success.with(new Uint8Array(derivedBits));
@@ -318,8 +336,211 @@ export class BrowserCryptoProvider implements ICryptoProvider {
       return Failure.with('Invalid base64 string');
     }
   }
+
+  // ============================================================================
+  // Asymmetric Key Operations
+  // ============================================================================
+
+  /**
+   * Generates a new asymmetric keypair via Web Crypto.
+   * @param algorithm - The algorithm to use.
+   * @param extractable - Whether the resulting keys may be exported.
+   * @returns `Success` with the generated `CryptoKeyPair`, or `Failure` with an error.
+   */
+  public async generateKeyPair(
+    algorithm: CryptoUtils.KeyPairAlgorithm,
+    extractable: boolean
+  ): Promise<Result<CryptoKeyPair>> {
+    const params = CryptoUtils.keyPairAlgorithmParams[algorithm];
+    const result = await captureAsyncResult(() =>
+      this._crypto.subtle.generateKey(params.generateKey, extractable, params.keyPairUsages)
+    );
+    return result.withErrorFormat((e) => `Failed to generate ${algorithm} keypair: ${e}`);
+  }
+
+  /**
+   * Exports a public `CryptoKey` as a JSON Web Key.
+   * @remarks
+   * Rejects non-public keys at runtime. WebCrypto's `exportKey('jwk', ...)`
+   * does not enforce public-vs-private; without this guard a caller that
+   * passed an extractable private key would receive its private fields
+   * (`d`, `p`, `q`, ...) as JWK, defeating the method's name.
+   * @param publicKey - Extractable public key to export.
+   * @returns `Success` with the JWK, or `Failure` if not a public key or if export fails.
+   */
+  public async exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>> {
+    if (publicKey.type !== 'public') {
+      return Failure.with(`exportPublicKeyJwk requires a public CryptoKey, got '${publicKey.type}'`);
+    }
+    const result = await captureAsyncResult(() => this._crypto.subtle.exportKey('jwk', publicKey));
+    return result.withErrorFormat((e) => `Failed to export public key as JWK: ${e}`);
+  }
+
+  /**
+   * Imports a public-key JWK as a `CryptoKey` for the requested algorithm.
+   * @param jwk - The JSON Web Key produced by a prior export.
+   * @param algorithm - The algorithm the key was generated for.
+   * @returns `Success` with the imported public `CryptoKey`, or `Failure` with an error.
+   */
+  public async importPublicKeyJwk(
+    jwk: JsonWebKey,
+    algorithm: CryptoUtils.KeyPairAlgorithm
+  ): Promise<Result<CryptoKey>> {
+    const params = CryptoUtils.keyPairAlgorithmParams[algorithm];
+    const result = await captureAsyncResult(() =>
+      this._crypto.subtle.importKey('jwk', jwk, params.importPublicKey, true, params.publicKeyUsages)
+    );
+    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
+      );
+    });
+  });
+});