@fgv/ts-extras 5.1.0-27 → 5.1.0-28

package/dist/ts-extras.d.ts

@@ -317,6 +317,25 @@ declare const allProviderIds: ReadonlyArray<AiProviderId>;
  */
 declare type AnthropicThinkingModelNames = 'claude-sonnet-4-5' | 'claude-sonnet-4-6' | 'claude-opus-4-6' | 'claude-opus-4-7';
 
+/**
+ * Recommended OWASP 2023 minimum Argon2id parameters.
+ * Suitable for recovery-row key derivation (high-entropy inputs).
+ * @public
+ */
+declare const ARGON2ID_OWASP_MIN: IArgon2idParams;
+
+/**
+ * Stronger Argon2id parameters suitable for user-typed passphrases.
+ * @public
+ */
+declare const ARGON2ID_PASSPHRASE: IArgon2idParams;
+
+/**
+ * Converter for {@link CryptoUtils.IArgon2idKeyDerivationParams | Argon2id key derivation parameters}.
+ * @public
+ */
+declare const argon2idKeyDerivationParams: Converter<IArgon2idKeyDerivationParams>;
+
 /**
  * Converter for base64 strings (validates format).
  * @public
@@ -481,6 +500,8 @@ declare namespace Converters_3 {
         encryptedFileFormat,
         encryptedFileErrorMode,
         keyDerivationFunction,
+        pbkdf2KeyDerivationParams,
+        argon2idKeyDerivationParams,
         keyDerivationParams,
         base64String,
         uint8ArrayFromBase64,
@@ -534,6 +555,8 @@ declare namespace CryptoUtils {
         importPublicKeyFromMultibaseSpki,
         multibaseBase64UrlDecode,
         multibaseBase64UrlEncode,
+        HpkeProvider,
+        IHpkeSealResult,
         isEncryptedFile,
         EncryptionAlgorithm,
         EncryptedFileFormat,
@@ -544,7 +567,13 @@ declare namespace CryptoUtils {
         IWrappedBytes,
         allKeyPairAlgorithms,
         KeyDerivationFunction,
+        IPbkdf2KeyDerivationParams,
+        IArgon2idKeyDerivationParams,
         IKeyDerivationParams,
+        IArgon2idParams,
+        ARGON2ID_OWASP_MIN,
+        ARGON2ID_PASSPHRASE,
+        IArgon2idProvider,
         IEncryptedFile,
         ICryptoProvider,
         IEncryptionProvider,
@@ -1035,6 +1064,128 @@ declare namespace Hash {
 }
 export { Hash }
 
+/**
+ * HPKE base mode (RFC 9180) — `DHKEM(X25519, HKDF-SHA256) + HKDF-SHA256 + AES-256-GCM`.
+ *
+ * Class-based provider that captures a `SubtleCrypto` instance at construction,
+ * matching the existing `NodeCryptoProvider` / `BrowserCryptoProvider` / `KeyStore`
+ * factory pattern used throughout `@fgv/ts-extras/crypto-utils`.
+ *
+ * **Node.js usage:**
+ * ```typescript
+ * import * as crypto from 'crypto';
+ * const hpke = HpkeProvider.create(crypto.webcrypto.subtle).orThrow();
+ * ```
+ *
+ * **Browser usage:**
+ * ```typescript
+ * const hpke = HpkeProvider.create(globalThis.crypto.subtle).orThrow();
+ * ```
+ *
+ * **Runtime requirements:** Node.js 20+ (X25519 in `crypto.webcrypto`);
+ * Chrome 113+, Safari 16.4+, Firefox 118+ (X25519 added to Web Crypto in 2023).
+ * @public
+ */
+declare class HpkeProvider {
+    private readonly _subtle;
+    private constructor();
+    /**
+     * Creates an `HpkeProvider` bound to the given `SubtleCrypto` instance.
+     *
+     * @param subtle - Web Crypto SubtleCrypto instance.
+     *   Node.js: `(await import('crypto')).webcrypto.subtle`.
+     *   Browser: `globalThis.crypto.subtle`.
+     * @returns `Success` with the provider, or `Failure` if construction fails.
+     */
+    static create(subtle: SubtleCrypto): Result<HpkeProvider>;
+    /**
+     * HPKE base-mode seal (sender side). RFC 9180 §6.1.
+     *
+     * Generates a fresh ephemeral X25519 keypair, runs DHKEM Encap to produce a
+     * shared secret and `enc` (32-byte raw ephemeral public key), derives the AEAD
+     * key and nonce deterministically via the RFC 9180 key schedule, then encrypts
+     * `plaintext` with AES-256-GCM.
+     *
+     * @param recipientPublicKey - Recipient's X25519 public `CryptoKey`
+     *   (`algorithm.name === 'X25519'`, `type === 'public'`, **`extractable: true`**).
+     *   Must be extractable — DHKEM Encap calls `exportKey('raw', ...)` on this key to
+     *   build the KEM shared-secret context. Keys imported with `extractable: false` will
+     *   cause this method to return a `Failure`.
+     * @param info - Context-binding bytes. **Load-bearing — no default.**
+     *   Binds this ciphertext to a specific application context, preventing replay
+     *   across different contexts sharing the same recipient keypair.
+     *   Use `new TextEncoder().encode('myapp/v1/use-case\x00' + contextId)` pattern.
+     *   Never pass an empty array in production: empty `info` provides no context binding.
+     * @param aad - Additional authenticated data. Integrity-protected but not encrypted.
+     *   `new Uint8Array(0)` is valid when no AAD is needed.
+     * @param plaintext - Bytes to encrypt. `new Uint8Array(0)` is valid.
+     * @returns `Success` with `{ enc, ciphertext }`, or `Failure` with error context.
+     */
+    sealBase(recipientPublicKey: CryptoKey, info: Uint8Array, aad: Uint8Array, plaintext: Uint8Array): Promise<Result<IHpkeSealResult>>;
+    /**
+     * HPKE base-mode open (recipient side). RFC 9180 §6.1.
+     *
+     * Decapsulates `enc` using the recipient's X25519 private key, derives the same
+     * AEAD key and nonce from the shared secret and `info`, then authenticates and
+     * decrypts `ciphertext` with AES-256-GCM.
+     *
+     * Returns `Failure` on any of:
+     * - Wrong private key (different DH output → different key derivation)
+     * - Wrong `info` (different key schedule context → different AEAD key)
+     * - Wrong `aad` (AES-GCM authentication fails)
+     * - Tampered `ciphertext` or `enc` (authentication fails or DH fails)
+     * - `enc` not exactly 32 bytes
+     * - `ciphertext` shorter than 16 bytes (no room for authentication tag)
+     *
+     * @param recipientPrivateKey - Recipient's X25519 private `CryptoKey`
+     *   (`algorithm.name === 'X25519'`, `type === 'private'`, `usages` includes `'deriveBits'`).
+     *   **Must be extractable** (`extractable: true`) — the recipient's public key bytes
+     *   are recovered from the JWK `x` field during Decap.
+     * @param info - Context-binding bytes. Must exactly match `info` from `sealBase`.
+     * @param aad - Must exactly match `aad` from `sealBase`.
+     * @param enc - The encapsulated key from `sealBase` — exactly 32 bytes.
+     * @param ciphertext - The ciphertext from `sealBase` — `plaintext.length + 16` bytes.
+     * @returns `Success` with decrypted plaintext bytes, or `Failure` with error context.
+     */
+    openBase(recipientPrivateKey: CryptoKey, info: Uint8Array, aad: Uint8Array, enc: Uint8Array, ciphertext: Uint8Array): Promise<Result<Uint8Array>>;
+    /**
+     * HKDF-SHA256 key derivation (RFC 5869). Extract-then-Expand using SHA-256.
+     *
+     * This is raw RFC 5869 HKDF — it does **not** use RFC 9180's labeled variants.
+     * The HPKE key schedule internally uses labeled HKDF; this method is the unlabeled
+     * version for callers that need standalone key derivation.
+     *
+     * @param secret - Input keying material (IKM). Any length.
+     * @param salt - Optional salt. Use `new Uint8Array(0)` if no salt is available
+     *   (RFC 5869: 32 zero bytes are used internally when salt is empty).
+     * @param info - Context / application-binding bytes. Any length.
+     * @param length - Number of output bytes to derive. Maximum 8160 bytes (255 × 32).
+     * @returns `Success` with derived bytes, or `Failure` with error context.
+     */
+    hkdf(secret: Uint8Array, salt: Uint8Array, info: Uint8Array, length: number): Promise<Result<Uint8Array>>;
+    /**
+     * Encodes an {@link IHpkeSealResult} as a single contiguous byte array for wire transport.
+     *
+     * Format: `enc` (32 bytes, fixed) || `ciphertext` (variable length).
+     * The 32-byte `enc` length is fixed for X25519; the split point is unambiguous.
+     *
+     * @param result - The output of {@link HpkeProvider.sealBase}.
+     * @returns Concatenated bytes: `enc || ciphertext`.
+     */
+    static encodeEnvelope(result: IHpkeSealResult): Uint8Array;
+    /**
+     * Decodes an envelope produced by {@link HpkeProvider.encodeEnvelope}.
+     *
+     * Validates that the buffer is at least 48 bytes (32-byte enc + 16-byte minimum
+     * ciphertext containing the AES-GCM auth tag; zero-length plaintext is the minimum
+     * meaningful case).
+     *
+     * @param envelope - Envelope bytes from `encodeEnvelope`.
+     * @returns `Success` with `{ enc, ciphertext }`, or `Failure` if malformed.
+     */
+    static decodeEnvelope(envelope: Uint8Array): Result<IHpkeSealResult>;
+}
+
 /**
  * Options for adding an asymmetric keypair to the key store.
  * @public
@@ -1079,6 +1230,25 @@ declare interface IAddKeyPairResult {
     readonly warning?: string;
 }
 
+/**
+ * Options for adding an Argon2id password-derived secret.
+ * @public
+ */
+declare interface IAddSecretFromPasswordArgon2idOptions {
+    /**
+     * Argon2id parameters. Defaults to {@link CryptoUtils.ARGON2ID_OWASP_MIN}.
+     */
+    readonly params?: IArgon2idParams;
+    /**
+     * Optional description for the secret.
+     */
+    readonly description?: string;
+    /**
+     * Whether to replace an existing secret with the same name.
+     */
+    readonly replace?: boolean;
+}
+
 /**
  * Options for adding a secret derived from a password.
  * @public
@@ -1615,6 +1785,81 @@ declare interface IAnthropicThinkingOptions {
     readonly config: IAnthropicThinkingConfig;
 }
 
+/**
+ * Argon2id key derivation parameters (RFC 9106).
+ * @public
+ */
+declare interface IArgon2idKeyDerivationParams {
+    /** Key derivation function discriminator. */
+    readonly kdf: 'argon2id';
+    /** Base64-encoded salt used for key derivation. */
+    readonly salt: string;
+    /** Memory cost in kibibytes. */
+    readonly memoryKiB: number;
+    /** Number of passes (time cost). */
+    readonly iterations: number;
+    /** Degree of parallelism. */
+    readonly parallelism: number;
+}
+
+/**
+ * Parameters for Argon2id key derivation (RFC 9106).
+ * All fields are required; fgv does not pick defaults silently.
+ * @public
+ */
+declare interface IArgon2idParams {
+    /**
+     * Memory cost in kibibytes (KiB).
+     * OWASP 2023 minimum: 19456 (19 MiB). Stronger: 65536 (64 MiB).
+     * Constraint: \>= 8.
+     */
+    readonly memoryKiB: number;
+    /**
+     * Number of passes (iterations / time cost).
+     * OWASP 2023 minimum: 2. Range: \>= 1.
+     */
+    readonly iterations: number;
+    /**
+     * Degree of parallelism (threads).
+     * Note: WASM-based implementations compute sequentially regardless of this value,
+     * but the value is wired into the algorithm and AFFECTS the output hash bytes.
+     * Callers must use the same parallelism value consistently for a given secret.
+     * Range: 1–255.
+     */
+    readonly parallelism: number;
+    /**
+     * Number of output bytes (hash length).
+     * Typical values: 16 (128-bit), 32 (256-bit, AES-256 key), 64 (512-bit).
+     * Constraint: \>= 4.
+     */
+    readonly outputBytes: number;
+}
+
+/**
+ * Argon2id key derivation provider (RFC 9106).
+ *
+ * Implementations are in separate packages to avoid WASM bundle costs for
+ * consumers who don't need Argon2id:
+ * - Node: `@fgv/ts-extras-argon2` (`NodeArgon2Provider`)
+ * - Browser: `@fgv/ts-web-extras-argon2` (`BrowserArgon2Provider`)
+ *
+ * @public
+ */
+declare interface IArgon2idProvider {
+    /**
+     * Derives key material from a password using Argon2id (RFC 9106 §3.1).
+     *
+     * Returns the raw derived bytes as a `Uint8Array`. Both Node and browser
+     * implementations produce bit-identical output for identical inputs.
+     *
+     * @param password - Password or passphrase. Accepts string (UTF-8) or raw bytes.
+     * @param salt - Salt bytes. Must be random and unique per credential (\>= 16 bytes recommended).
+     * @param params - Argon2id parameters. Use `ARGON2ID_OWASP_MIN` as a starting point.
+     * @returns Success with derived bytes, Failure with error context.
+     */
+    argon2id(password: Uint8Array | string, salt: Uint8Array, params: IArgon2idParams): Promise<Result<Uint8Array>>;
+}
+
 /**
  * A single chat message in OpenAI format.
  * @public
@@ -1845,6 +2090,80 @@ declare interface ICryptoProvider {
      * @returns `Success` with the original `plaintext`, or `Failure` with error context.
      */
     unwrapBytes(wrapped: IWrappedBytes, recipientPrivateKey: CryptoKey, options: IWrapBytesOptions): Promise<Result<Uint8Array>>;
