@fgv/ts-web-extras 5.1.0-3 → 5.1.0-30

package/lib/packlets/crypto-utils/browserCryptoProvider.d.ts

@@ -1,7 +1,5 @@
-import { Result } from '@fgv/ts-utils';
+import { Result, Uuid } from '@fgv/ts-utils';
 import { CryptoUtils } from '@fgv/ts-extras';
-type ICryptoProvider = CryptoUtils.ICryptoProvider;
-type IEncryptionResult = CryptoUtils.IEncryptionResult;
 /**
  * Browser implementation of `ICryptoProvider` using the Web Crypto API.
  * Uses AES-256-GCM for authenticated encryption.
@@ -11,7 +9,7 @@ type IEncryptionResult = CryptoUtils.IEncryptionResult;
  *
  * @public
  */
-export declare class BrowserCryptoProvider implements ICryptoProvider {
+export declare class BrowserCryptoProvider implements CryptoUtils.ICryptoProvider {
     private readonly _crypto;
     /**
      * Creates a new {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider}.
@@ -24,7 +22,7 @@ export declare class BrowserCryptoProvider implements ICryptoProvider {
      * @param key - 32-byte encryption key
      * @returns `Success` with encryption result, or `Failure` with an error.
      */
-    encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>>;
+    encrypt(plaintext: string, key: Uint8Array): Promise<Result<CryptoUtils.IEncryptionResult>>;
     /**
      * Decrypts ciphertext using AES-256-GCM.
      * @param encryptedData - Encrypted bytes
@@ -47,12 +45,25 @@ export declare class BrowserCryptoProvider implements ICryptoProvider {
      * @returns Success with derived 32-byte key, or Failure with error
      */
     deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * 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.
+     */
+    sha256(data: string): Promise<Result<string>>;
     /**
      * Generates cryptographically secure random bytes.
      * @param length - Number of bytes to generate
      * @returns Success with random bytes, or Failure with error
      */
     generateRandomBytes(length: number): Result<Uint8Array>;
+    /**
+     * 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(): Result<Uuid>;
     /**
      * Encodes binary data to base64 string.
      * @param data - Binary data to encode
@@ -65,6 +76,105 @@ export declare class BrowserCryptoProvider implements ICryptoProvider {
      * @returns Success with decoded bytes, or Failure if invalid base64
      */
     fromBase64(base64: string): Result<Uint8Array>;
+    /**
+     * 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.
+     */
+    generateKeyPair(algorithm: CryptoUtils.KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;
+    /**
+     * 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.
+     */
+    exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>>;
+    /**
+     * 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.
+     */
+    importPublicKeyJwk(jwk: JsonWebKey, algorithm: CryptoUtils.KeyPairAlgorithm): Promise<Result<CryptoKey>>;
+    /**
+     * 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.
+     */
+    exportPublicKeySpki(publicKey: CryptoKey): Promise<Result<Uint8Array>>;
+    /**
+     * 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.
+     */
+    importPublicKeySpki(spkiBytes: Uint8Array, algorithm: CryptoUtils.KeyPairAlgorithm): Promise<Result<CryptoKey>>;
+    /**
+     * 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.
+     */
+    sign(privateKey: CryptoKey, data: Uint8Array): Promise<Result<Uint8Array>>;
+    /**
+     * 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.
+     */
+    verify(publicKey: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean>>;
+    /**
+     * 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: Uint8Array, b: Uint8Array): boolean;
+    /**
+     * 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.
+     */
+    hmacSha256(key: CryptoKey, data: Uint8Array): Promise<Result<Uint8Array>>;
+    /**
+     * 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.
+     */
+    verifyHmacSha256(key: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean>>;
+    /**
+     * 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.
+     */
+    wrapBytes(plaintext: Uint8Array, recipientPublicKey: CryptoKey, options: CryptoUtils.IWrapBytesOptions): Promise<Result<CryptoUtils.IWrappedBytes>>;
+    /**
+     * 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.
+     */
+    unwrapBytes(wrapped: CryptoUtils.IWrappedBytes, recipientPrivateKey: CryptoKey, options: CryptoUtils.IWrapBytesOptions): Promise<Result<Uint8Array>>;
 }
 /**
  * Creates a {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider} if Web
@@ -73,5 +183,4 @@ export declare class BrowserCryptoProvider implements ICryptoProvider {
  * @public
  */
 export declare function createBrowserCryptoProvider(): Result<BrowserCryptoProvider>;
-export {};
 //# sourceMappingURL=browserCryptoProvider.d.ts.map

package/lib/packlets/crypto-utils/browserCryptoProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browserCryptoProvider.d.ts","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/browserCryptoProvider.ts"],"names":[],"mappings":"AAqBA,OAAO,EAA0B,MAAM,EAAW,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,KAAK,eAAe,GAAG,WAAW,CAAC,eAAe,CAAC;AACnD,KAAK,iBAAiB,GAAG,WAAW,CAAC,iBAAiB,CAAC;AAevD;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;OAGG;gBACgB,SAAS,CAAC,EAAE,MAAM;IAYrC;;;;;OAKG;IACU,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAmD5F;;;;;;;OAOG;IACU,OAAO,CAClB,aAAa,EAAE,UAAU,EACzB,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,UAAU,EACd,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAgD1B;;;OAGG;IACU,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IASvD;;;;;;OAMG;IACU,SAAS,CACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAyC9B;;;;OAIG;IACI,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC;IAY9D;;;;OAIG;IACI,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM;IASzC;;;;OAIG;IACI,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC;CAYtD;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,CAAC,qBAAqB,CAAC,CAE3E"}
+{"version":3,"file":"browserCryptoProvider.d.ts","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/browserCryptoProvider.ts"],"names":[],"mappings":"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"}

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

@@ -21,10 +21,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BrowserCryptoProvider = void 0;
 exports.createBrowserCryptoProvider = createBrowserCryptoProvider;
-/* c8 ignore start - Browser-only implementation cannot be tested in Node.js environment */
 const ts_utils_1 = require("@fgv/ts-utils");
 const ts_extras_1 = require("@fgv/ts-extras");
-const CryptoConstants = ts_extras_1.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
@@ -36,6 +35,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.
@@ -46,6 +63,7 @@ function toArrayBuffer(arr) {
  * @public
  */
 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)
@@ -71,12 +89,12 @@ 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 ts_utils_1.Failure.with(`Key must be ${CryptoConstants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+        if (key.length !== ts_extras_1.CryptoUtils.Constants.AES_256_KEY_SIZE) {
+            return ts_utils_1.Failure.with(`Key must be ${ts_extras_1.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(ts_extras_1.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
@@ -86,12 +104,12 @@ class BrowserCryptoProvider {
             const encryptedWithTag = await this._crypto.subtle.encrypt({
                 name: 'AES-GCM',
                 iv: iv,
-                tagLength: CryptoConstants.GCM_AUTH_TAG_SIZE * 8 // bits
+                tagLength: ts_extras_1.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 - ts_extras_1.CryptoUtils.Constants.GCM_AUTH_TAG_SIZE);
+            const authTag = encryptedArray.slice(encryptedArray.length - ts_extras_1.CryptoUtils.Constants.GCM_AUTH_TAG_SIZE);
             return ts_utils_1.Success.with({
                 iv,
                 authTag,
@@ -112,14 +130,14 @@ 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 ts_utils_1.Failure.with(`Key must be ${CryptoConstants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+        if (key.length !== ts_extras_1.CryptoUtils.Constants.AES_256_KEY_SIZE) {
+            return ts_utils_1.Failure.with(`Key must be ${ts_extras_1.CryptoUtils.Constants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
         }
-        if (iv.length !== CryptoConstants.GCM_IV_SIZE) {
-            return ts_utils_1.Failure.with(`IV must be ${CryptoConstants.GCM_IV_SIZE} bytes, got ${iv.length}`);
+        if (iv.length !== ts_extras_1.CryptoUtils.Constants.GCM_IV_SIZE) {
+            return ts_utils_1.Failure.with(`IV must be ${ts_extras_1.CryptoUtils.Constants.GCM_IV_SIZE} bytes, got ${iv.length}`);
         }
-        if (authTag.length !== CryptoConstants.GCM_AUTH_TAG_SIZE) {
-            return ts_utils_1.Failure.with(`Auth tag must be ${CryptoConstants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`);
+        if (authTag.length !== ts_extras_1.CryptoUtils.Constants.GCM_AUTH_TAG_SIZE) {
+            return ts_utils_1.Failure.with(`Auth tag must be ${ts_extras_1.CryptoUtils.Constants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`);
         }
         try {
             // Import the key
@@ -132,7 +150,7 @@ class BrowserCryptoProvider {
             const decrypted = await this._crypto.subtle.decrypt({
                 name: 'AES-GCM',
                 iv: toArrayBuffer(iv),
-                tagLength: CryptoConstants.GCM_AUTH_TAG_SIZE * 8 // bits
+                tagLength: ts_extras_1.CryptoUtils.Constants.GCM_AUTH_TAG_SIZE * 8 // bits
             }, cryptoKey, encryptedWithTag);
             // Decode to string
             const decoder = new TextDecoder();
@@ -149,7 +167,7 @@ class BrowserCryptoProvider {
      */
     async generateKey() {
         try {
-            return ts_utils_1.Success.with(this._crypto.getRandomValues(new Uint8Array(CryptoConstants.AES_256_KEY_SIZE)));
+            return ts_utils_1.Success.with(this._crypto.getRandomValues(new Uint8Array(ts_extras_1.CryptoUtils.Constants.AES_256_KEY_SIZE)));
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
@@ -184,7 +202,7 @@ class BrowserCryptoProvider {
                 salt: toArrayBuffer(salt),
                 iterations: iterations,
                 hash: 'SHA-256'
-            }, keyMaterial, CryptoConstants.AES_256_KEY_SIZE * 8 // bits
+            }, keyMaterial, ts_extras_1.CryptoUtils.Constants.AES_256_KEY_SIZE * 8 // bits
             );
             return ts_utils_1.Success.with(new Uint8Array(derivedBits));
         }
@@ -193,6 +211,27 @@ class BrowserCryptoProvider {
             return ts_utils_1.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 (0, ts_utils_1.succeed)(hashHex);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return (0, ts_utils_1.fail)(`SHA-256 hash failed: ${message}`);
+        }
+    }
     // ============================================================================
     // Platform Utility Methods
     // ============================================================================
@@ -213,6 +252,21 @@ class BrowserCryptoProvider {
             return ts_utils_1.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 ts_utils_1.Failure.with('Crypto instance does not expose randomUUID');
+        }
+        return (0, ts_utils_1.captureResult)(() => this._crypto.randomUUID());
+    }
+    /* c8 ignore start - browser-only methods continue */
     /**
      * Encodes binary data to base64 string.
      * @param data - Binary data to encode
@@ -244,8 +298,266 @@ class BrowserCryptoProvider {
             return ts_utils_1.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 = ts_extras_1.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 (0, ts_utils_1.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 ts_utils_1.Failure.with(`exportPublicKeyJwk requires a public CryptoKey, got '${publicKey.type}'`);
+        }
+        const result = await (0, ts_utils_1.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 = ts_extras_1.CryptoUtils.keyPairAlgorithmParams[algorithm];
+        const result = await (0, ts_utils_1.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 ts_utils_1.Failure.with(`exportPublicKeySpki requires a public CryptoKey, got '${publicKey.type}'`);
+        }
+        const result = await (0, ts_utils_1.captureAsyncResult)(() => this._crypto.subtle.exportKey('spki', publicKey));
+        return result
+            .withErrorFormat((e) => `exportPublicKeySpki: failed to export key: ${e}`)
+            .onSuccess((buf) => (0, ts_utils_1.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 = ts_extras_1.CryptoUtils.keyPairAlgorithmParams[algorithm];
+        const result = await (0, ts_utils_1.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 (0, ts_utils_1.captureAsyncResult)(() => this._crypto.subtle.sign(algorithm, privateKey, toBufferView(data)));
+        return result
+            .withErrorFormat((e) => `sign failed: ${e}`)
+            .onSuccess((buf) => (0, ts_utils_1.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 (0, ts_utils_1.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 (0, ts_utils_1.captureAsyncResult)(() => this._crypto.subtle.sign({ name: 'HMAC' }, key, toBufferView(data)));
+        return result
+            .withErrorFormat((e) => `hmacSha256 failed: ${e}`)
+            .onSuccess((buf) => (0, ts_utils_1.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) => (0, ts_utils_1.succeed)(this.timingSafeEqual(mac, signature)));
+    }
+    /**
+     * 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 ts_utils_1.Failure.with(`wrapBytes failed: ${recipientCheck.message}`);
+        }
+        const subtle = this._crypto.subtle;
+        const result = await (0, ts_utils_1.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(ts_extras_1.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 ts_utils_1.Failure.with(`unwrapBytes failed: ${recipientCheck.message}`);
+        }
+        const nonceResult = this.fromBase64(wrapped.nonce);
+        if (nonceResult.isFailure()) {
+            return ts_utils_1.Failure.with(`unwrapBytes failed: nonce: ${nonceResult.message}`);
+        }
+        if (nonceResult.value.length !== ts_extras_1.CryptoUtils.Constants.GCM_IV_SIZE) {
+            return ts_utils_1.Failure.with(`unwrapBytes failed: nonce must be ${ts_extras_1.CryptoUtils.Constants.GCM_IV_SIZE} bytes (got ${nonceResult.value.length})`);
+        }
+        const ciphertextResult = this.fromBase64(wrapped.ciphertext);
+        if (ciphertextResult.isFailure()) {
+            return ts_utils_1.Failure.with(`unwrapBytes failed: ciphertext: ${ciphertextResult.message}`);
+        }
+        if (ciphertextResult.value.length < ts_extras_1.CryptoUtils.Constants.GCM_AUTH_TAG_SIZE) {
+            return ts_utils_1.Failure.with(`unwrapBytes failed: ciphertext must be at least ${ts_extras_1.CryptoUtils.Constants.GCM_AUTH_TAG_SIZE} bytes (got ${ciphertextResult.value.length})`);
+        }
+        const subtle = this._crypto.subtle;
+        const result = await (0, ts_utils_1.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}`);
+    }
 }
 exports.BrowserCryptoProvider = BrowserCryptoProvider;
+/**
+ * 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 ts_utils_1.Failure.with(`${label} must be ECDH P-256 (got algorithm '${key.algorithm.name}')`);
+    }
+    const namedCurve = key.algorithm.namedCurve;
+    if (namedCurve !== 'P-256') {
+        return ts_utils_1.Failure.with(`${label} must be ECDH P-256 (got curve '${namedCurve}')`);
+    }
+    if (key.type !== keyType) {
+        return ts_utils_1.Failure.with(`${label} must be a ${keyType} CryptoKey (got '${key.type}')`);
+    }
+    return (0, ts_utils_1.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.