@fgv/ts-web-extras 5.1.0-4 → 5.1.0-41

package/dist/packlets/crypto-utils/browserCryptoProvider.js

@@ -17,10 +17,9 @@
 // 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.
-/* c8 ignore start - Browser-only implementation cannot be tested in Node.js environment */
-import { captureResult, Failure, Success } from '@fgv/ts-utils';
+import { captureAsyncResult, captureResult, fail, Failure, succeed, Success } from '@fgv/ts-utils';
 import { CryptoUtils } from '@fgv/ts-extras';
-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
@@ -32,6 +31,24 @@ function toArrayBuffer(arr) {
     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) {
+    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.
  * Uses AES-256-GCM for authenticated encryption.
@@ -42,6 +59,7 @@ function toArrayBuffer(arr) {
  * @public
  */
 export class BrowserCryptoProvider {
+    /* 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)
@@ -67,12 +85,12 @@ export class BrowserCryptoProvider {
      * @returns `Success` with encryption result, or `Failure` with an error.
      */
     async encrypt(plaintext, key) {
-        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}`);
         }
         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('raw', toArrayBuffer(key), { name: 'AES-GCM' }, false, ['encrypt']);
             // Encode plaintext to bytes
@@ -82,12 +100,12 @@ export class BrowserCryptoProvider {
             const encryptedWithTag = await this._crypto.subtle.encrypt({
                 name: 'AES-GCM',
                 iv: iv,
-                tagLength: CryptoConstants.GCM_AUTH_TAG_SIZE * 8 // bits
+                tagLength: CryptoUtils.Constants.GCM_AUTH_TAG_SIZE * 8 // bits
             }, cryptoKey, plaintextBytes);
             // Split ciphertext and auth tag (auth tag is last 16 bytes)
             const encryptedArray = new Uint8Array(encryptedWithTag);
-            const encryptedData = encryptedArray.slice(0, encryptedArray.length - CryptoConstants.GCM_AUTH_TAG_SIZE);
-            const authTag = encryptedArray.slice(encryptedArray.length - CryptoConstants.GCM_AUTH_TAG_SIZE);
+            const encryptedData = encryptedArray.slice(0, encryptedArray.length - CryptoUtils.Constants.GCM_AUTH_TAG_SIZE);
+            const authTag = encryptedArray.slice(encryptedArray.length - CryptoUtils.Constants.GCM_AUTH_TAG_SIZE);
             return Success.with({
                 iv,
                 authTag,
@@ -108,14 +126,14 @@ export class BrowserCryptoProvider {
      * @returns `Success` with decrypted UTF-8 string, or `Failure` with an error.
      */
     async decrypt(encryptedData, key, iv, authTag) {
-        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) {
-            return Failure.with(`Auth tag must be ${CryptoConstants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`);
+        if (authTag.length !== CryptoUtils.Constants.GCM_AUTH_TAG_SIZE) {
+            return Failure.with(`Auth tag must be ${CryptoUtils.Constants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`);
         }
         try {
             // Import the key
@@ -128,7 +146,7 @@ export class BrowserCryptoProvider {
             const decrypted = await this._crypto.subtle.decrypt({
                 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);
             // Decode to string
             const decoder = new TextDecoder();
@@ -145,7 +163,7 @@ export class BrowserCryptoProvider {
      */
     async generateKey() {
         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);
@@ -180,7 +198,7 @@ export class BrowserCryptoProvider {
                 salt: toArrayBuffer(salt),
                 iterations: iterations,
                 hash: 'SHA-256'
-            }, keyMaterial, CryptoConstants.AES_256_KEY_SIZE * 8 // bits
+            }, keyMaterial, CryptoUtils.Constants.AES_256_KEY_SIZE * 8 // bits
             );
             return Success.with(new Uint8Array(derivedBits));
         }
@@ -189,6 +207,27 @@ export class BrowserCryptoProvider {
             return Failure.with(`Key derivation failed: ${message}`);
         }
     }
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns `Success` with hex-encoded hash string, or `Failure` with an error.
+     */
+    async sha256(data) {
+        try {
+            const encoder = new TextEncoder();
+            const dataBuffer = encoder.encode(data);
+            const hashBuffer = await this._crypto.subtle.digest('SHA-256', dataBuffer);
+            const hashArray = new Uint8Array(hashBuffer);
+            const hashHex = Array.from(hashArray)
+                .map((b) => b.toString(16).padStart(2, '0'))
+                .join('');
+            return succeed(hashHex);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return fail(`SHA-256 hash failed: ${message}`);
+        }
+    }
     // ============================================================================
     // Platform Utility Methods
     // ============================================================================
@@ -209,6 +248,21 @@ export class BrowserCryptoProvider {
             return Failure.with(`Random bytes generation failed: ${message}`);
         }
     }
+    /* c8 ignore stop */
+    /**
+     * Generates a cryptographically random UUIDv4 using the injected
+     * `Crypto` instance.
+     * @returns `Success` with the generated UUID, or `Failure` if the underlying
+     * `Crypto` instance does not expose `randomUUID`.
+     */
+    generateUuid() {
+        /* c8 ignore next 3 - randomUUID is always available in supported runtimes (Node 22+, modern browsers) */
+        if (typeof this._crypto.randomUUID !== 'function') {
+            return Failure.with('Crypto instance does not expose randomUUID');
+        }
+        return captureResult(() => this._crypto.randomUUID());
+    }
+    /* c8 ignore start - browser-only methods continue */
     /**
      * Encodes binary data to base64 string.
      * @param data - Binary data to encode
@@ -240,7 +294,348 @@ export class BrowserCryptoProvider {
             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.
+     */
+    async generateKeyPair(algorithm, extractable) {
+        const params = CryptoUtils.keyPairAlgorithmParams[algorithm];
+        // Widening upcast to `AlgorithmIdentifier` steers TS to subtle.generateKey's
+        // broad overload, which accepts the Ed25519 `{ name: 'Ed25519' }` shape and
+        // returns `CryptoKey | CryptoKeyPair`. The narrowing back to `CryptoKeyPair`
+        // is a runtime check via the `in` operator, not a type assertion.
+        const result = await captureAsyncResult(async () => {
+            const generated = await this._crypto.subtle.generateKey(params.generateKey, extractable, [...params.keyPairUsages]);
+            if ('privateKey' in generated && 'publicKey' in generated) {
+                return generated;
+            }
+            /* c8 ignore next - unreachable: every entry in keyPairAlgorithmParams produces a keypair */
+            throw new Error(`${algorithm} unexpectedly produced a single CryptoKey`);
+        });
+        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.
+     */
+    async exportPublicKeyJwk(publicKey) {
+        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.
+     */
+    async importPublicKeyJwk(jwk, algorithm) {
+        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}`);
+    }
+    /**
+     * Exports a public `CryptoKey` as a DER-encoded SPKI blob.
+     * @param publicKey - The public `CryptoKey` to export.
+     * @returns `Success` with the raw SPKI bytes, or `Failure` with error context.
+     */
+    async exportPublicKeySpki(publicKey) {
+        if (publicKey.type !== 'public') {
+            return Failure.with(`exportPublicKeySpki requires a public CryptoKey, got '${publicKey.type}'`);
+        }
+        const result = await captureAsyncResult(() => this._crypto.subtle.exportKey('spki', publicKey));
+        return result
+            .withErrorFormat((e) => `exportPublicKeySpki: failed to export key: ${e}`)
+            .onSuccess((buf) => succeed(new Uint8Array(buf)));
+    }
+    /**
+     * Imports a public key from a DER-encoded SPKI blob.
+     * @param spkiBytes - The raw SPKI bytes.
+     * @param algorithm - The algorithm the key was generated for.
+     * @returns `Success` with the imported public `CryptoKey`, or `Failure` with error context.
+     */
+    async importPublicKeySpki(spkiBytes, algorithm) {
+        const params = CryptoUtils.keyPairAlgorithmParams[algorithm];
+        const result = await captureAsyncResult(() => this._crypto.subtle.importKey('spki', toBufferView(spkiBytes), params.importPublicKey, true, [...params.publicKeyUsages]));
+        return result.withErrorFormat((e) => `importPublicKeySpki: failed to import ${algorithm} public key from SPKI: ${e}`);
+    }
+    /* c8 ignore stop */
+    /**
+     * Signs `data` with `privateKey` using the algorithm inferred from the key.
+     * @param privateKey - A signing `CryptoKey` (`'ecdsa-p256'` or `'ed25519'`).
+     * @param data - The bytes to sign.
+     * @returns `Success` with the raw signature bytes, or `Failure` with error context.
+     */
+    async sign(privateKey, data) {
+        const algorithm = signAlgorithmFromKey(privateKey);
+        const result = await captureAsyncResult(() => this._crypto.subtle.sign(algorithm, privateKey, toBufferView(data)));
+        return result
+            .withErrorFormat((e) => `sign failed: ${e}`)
+            .onSuccess((buf) => succeed(new Uint8Array(buf)));
+    }
+    /**
+     * Verifies a signature produced by {@link BrowserCryptoProvider.sign}.
+     * @param publicKey - A verify `CryptoKey` (`'ecdsa-p256'` or `'ed25519'`).
+     * @param signature - The raw signature bytes.
+     * @param data - The original data that was signed.
+     * @returns `Success` with `true` if valid, `false` if not, or `Failure` with error context.
+     */
+    async verify(publicKey, signature, data) {
+        const algorithm = signAlgorithmFromKey(publicKey);
+        const result = await captureAsyncResult(() => this._crypto.subtle.verify(algorithm, publicKey, toBufferView(signature), toBufferView(data)));
+        return result.withErrorFormat((e) => `verify failed: ${e}`);
+    }
+    /**
+     * Compares two byte arrays in constant time.
+     *
+     * Accumulates XOR differences with bitwise-OR; no early-return is possible
+     * once the length check passes, making timing independent of the byte
+     * values. Returns `false` immediately on length mismatch (length is not
+     * secret in normal use).
+     * @param a - First byte array.
+     * @param b - Second byte array.
+     * @returns `true` if lengths match and all bytes are equal, `false` otherwise.
+     */
+    timingSafeEqual(a, b) {
+        if (a.length !== b.length)
+            return false;
+        let diff = 0;
+        for (let i = 0; i < a.length; i++) {
+            // eslint-disable-next-line no-bitwise
+            diff |= a[i] ^ b[i];
+        }
+        return diff === 0;
+    }
+    /**
+     * Computes an HMAC-SHA256 MAC for `data` using `key`.
+     * @param key - An HMAC `CryptoKey` with `'sign'` usage.
+     * @param data - The bytes to authenticate.
+     * @returns `Success` with the 32-byte MAC, or `Failure` with error context.
+     */
+    async hmacSha256(key, data) {
+        const result = await captureAsyncResult(() => this._crypto.subtle.sign({ name: 'HMAC' }, key, toBufferView(data)));
+        return result
+            .withErrorFormat((e) => `hmacSha256 failed: ${e}`)
+            .onSuccess((buf) => succeed(new Uint8Array(buf)));
+    }
+    /**
+     * Verifies an HMAC-SHA256 MAC in constant time.
+     * @param key - An HMAC `CryptoKey` with `'sign'` usage.
+     * @param signature - The MAC bytes to verify.
+     * @param data - The original data that was authenticated.
+     * @returns `Success` with `true` if valid, `false` if not, or `Failure` with error context.
+     */
+    async verifyHmacSha256(key, signature, data) {
+        return (await this.hmacSha256(key, data))
+            .withErrorFormat((e) => `verifyHmacSha256 failed: ${e}`)
+            .onSuccess((mac) => succeed(this.timingSafeEqual(mac, signature)));
+    }
+    /**
+     * Encrypts raw bytes using AES-256-GCM with a caller-supplied nonce and
+     * optional AAD. See {@link CryptoUtils.ICryptoProvider.encryptBytes | ICryptoProvider.encryptBytes}
+     * — in particular the caller's responsibility to use a unique `nonce` per
+     * message under a given `key`.
+     *
+     * Byte-identical to {@link CryptoUtils.NodeCryptoProvider.encryptBytes} for
+     * identical `(key, nonce, plaintext, aad)`: Web Crypto appends the 16-byte tag
+     * to the ciphertext, and this method splits it off so the returned
+     * `ciphertext`/`authTag` match Node's separated-tag layout exactly.
+     * @param key - 32-byte AES-256 key.
+     * @param nonce - 12-byte GCM nonce (must be unique per message under `key`).
+     * @param plaintext - The bytes to encrypt (empty permitted).
+     * @param aad - Optional additional authenticated data bound into the tag.
+     * @returns `Success` with the ciphertext and 16-byte auth tag, or `Failure` with an error.
+     */
+    async encryptBytes(key, nonce, plaintext, aad) {
+        if (key.length !== CryptoUtils.Constants.AES_256_KEY_SIZE) {
+            return Failure.with(`encryptBytes: key must be ${CryptoUtils.Constants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+        }
+        if (nonce.length !== CryptoUtils.Constants.GCM_IV_SIZE) {
+            return Failure.with(`encryptBytes: nonce must be ${CryptoUtils.Constants.GCM_IV_SIZE} bytes, got ${nonce.length}`);
+        }
+        const result = await captureAsyncResult(async () => {
+            const cryptoKey = await this._crypto.subtle.importKey('raw', toBufferView(key), { name: 'AES-GCM' }, false, ['encrypt']);
+            const algorithm = {
+                name: 'AES-GCM',
+                iv: toBufferView(nonce),
+                tagLength: CryptoUtils.Constants.GCM_AUTH_TAG_SIZE * 8 // bits
+            };
+            if (aad !== undefined) {
+                algorithm.additionalData = toBufferView(aad);
+            }
+            const encryptedWithTag = new Uint8Array(await this._crypto.subtle.encrypt(algorithm, cryptoKey, toBufferView(plaintext)));
+            const tagStart = encryptedWithTag.length - CryptoUtils.Constants.GCM_AUTH_TAG_SIZE;
+            return {
+                ciphertext: encryptedWithTag.slice(0, tagStart),
+                authTag: encryptedWithTag.slice(tagStart)
+            };
+        });
+        return result.withErrorFormat((e) => `encryptBytes failed: ${e}`);
+    }
+    /**
+     * Decrypts raw bytes produced by {@link BrowserCryptoProvider.encryptBytes}
+     * using AES-256-GCM. See
+     * {@link CryptoUtils.ICryptoProvider.decryptBytes | ICryptoProvider.decryptBytes}.
+     * Fails (never throws) on any authentication failure, including a mismatched `aad`.
+     * @param key - 32-byte AES-256 key.
+     * @param nonce - 12-byte GCM nonce (the same one used to encrypt).
+     * @param ciphertext - The ciphertext from the `encryptBytes` result.
+     * @param authTag - The 16-byte GCM auth tag from the `encryptBytes` result.
+     * @param aad - The identical AAD supplied at encrypt time (or absent).
+     * @returns `Success` with the decrypted plaintext bytes, or `Failure` with an error.
+     */
+    async decryptBytes(key, nonce, ciphertext, authTag, aad) {
+        if (key.length !== CryptoUtils.Constants.AES_256_KEY_SIZE) {
+            return Failure.with(`decryptBytes: key must be ${CryptoUtils.Constants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+        }
+        if (nonce.length !== CryptoUtils.Constants.GCM_IV_SIZE) {
+            return Failure.with(`decryptBytes: nonce must be ${CryptoUtils.Constants.GCM_IV_SIZE} bytes, got ${nonce.length}`);
+        }
+        if (authTag.length !== CryptoUtils.Constants.GCM_AUTH_TAG_SIZE) {
+            return Failure.with(`decryptBytes: auth tag must be ${CryptoUtils.Constants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`);
+        }
+        const result = await captureAsyncResult(async () => {
+            const cryptoKey = await this._crypto.subtle.importKey('raw', toBufferView(key), { name: 'AES-GCM' }, false, ['decrypt']);
+            // Web Crypto expects ciphertext + auth tag concatenated.
+            const encryptedWithTag = new Uint8Array(ciphertext.length + authTag.length);
+            encryptedWithTag.set(ciphertext);
+            encryptedWithTag.set(authTag, ciphertext.length);
+            const algorithm = {
+                name: 'AES-GCM',
+                iv: toBufferView(nonce),
+                tagLength: CryptoUtils.Constants.GCM_AUTH_TAG_SIZE * 8 // bits
+            };
+            if (aad !== undefined) {
+                algorithm.additionalData = toBufferView(aad);
+            }
+            const decrypted = await this._crypto.subtle.decrypt(algorithm, cryptoKey, encryptedWithTag);
+            return new Uint8Array(decrypted);
+        });
+        return result.withErrorFormat((e) => `decryptBytes failed: ${e}`);
+    }
+    /**
+     * 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.
+     */
+    async wrapBytes(plaintext, recipientPublicKey, options) {
+        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'
+            ]));
+            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.
+     */
+    async unwrapBytes(wrapped, recipientPrivateKey, options) {
+        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}`);
+    }
+}
+/**
+ * Derives the algorithm identifier needed by `crypto.subtle.sign/verify`
+ * from the key's embedded `algorithm` property. ECDSA requires an explicit
+ * `hash` parameter that is not stored on the key object itself; all other
+ * supported signing algorithms (`Ed25519`) use the key algorithm as-is.
+ */
+function signAlgorithmFromKey(key) {
+    if (key.algorithm.name === 'ECDSA') {
+        return { name: 'ECDSA', hash: 'SHA-256' };
+    }
+    return key.algorithm;
+}
+/**
+ * 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, keyType, label) {
+    if (key.algorithm.name !== 'ECDH') {
+        return Failure.with(`${label} must be ECDH P-256 (got algorithm '${key.algorithm.name}')`);
+    }
+    const namedCurve = key.algorithm.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.