+    /**
+     * Signs `data` with `privateKey` using the algorithm inferred from the key.
+     * Delegates to `crypto.subtle.sign`; the algorithm is derived from
+     * `privateKey.algorithm.name` — ECDSA keys are augmented with
+     * `hash: 'SHA-256'` at sign time (the hash is not stored in the key);
+     * all other algorithm names are passed through as-is.
+     * Intended for Ed25519 and ECDSA-P256 asymmetric private keys; for
+     * HMAC-SHA256 authentication codes use {@link ICryptoProvider.hmacSha256} instead.
+     * @param privateKey - A `CryptoKey` with `'sign'` usage (e.g. generated by
+     * {@link CryptoUtils.ICryptoProvider.generateKeyPair | generateKeyPair} with
+     * `'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 ICryptoProvider.sign}.
+     * Delegates to `crypto.subtle.verify`; the algorithm is derived from
+     * `publicKey.algorithm.name` — ECDSA keys are augmented with
+     * `hash: 'SHA-256'`; all other algorithm names are passed through as-is.
+     * Intended for Ed25519 and ECDSA-P256 asymmetric public keys; for
+     * HMAC-SHA256 verification use {@link ICryptoProvider.verifyHmacSha256} instead.
+     * @param publicKey - A `CryptoKey` with `'verify'` usage (e.g. the public
+     * half of a keypair generated by
+     * {@link CryptoUtils.ICryptoProvider.generateKeyPair | generateKeyPair} with
+     * `'ecdsa-p256'` or `'ed25519'`).
+     * @param signature - The raw signature bytes produced by `sign`.
+     * @param data - The original data that was signed.
+     * @returns `Success` with `true` if the signature is valid, `false` if it is
+     * not, or `Failure` with error context if the operation itself failed.
+     */
+    verify(publicKey: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean>>;
+    /**
+     * Compares two byte arrays in constant time.
+     *
+     * The comparison visits all bytes of `a` and `b` regardless of where they
+     * diverge, accumulating XOR differences with bitwise-OR. No early-return is
+     * possible once the length check passes, making timing independent of the
+     * byte values. This prevents timing side-channels when comparing MAC outputs,
+     * signed-token bytes, or any secret-derived byte sequences.
+     *
+     * Returns `false` immediately (before the loop) when `a.length !== b.length`;
+     * the length mismatch itself is not secret in normal use.
+     * @param a - First byte array.
+     * @param b - Second byte array.
+     * @returns `true` if the arrays have the same length and identical contents,
+     * `false` otherwise.
+     */
+    timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+    /**
+     * Computes an HMAC-SHA256 authentication code for `data` using `key`.
+     *
+     * The key must be a `CryptoKey` with `'sign'` usage and algorithm name
+     * `'HMAC'` (e.g. derived via PBKDF2 or imported with
+     * `crypto.subtle.importKey`). Use {@link ICryptoProvider.verifyHmacSha256}
+     * for constant-time verification of the output.
+     * @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 authentication code in constant time.
+     *
+     * Computes the expected MAC over `data` with `key`, then compares it to
+     * `signature` using {@link ICryptoProvider.timingSafeEqual} so that
+     * mismatches do not leak information through timing.
+     * @param key - An HMAC `CryptoKey` with `'sign'` usage.
+     * @param signature - The MAC bytes to verify (typically 32 bytes).
+     * @param data - The original data that was authenticated.
+     * @returns `Success` with `true` if the MAC is valid, `false` if it is not,
+     * or `Failure` with error context if the MAC computation itself failed.
+     */
+    verifyHmacSha256(key: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean>>;
 }
 
 /**
@@ -2181,6 +2500,26 @@ declare interface IGrokImagineModelOptions extends INamedModelFamilyConfig {
     readonly config: IGrokImagineImageGenerationConfig;
 }
 
+/**
+ * Output of {@link HpkeProvider.sealBase}.
+ *
+ * The `ciphertext` field includes the 16-byte AES-256-GCM authentication tag
+ * appended by Web Crypto's `encrypt()` operation: `length = plaintext.length + 16`.
+ * @public
+ */
+declare interface IHpkeSealResult {
+    /**
+     * Encapsulated key — 32-byte raw X25519 ephemeral public key (`enc` in RFC 9180).
+     * Must be transmitted to the recipient alongside `ciphertext`.
+     */
+    readonly enc: Uint8Array;
+    /**
+     * AES-256-GCM ciphertext with the 16-byte authentication tag appended.
+     * Length = `plaintext.length + 16`.
+     */
+    readonly ciphertext: Uint8Array;
+}
+
 /**
  * Provider-specific config for Google Imagen 4 models.
  * @public
@@ -2239,23 +2578,10 @@ declare interface IImportSecretOptions extends IAddSecretOptions {
 
 /**
  * Key derivation parameters stored in encrypted files.
- * Allows decryption with password without needing to know the original salt/iterations.
+ * Discriminated union on `kdf` field: `'pbkdf2'` or `'argon2id'`.
  * @public
  */
-declare interface IKeyDerivationParams {
-    /**
-     * Key derivation function used.
-     */
-    readonly kdf: KeyDerivationFunction;
-    /**
-     * Base64-encoded salt used for key derivation.
-     */
-    readonly salt: string;
-    /**
-     * Number of iterations used for key derivation.
-     */
-    readonly iterations: number;
-}
+declare type IKeyDerivationParams = IPbkdf2KeyDerivationParams | IArgon2idKeyDerivationParams;
 
 /**
  * WebCrypto parameters for a single {@link CryptoUtils.KeyPairAlgorithm}.
@@ -2436,9 +2762,9 @@ declare interface IKeyStoreFile {
      */
     readonly encryptedData: string;
     /**
-     * Key derivation parameters (required for key store - always password-derived).
+     * Key derivation parameters for the vault master key (always PBKDF2).
      */
-    readonly keyDerivation: IKeyDerivationParams;
+    readonly keyDerivation: IPbkdf2KeyDerivationParams;
 }
 
 /**
@@ -2743,6 +3069,19 @@ declare interface IOtherThinkingOptions {
     readonly config: JsonObject;
 }
 
+/**
+ * PBKDF2 key derivation parameters.
+ * @public
+ */
+declare interface IPbkdf2KeyDerivationParams {
+    /** Key derivation function discriminator. */
+    readonly kdf: 'pbkdf2';
+    /** Base64-encoded salt used for key derivation. */
+    readonly salt: string;
+    /** Number of iterations used for key derivation. */
+    readonly iterations: number;
+}
+
 /**
  * Pluggable backend that persists raw asymmetric private keys outside of the
  * encrypted keystore vault. Concrete implementations live in platform-specific
@@ -3253,7 +3592,7 @@ declare const jsonWebKeyShape: Validator<JsonWebKey>;
  * Supported key derivation functions.
  * @public
  */
