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

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,135 @@ 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>>;
+    /**
+     * 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.
+     */
+    encryptBytes(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Promise<Result<CryptoUtils.IEncryptBytesResult>>;
+    /**
+     * 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.
+     */
+    decryptBytes(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, authTag: Uint8Array, aad?: Uint8Array): Promise<Result<Uint8Array>>;
+    /**
+     * 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 +213,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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"}