-declare type KeyDerivationFunction = 'pbkdf2';
+declare type KeyDerivationFunction = 'pbkdf2' | 'argon2id';
 
 /**
  * Converter for {@link CryptoUtils.KeyDerivationFunction | key derivation function} type.
@@ -3263,6 +3602,7 @@ declare const keyDerivationFunction: Converter<KeyDerivationFunction>;
 
 /**
  * Converter for {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+ * Handles both PBKDF2 and Argon2id discriminated union arms.
  * @public
  */
 declare const keyDerivationParams: Converter<IKeyDerivationParams>;
@@ -3341,6 +3681,7 @@ declare namespace KeyStore {
         IAddSecretFromPasswordOptions,
         DEFAULT_SECRET_ITERATIONS,
         IAddSecretFromPasswordResult,
+        IAddSecretFromPasswordArgon2idOptions,
         IAddKeyPairOptions,
         IAddKeyPairResult,
         IRemoveSecretResult,
@@ -3577,6 +3918,36 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @public
      */
     verifySecretFromPassword(name: string, password: string, keyDerivation: IKeyDerivationParams): Promise<Result<boolean>>;
+    /**
+     * Adds a secret derived from a password using Argon2id (RFC 9106).
+     *
+     * The Argon2id provider must be supplied explicitly; the KeyStore does not
+     * hold one by default (consumers opt in by depending on the argon2 package).
+     *
+     * Returns the key derivation parameters so callers can store them alongside
+     * encrypted artifacts, enabling future re-derivation and verification.
+     *
+     * @param name - Unique name for the secret
+     * @param password - Password or passphrase
+     * @param argon2idProvider - Argon2id provider (Node or Browser implementation)
+     * @param options - Optional: Argon2id params (defaults to ARGON2ID_OWASP_MIN), description, replace flag
+     * @returns Success with entry and keyDerivation params, Failure if locked or invalid
+     * @public
+     */
+    addSecretFromPasswordArgon2id(name: string, password: string, argon2idProvider: IArgon2idProvider, options?: IAddSecretFromPasswordArgon2idOptions): Promise<Result<IAddSecretFromPasswordResult>>;
+    /**
+     * Verifies a candidate password against an Argon2id-derived entry using the
+     * supplied key derivation parameters. Constant-time comparison.
+     *
+     * @param name - Name of the secret to verify against
+     * @param password - Candidate password to test
+     * @param argon2idProvider - Argon2id provider (must produce bit-identical output for identical inputs)
+     * @param keyDerivation - The Argon2id key derivation parameters returned by `addSecretFromPasswordArgon2id`
+     * @returns Success(true) if candidate matches stored key, Success(false) if not,
+     * Failure if locked, secret missing, wrong type, or derivation fails
+     * @public
+     */
+    verifySecretFromPasswordArgon2id(name: string, password: string, argon2idProvider: IArgon2idProvider, keyDerivation: IArgon2idKeyDerivationParams): Promise<Result<boolean>>;
     /**
      * Removes a secret by name. Vault-first: the in-memory vault entry is dropped
      * before any storage cleanup runs. For asymmetric-keypair entries, best-effort
@@ -4129,6 +4500,45 @@ declare class NodeCryptoProvider implements ICryptoProvider {
      * @returns `Success` with the imported public `CryptoKey`, or `Failure` with error context.
      */
     importPublicKeySpki(spkiBytes: Uint8Array, algorithm: 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 NodeCryptoProvider.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 using Node's native
+     * `crypto.timingSafeEqual`. Returns `false` for mismatched lengths
+     * rather than throwing (Node's native throws on length mismatch).
+     * @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
@@ -4181,6 +4591,12 @@ declare function parseCsvString(body: string, options?: CsvOptions): Result<unkn
  */
 declare function parseRecordJarLines(lines: string[], options?: JarRecordParserOptions): Result<JarRecord[]>;
 
+/**
+ * Converter for {@link CryptoUtils.IPbkdf2KeyDerivationParams | PBKDF2 key derivation parameters}.
+ * @public
+ */
+declare const pbkdf2KeyDerivationParams: Converter<IPbkdf2KeyDerivationParams>;
+
 /**
  * Simple implementation of a possibly open-ended range of some comparable
  * type `<T>` with test and formatting.

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.57.7"
+      "packageVersion": "7.58.7"
     }
   ]
 }

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

@@ -1,6 +1,6 @@
 import { JsonValue } from '@fgv/ts-json-base';
 import { Converter } from '@fgv/ts-utils';
-import { EncryptedFileErrorMode, EncryptedFileFormat, EncryptionAlgorithm, IEncryptedFile, IKeyDerivationParams, INamedSecret, KeyDerivationFunction } from './model';
+import { EncryptedFileErrorMode, EncryptedFileFormat, EncryptionAlgorithm, IArgon2idKeyDerivationParams, IEncryptedFile, IKeyDerivationParams, INamedSecret, IPbkdf2KeyDerivationParams, KeyDerivationFunction } from './model';
 /**
  * Converter for {@link CryptoUtils.EncryptionAlgorithm | encryption algorithm} values.
  * @public
@@ -21,8 +21,19 @@ export declare const encryptedFileErrorMode: Converter<EncryptedFileErrorMode>;
  * @public
  */
 export declare const keyDerivationFunction: Converter<KeyDerivationFunction>;
+/**
+ * Converter for {@link CryptoUtils.IPbkdf2KeyDerivationParams | PBKDF2 key derivation parameters}.
+ * @public
+ */
+export declare const pbkdf2KeyDerivationParams: Converter<IPbkdf2KeyDerivationParams>;
+/**
+ * Converter for {@link CryptoUtils.IArgon2idKeyDerivationParams | Argon2id key derivation parameters}.
+ * @public
+ */
+export declare const argon2idKeyDerivationParams: Converter<IArgon2idKeyDerivationParams>;
 /**
  * Converter for {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+ * Handles both PBKDF2 and Argon2id discriminated union arms.
  * @public
  */
 export declare const keyDerivationParams: Converter<IKeyDerivationParams>;

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

@@ -1 +1 @@
-{"version":3,"file":"converters.d.ts","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/converters.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAgC,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAA6B,MAAM,eAAe,CAAC;AAErE,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAMjB;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,CAAC,mBAAmB,CACiB,CAAC;AAEjF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,CAAC,mBAAmB,CAE7D,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,CAAC,sBAAsB,CACS,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,CAAC,qBAAqB,CACJ,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,CAAC,oBAAoB,CAI9D,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,CAAC,MAAM,CAOzC,CAAC;AAMH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,CAAC,UAAU,CAoBrD,CAAC;AAMH;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,CAAC,YAAY,CAG9C,CAAC;AAsCH;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,GAAG,SAAS,EAChE,iBAAiB,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,GACvC,SAAS,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAyBtC;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,CAAC,cAAc,CAAkC,CAAC"}
+{"version":3,"file":"converters.d.ts","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/converters.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAgC,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAA6B,MAAM,eAAe,CAAC;AAErE,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,4BAA4B,EAC5B,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAMjB;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,CAAC,mBAAmB,CACiB,CAAC;AAEjF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,CAAC,mBAAmB,CAE7D,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,CAAC,sBAAsB,CACS,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,CAAC,qBAAqB,CACQ,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,CAAC,0BAA0B,CAKxE,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,CAAC,4BAA4B,CAO5E,CAAC;AAEL;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,CAAC,oBAAoB,CAG9D,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,CAAC,MAAM,CAOzC,CAAC;AAMH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,CAAC,UAAU,CAoBrD,CAAC;AAMH;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,CAAC,YAAY,CAG9C,CAAC;AAsCH;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,GAAG,SAAS,EAChE,iBAAiB,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,GACvC,SAAS,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAyBtC;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,CAAC,cAAc,CAAkC,CAAC"}

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

@@ -52,7 +52,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.encryptedFile = exports.namedSecret = exports.uint8ArrayFromBase64 = exports.base64String = exports.keyDerivationParams = exports.keyDerivationFunction = exports.encryptedFileErrorMode = exports.encryptedFileFormat = exports.encryptionAlgorithm = void 0;
+exports.encryptedFile = exports.namedSecret = exports.uint8ArrayFromBase64 = exports.base64String = exports.keyDerivationParams = exports.argon2idKeyDerivationParams = exports.pbkdf2KeyDerivationParams = exports.keyDerivationFunction = exports.encryptedFileErrorMode = exports.encryptedFileFormat = exports.encryptionAlgorithm = void 0;
 exports.createEncryptedFileConverter = createEncryptedFileConverter;
 const ts_json_base_1 = require("@fgv/ts-json-base");
 const ts_utils_1 = require("@fgv/ts-utils");
@@ -81,16 +81,36 @@ exports.encryptedFileErrorMode = ts_utils_1.Converters.enumeratedValue(['fail',
  * Converter for {@link CryptoUtils.KeyDerivationFunction | key derivation function} type.
  * @public
  */
-exports.keyDerivationFunction = ts_utils_1.Converters.enumeratedValue(['pbkdf2']);
+exports.keyDerivationFunction = ts_utils_1.Converters.enumeratedValue(['pbkdf2', 'argon2id']);
 /**
- * Converter for {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+ * Converter for {@link CryptoUtils.IPbkdf2KeyDerivationParams | PBKDF2 key derivation parameters}.
  * @public
  */
-exports.keyDerivationParams = ts_utils_1.Converters.object({
-    kdf: exports.keyDerivationFunction,
+exports.pbkdf2KeyDerivationParams = ts_utils_1.Converters.object({
+    kdf: ts_utils_1.Converters.enumeratedValue(['pbkdf2']),
     salt: ts_utils_1.Converters.string,
     iterations: ts_utils_1.Converters.number
 });
+/**
+ * Converter for {@link CryptoUtils.IArgon2idKeyDerivationParams | Argon2id key derivation parameters}.
+ * @public
+ */
+exports.argon2idKeyDerivationParams = ts_utils_1.Converters.object({
+    kdf: ts_utils_1.Converters.enumeratedValue(['argon2id']),
+    salt: ts_utils_1.Converters.string,
+    memoryKiB: ts_utils_1.Converters.number,
+    iterations: ts_utils_1.Converters.number,
+    parallelism: ts_utils_1.Converters.number
+});
+/**
+ * Converter for {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+ * Handles both PBKDF2 and Argon2id discriminated union arms.
+ * @public
+ */
+exports.keyDerivationParams = ts_utils_1.Converters.oneOf([
+    exports.pbkdf2KeyDerivationParams,
+    exports.argon2idKeyDerivationParams
+]);
 /**
  * Converter for base64 strings (validates format).
  * @public