@fgv/ts-extras 5.1.0-40 → 5.1.0-42

package/dist/ts-extras.d.ts

@@ -381,6 +381,12 @@ declare const allKeyPairAlgorithms: ReadonlyArray<KeyPairAlgorithm>;
  */
 declare const allKeyStoreAsymmetricSecretTypes: ReadonlyArray<KeyStoreAsymmetricSecretType>;
 
+/**
+ * All recognized key store format versions (readable by the current library).
+ * @public
+ */
+declare const allKeyStoreFormats: ReadonlyArray<KeyStoreFormat>;
+
 /**
  * All valid key store secret types.
  * @public
@@ -714,6 +720,7 @@ declare namespace CryptoUtils {
         IDirectEncryptionProviderParams,
         IKeyPairAlgorithmParams,
         keyPairAlgorithmParams,
+        deriveKeyPairFromSeed,
         NodeCryptoProvider,
         nodeCryptoProvider,
         createEncryptedFile,
@@ -730,6 +737,7 @@ declare namespace CryptoUtils {
         MultibaseSpkiPublicKeyRegExp,
         multibaseBase64UrlDecode,
         multibaseBase64UrlEncode,
+        spkiToRawX25519,
         HpkeProvider,
         IHpkeSealResult,
         isEncryptedFile,
@@ -738,7 +746,9 @@ declare namespace CryptoUtils {
         EncryptedFileFormat,
         INamedSecret,
         IEncryptionResult,
+        IEncryptBytesResult,
         KeyPairAlgorithm,
+        SeedDerivableAlgorithm,
         IWrapBytesOptions,
         IWrappedBytes,
         allKeyPairAlgorithms,
@@ -833,6 +843,41 @@ declare const DEFAULT_RANGEOF_FORMATS: RangeOfFormats;
  */
 declare const DEFAULT_SECRET_ITERATIONS: number;
 
+/**
+ * Derives an asymmetric keypair *deterministically* from a fixed secret seed
+ * using `globalThis.crypto.subtle`, shared by the Node and browser
+ * {@link CryptoUtils.ICryptoProvider} implementations (both speak the same
+ * WebCrypto API). See
+ * {@link CryptoUtils.ICryptoProvider.importKeyPairFromSeed | importKeyPairFromSeed}
+ * for the public contract.
+ *
+ * For `'ed25519'`: wraps the 32-byte seed in the RFC 8410 PKCS#8 envelope, then
+ * runs a transient-extractable-then-derive dance so the public key is
+ * recoverable even when the caller requests a non-extractable private key:
+ *
+ * 1. Import the PKCS#8 as a *transient* extractable private key.
+ * 2. Export it to JWK to read the deterministic public coordinate `x`.
+ * 3. Import `{ kty: 'OKP', crv: 'Ed25519', x }` as the returned public key.
+ * 4. For the returned private key: reuse the transient key when `extractable`
+ *    is `true`; otherwise re-import the same PKCS#8 as a non-extractable key.
+ *    The transient extractable key is never returned when `extractable` is
+ *    `false`, so seed material cannot escape through it.
+ *
+ * The seed bytes are copied into a freshly allocated PKCS#8 buffer, so the
+ * `BufferSource` handed to WebCrypto is always backed by a plain `ArrayBuffer`
+ * (side-stepping the Node-20 `SharedArrayBuffer`-view rejection) and the
+ * caller's `seed` is never mutated.
+ *
+ * @param algorithm - The seed-derivable algorithm; only `'ed25519'` is
+ * supported today. Any other value fails loudly rather than being mis-handled.
+ * @param seed - The 32-byte secret seed. Any other length fails loudly, before
+ * any WebCrypto call.
+ * @param extractable - Whether the returned private key may be exported.
+ * @returns `Success` with the derived `CryptoKeyPair`, or `Failure` with error context.
+ * @public
+ */
+declare function deriveKeyPairFromSeed(algorithm: SeedDerivableAlgorithm, seed: Uint8Array, extractable: boolean): Promise<Result<CryptoKeyPair>>;
+
 /**
  * An {@link IEncryptionProvider} that uses a pre-supplied key and crypto provider.
  *
@@ -1435,15 +1480,23 @@ declare class HpkeProvider {
      *
      * @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.
+     *   **Must be extractable** (`extractable: true`) only when `recipientPublicKey` is not
+     *   supplied — the recipient's public key bytes are then recovered from the JWK `x` field
+     *   during Decap. When `recipientPublicKey` is supplied, `recipientPrivateKey` may be
+     *   non-extractable.
      * @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.
+     * @param recipientPublicKey - Optional raw 32-byte X25519 public key matching
+     *   `recipientPrivateKey` (`pkRm` in RFC 9180 §4.1). Public material — supplying it lets
+     *   Decap build `kem_context` without exporting `recipientPrivateKey` to JWK, so
+     *   `recipientPrivateKey` no longer needs to be extractable. A mismatched value only breaks
+     *   the caller's own decryption (AEAD authentication fails) — it cannot be used to attack
+     *   another party's ciphertext.
      * @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>>;
+    openBase(recipientPrivateKey: CryptoKey, info: Uint8Array, aad: Uint8Array, enc: Uint8Array, ciphertext: Uint8Array, recipientPublicKey?: Uint8Array): Promise<Result<Uint8Array>>;
     /**
      * HKDF-SHA256 key derivation (RFC 5869). Extract-then-Expand using SHA-256.
      *
@@ -1508,6 +1561,28 @@ declare interface IAddKeyPairOptions {
      * downgrading.
      */
     readonly extractable?: boolean;
+    /**
+     * Opt in to private-key escrow. When `true`, an encrypted copy of the
+     * private key (as a JWK) is carried inside the vault entry
+     * (`escrowedPrivateKeyJwk`), enabling cross-device recovery from the vault
+     * file plus the master password alone via
+     * `getKeyPair(name, { rehydrate: true })`.
+     *
+     * Orthogonal to `extractable`: the escrow copy is always captured (the
+     * transient keypair is generated extractable so it can be exported to JWK),
+     * while the LIVE stored key's extractability still follows the normal rule
+     * (`extractable` override, else the backend default). So escrow does not
+     * change how extractable the day-to-day key is — only whether a recovery
+     * copy is retained in the vault.
+     *
+     * @defaultValue false — no escrow copy is written (today's behavior).
+     *
+     * SECURITY: escrow makes the master password the sole gate protecting a
+     * private key that would otherwise be unrecoverable from the vault. Use a
+     * strong KDF (Argon2id-derived or high-iteration PBKDF2) for escrow-bearing
+     * stores. See the {@link CryptoUtils.KeyStore.KeyStore} class docs.
+     */
+    readonly escrow?: boolean;
 }
 
 /**
@@ -2681,6 +2756,68 @@ declare interface ICryptoProvider {
      * @returns Success with decrypted UTF-8 string, or Failure with error
      */
     decrypt(encryptedData: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array): Promise<Result<string>>;
+    /**
+     * Encrypts raw bytes using AES-256-GCM with a **caller-supplied nonce** and
+     * optional additional authenticated data (AAD).
+     *
+     * This is the raw-byte sibling of {@link CryptoUtils.ICryptoProvider.encrypt | encrypt}.
+     * Unlike `encrypt`, it takes and returns `Uint8Array` (no UTF-8 coding), the
+     * caller owns the nonce (rather than the provider generating one), and it
+     * binds optional `aad` into the GCM authentication. Use it when you need to
+     * bind context (e.g. an actor id, key version, or row kind) into the
+     * authentication so a wrapped secret cannot be replayed across
+     * users/versions/kinds, or when you manage nonces yourself.
+     *
+     * @remarks
+     * **⚠️ NONCE UNIQUENESS IS THE CALLER'S RESPONSIBILITY AND IS CRITICAL.**
+     * Because the caller supplies the nonce, this primitive cannot guarantee
+     * uniqueness. Reusing a `(key, nonce)` pair for two different messages is
+     * **catastrophic** for AES-GCM: it breaks confidentiality (the XOR of the two
+     * plaintexts leaks) AND authentication (the GCM authentication key can be
+     * recovered, letting an attacker forge tags for arbitrary messages under that
+     * key). The caller MUST use a unique nonce for every message encrypted under a
+     * given key — draw it from {@link CryptoUtils.ICryptoProvider.generateRandomBytes | generateRandomBytes(12)}
+     * (12 random bytes has negligible collision probability well within a single
+     * key's message budget) or from a strictly-increasing counter. Never hardcode
+     * a nonce and never reuse one.
+     *
+     * @param key - 32-byte AES-256 key. Wrong lengths fail with error context.
+     * @param nonce - 12-byte (96-bit) GCM nonce. MUST be unique per message under
+     * `key` (see the nonce-uniqueness warning above). Wrong lengths fail with
+     * error context.
+     * @param plaintext - The bytes to encrypt. Empty plaintext is permitted and
+     * round-trips (GCM produces a valid tag over zero-length plaintext).
+     * @param aad - Optional additional authenticated data bound into the GCM tag
+     * but NOT encrypted. If provided at encrypt time, the identical bytes must be
+     * supplied to `decryptBytes` or decryption fails authentication. Absent means
+     * no AAD.
+     * @returns `Success` with the {@link CryptoUtils.IEncryptBytesResult | ciphertext and 16-byte auth tag},
+     * or `Failure` with error context.
+     */
+    encryptBytes(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Promise<Result<IEncryptBytesResult>>;
+    /**
+     * Decrypts raw bytes produced by
+     * {@link CryptoUtils.ICryptoProvider.encryptBytes | encryptBytes} using
+     * AES-256-GCM. The inverse of `encryptBytes`: the `ciphertext` and `authTag`
+     * from an `encryptBytes` result, together with the same `key`, `nonce`, and
+     * `aad`, recover the original plaintext.
+     *
+     * Fails (never throws) on any authentication failure: a tampered ciphertext
+     * or tag, the wrong key or nonce, or an `aad` that differs from the one used
+     * at encrypt time. AES-GCM authentication is fail-closed — a mismatched `aad`
+     * fails exactly as a tampered ciphertext does.
+     *
+     * @param key - 32-byte AES-256 key (the same key used to encrypt).
+     * @param nonce - 12-byte (96-bit) GCM nonce (the same nonce used to encrypt).
+     * @param ciphertext - The ciphertext from the `encryptBytes` result.
+     * @param authTag - The 16-byte (128-bit) GCM authentication tag from the
+     * `encryptBytes` result.
+     * @param aad - The identical additional authenticated data supplied at encrypt
+     * time (or absent if none was supplied). A mismatch fails authentication.
+     * @returns `Success` with the decrypted plaintext bytes, or `Failure` with
+     * error context (including all authentication failures).
+     */
+    decryptBytes(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, authTag: Uint8Array, aad?: Uint8Array): Promise<Result<Uint8Array>>;
     /**
      * Generates a random 32-byte key suitable for AES-256.
      * @returns Success with generated key, or Failure with error
@@ -2737,6 +2874,28 @@ declare interface ICryptoProvider {
      * @returns Success with the generated `CryptoKeyPair`, or Failure with error context.
      */
     generateKeyPair(algorithm: KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;
+    /**
+     * Derives an asymmetric keypair *deterministically* from a fixed secret seed.
+     * The same `seed` always yields the same keypair on every runtime, so this is
+     * the primitive to use when a keypair must be reconstructable from stored seed
+     * material (key escrow, HD-style derivation, deterministic test vectors) rather
+     * than freshly sampled by {@link CryptoUtils.ICryptoProvider.generateKeyPair | generateKeyPair}.
+     *
+     * For `'ed25519'` the private key *is* its 32-byte seed and the public key is a
+     * deterministic function of that seed (RFC 8032), so the returned public key is
+     * recovered even when the caller requests a non-extractable private key. The
+     * transient extractable key used internally to recover the public half is never
+     * returned or logged when `extractable` is `false`.
+     * @param algorithm - The {@link CryptoUtils.SeedDerivableAlgorithm | seed-derivable algorithm}.
+     * Only `'ed25519'` is supported today; any other value fails loudly with context.
+     * @param seed - The secret seed. For `'ed25519'` it must be exactly 32 bytes;
+     * any other length fails loudly, before any WebCrypto call. The bytes are copied,
+     * not retained or mutated.
+     * @param extractable - Whether the returned private key may be exported. The
+     * returned public key is identical for a given seed regardless of this flag.
+     * @returns Success with the derived `CryptoKeyPair`, or Failure with error context.
+     */
+    importKeyPairFromSeed(algorithm: SeedDerivableAlgorithm, seed: Uint8Array, extractable: boolean): Promise<Result<CryptoKeyPair>>;
     /**
      * Exports the public half of a keypair as a JSON Web Key.
      * @param publicKey - The public `CryptoKey` to export. Must be an `extractable`
@@ -2905,6 +3064,34 @@ declare interface IDirectEncryptionProviderParams {
     readonly boundSecretName?: string;
 }
 
+/**
+ * Result of a raw-byte AES-256-GCM encryption via
+ * {@link CryptoUtils.ICryptoProvider.encryptBytes | encryptBytes}. The
+ * authentication tag is returned separately from the ciphertext, mirroring the
+ * separated-tag convention of {@link CryptoUtils.IEncryptionResult}. The exact
+ * byte layout is:
+ * - `ciphertext`: the AES-GCM ciphertext, byte-for-byte the same length as the
+ *   input plaintext (GCM is a stream cipher — no padding). Empty plaintext
+ *   yields an empty `ciphertext`.
+ * - `authTag`: the 16-byte (128-bit) GCM authentication tag, computed over the
+ *   ciphertext, the nonce, and any `aad`.
+ *
+ * The caller persists both fields alongside the (caller-owned) nonce and feeds
+ * them back to {@link CryptoUtils.ICryptoProvider.decryptBytes | decryptBytes}.
+ * @public
+ */
+declare interface IEncryptBytesResult {
+    /**
+     * The AES-256-GCM ciphertext. Same length as the input plaintext (no tag
+     * appended — the tag is carried separately in the `authTag` field).
+     */
+    readonly ciphertext: Uint8Array;
+    /**
+     * The 16-byte (128-bit) GCM authentication tag.
+     */
+    readonly authTag: Uint8Array;
+}
+
 /**
  * Generic encrypted file format.
  * This is the JSON structure stored in encrypted files.
@@ -3278,6 +3465,26 @@ declare interface IGenerateJsonCompletionResult<T> {
     readonly response: IAiCompletionResponse;
 }
 
+/**
+ * Options for retrieving an asymmetric keypair via {@link CryptoUtils.KeyStore.KeyStore.getKeyPair}.
+ * @public
+ */
+declare interface IGetKeyPairOptions {
+    /**
+     * Opt in to escrow rehydration. When `true` AND no private-key blob exists
+     * under the entry's storage `id` AND the entry carries an
+     * `escrowedPrivateKeyJwk`, the escrowed JWK is imported (non-extractable
+     * where the backend supports it) and stored under the entry's `id` before
+     * being returned — filling a gap on a fresh device from the recovered vault.
+     *
+     * Fill-a-gap only: an existing storage blob is never overwritten. When a
+     * blob is present it is loaded as usual and the escrow copy is ignored.
+     *
+     * @defaultValue false — today's behavior: load from storage or fail.
+     */
+    readonly rehydrate?: boolean;
+}
+
 /**
  * Provider-specific config for gpt-image-1.
  * @public
@@ -3453,6 +3660,21 @@ declare interface IKeyStoreAsymmetricEntry {
      * The public key as a JSON Web Key.
      */
     readonly publicKeyJwk: JsonWebKey;
+    /**
+     * Optional escrowed copy of the private key, as a JSON Web Key. Present only
+     * when the entry was created with `addKeyPair(name, { escrow: true })`.
+     *
+     * This is an opt-in cross-device recovery affordance: the private key is
+     * carried inside the vault's AES-GCM ciphertext (same custody class as
+     * `publicKeyJwk`), so a recovered vault plus the master password can
+     * reconstitute the signing/decryption identity on a fresh device via
+     * `getKeyPair(name, { rehydrate: true })`.
+     *
+     * SECURITY: when present, the master password becomes the sole gate
+     * protecting this private key. Use a strong KDF for escrow-bearing stores.
+     * See the {@link CryptoUtils.KeyStore.KeyStore} class docs.
+     */
+    readonly escrowedPrivateKeyJwk?: JsonWebKey;
     /**
      * Optional description for this entry.
      */
@@ -3491,6 +3713,12 @@ declare interface IKeyStoreAsymmetricEntryJson {
      * The public key as a JSON Web Key.
      */
     readonly publicKeyJwk: JsonWebKey;
+    /**
+     * Optional escrowed copy of the private key, as a JSON Web Key. Present only
+     * on `'keystore-v2'` vaults whose entry was created with escrow enabled. A
+     * v1 vault omits the field; a v2 reader treats its absence as "no escrow".
+     */
+    readonly escrowedPrivateKeyJwk?: JsonWebKey;
     /**
      * Optional description.
      */
@@ -4604,6 +4832,7 @@ declare namespace KeyStore {
         allKeyPairAlgorithms,
         KeyPairAlgorithm,
         KeyStoreFormat,
+        allKeyStoreFormats,
         KEYSTORE_FORMAT,
         DEFAULT_KEYSTORE_ITERATIONS,
         MIN_SALT_LENGTH,
@@ -4635,6 +4864,7 @@ declare namespace KeyStore {
         IAddSecretFromPasswordResult,
         IAddSecretFromPasswordArgon2idOptions,
         IAddKeyPairOptions,
+        IGetKeyPairOptions,
         IAddKeyPairResult,
         IRemoveSecretResult,
         IPrivateKeyStorage
@@ -4670,6 +4900,20 @@ declare namespace KeyStore {
  * const encryptionConfig = keystore2.getEncryptionConfig().orThrow();
  * ```
  *
+ * @remarks
+ * SECURITY — private-key escrow. By default an asymmetric keypair's private
+ * key lives only in the per-device {@link CryptoUtils.KeyStore.IPrivateKeyStorage}
+ * backend; the vault carries only the public JWK, so a vault recovered on a new
+ * device reconstitutes with no private keys (a lost device is a lost identity).
+ * `addKeyPair(name, { escrow: true })` opts into carrying an encrypted private-key
+ * copy inside the vault ciphertext, so the vault file plus the master password can
+ * recover the identity on a fresh device via `getKeyPair(name, { rehydrate: true })`.
+ *
+ * When escrow is used, **the master password becomes the sole gate** protecting a
+ * private signing/decryption key that was previously unrecoverable from the vault.
+ * Configure escrow-bearing stores with a strong KDF — an Argon2id-derived master
+ * key or a high-iteration PBKDF2 count — and treat the vault file accordingly.
+ *
  * @public
  */
 declare class KeyStore_2 implements IEncryptionProvider {
@@ -4776,6 +5020,12 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * Gets a secret by name. Returns the {@link CryptoUtils.KeyStore.IKeyStoreEntry | discriminated union}
      * — callers must check `entry.type` before accessing `key`/`id` since asymmetric
      * entries carry no raw key material.
+     *
+     * SECURITY: for an escrow-enabled asymmetric-keypair entry the returned object
+     * carries `escrowedPrivateKeyJwk` in cleartext (same custody class as
+     * `publicKeyJwk`, gated by the same unlock) — do not log or serialize a
+     * `getSecret()` result casually.
+     *
      * @param name - Name of the secret
      * @returns Success with secret entry, Failure if not found or locked
      * @public
@@ -4962,12 +5212,23 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * the keystore never caches private `CryptoKey` references between calls.
      * The public key is re-imported from the vault's JWK so callers always
      * receive a `CryptoKey` rather than the JWK form.
+     *
+     * With `options.rehydrate: true`, if the storage backend holds no blob for
+     * the entry's `id` and the entry carries an `escrowedPrivateKeyJwk` (see
+     * `addKeyPair(name, { escrow: true })`), the escrowed JWK is imported and
+     * stored under the entry's `id` before being returned — recovering the
+     * private key on a fresh device from the vault plus master password. This is
+     * fill-a-gap only: an existing storage blob is never overwritten.
+     *
      * @param name - Name of the entry
+     * @param options - Optional {@link CryptoUtils.KeyStore.IGetKeyPairOptions}
+     * (currently the `rehydrate` escrow-recovery flag).
      * @returns Success with `{ publicKey, privateKey }`, Failure if not found,
-     * locked, wrong type, no provider, or storage load failed.
+     * locked, wrong type, no provider, or storage load (and any escrow
+     * rehydration) failed.
      * @public
      */
-    getKeyPair(name: string): Promise<Result<{
+    getKeyPair(name: string, options?: IGetKeyPairOptions): Promise<Result<{
         publicKey: CryptoKey;
         privateKey: CryptoKey;
     }>>;
@@ -5053,6 +5314,40 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @returns A warning string if storage cleanup failed, otherwise undefined.
      */
     private _releaseEntryResources;
+    /**
+     * Exports the transient extractable private `CryptoKey` to a JWK for escrow,
+     * via WebCrypto's `exportKey('jwk', ...)` (cross-runtime through
+     * `globalThis.crypto.subtle`). The result is carried in the vault entry — the
+     * same custody class as the public JWK — and is never returned from a public
+     * method nor logged.
+     */
+    private _exportPrivateKeyJwk;
+    /**
+     * Re-imports an escrowed private-key JWK as a `CryptoKey` for `algorithm`
+     * with the requested extractability. The WebCrypto JWK-import descriptor is
+     * shared between the public and private halves for every supported algorithm,
+     * so `IKeyPairAlgorithmParams.importPublicKey` is reused; the private/public
+     * distinction is carried by the requested usages (see
+     * {@link KeyStore._privateKeyUsagesFor}). Cross-runtime through
+     * `globalThis.crypto.subtle`.
+     */
+    private _importEscrowedPrivateKey;
+    /**
+     * Loads the private key for `entry` from storage, or — when
+     * `options.rehydrate` is set, storage holds no blob, and the entry carries an
+     * escrowed JWK — imports the escrowed key, persists it under the entry's `id`
+     * (fill-a-gap; never overwrites an existing blob), and returns it.
+     */
+    private _loadOrRehydratePrivateKey;
+    /**
+     * Computes the key usages to request when importing an escrowed private JWK.
+     * Mirrors `EncryptedFilePrivateKeyStorage`: intersect the algorithm's private
+     * usages (its keypair usages minus the public-only ones) with the JWK's
+     * recorded `key_ops` so we request exactly the operations the stored key
+     * supports; fall back to the algorithm's private usages when `key_ops` is
+     * absent.
+     */
+    private static _privateKeyUsagesFor;
     /**
      * Constant-time byte comparison. Returns false immediately for length
      * mismatch (length is not secret); for equal-length inputs, walks the full
@@ -5069,7 +5364,7 @@ declare class KeyStore_2 implements IEncryptionProvider {
 }
 
 /**
- * Current format version constant.
+ * Current format version constant. New vaults are written as `'keystore-v2'`.
  * @public
  */
 declare const KEYSTORE_FORMAT: KeyStoreFormat;
@@ -5107,9 +5402,15 @@ declare const keystoreFile: Converter<IKeyStoreFile>;
 
 /**
  * Format version for key store files.
+ *
+ * - `'keystore-v1'`: the original format (no private-key escrow).
+ * - `'keystore-v2'`: adds the optional `escrowedPrivateKeyJwk` field on
+ *   asymmetric-keypair entries. A strict superset of v1 — the field is
+ *   optional, so a v2 reader opens a v1 vault with no special-casing, and a
+ *   v1 vault opened and re-saved is silently upgraded to v2.
  * @public
  */
-declare type KeyStoreFormat = 'keystore-v1';
+declare type KeyStoreFormat = 'keystore-v1' | 'keystore-v2';
 
 /**
  * Converter for {@link CryptoUtils.KeyStore.KeyStoreFormat | key store format} version.
@@ -5447,6 +5748,30 @@ declare class NodeCryptoProvider implements ICryptoProvider {
      * @returns `Success` with decrypted UTF-8 string, or `Failure` with an error.
      */
     decrypt(encryptedData: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array): Promise<Result<string>>;
+    /**
+     * 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`.
+     * @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<IEncryptBytesResult>>;
+    /**
+     * Decrypts raw bytes produced by {@link NodeCryptoProvider.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>>;
     /**
      * Generates a random 32-byte key suitable for AES-256.
      * @returns `Success` with generated key, or `Failure` with an error.
@@ -5497,6 +5822,14 @@ declare class NodeCryptoProvider implements ICryptoProvider {
      * @returns `Success` with the generated `CryptoKeyPair`, or `Failure` with an error.
      */
     generateKeyPair(algorithm: KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;
+    /**
+     * Derives an asymmetric keypair deterministically from a fixed secret seed.
+     * @param algorithm - The seed-derivable algorithm (only `'ed25519'` today).
+     * @param seed - The 32-byte secret seed.
+     * @param extractable - Whether the returned private key may be exported.
+     * @returns `Success` with the derived `CryptoKeyPair`, or `Failure` with an error.
+     */
+    importKeyPairFromSeed(algorithm: SeedDerivableAlgorithm, seed: Uint8Array, extractable: boolean): Promise<Result<CryptoKeyPair>>;
     /**
      * Exports a public `CryptoKey` as a JSON Web Key.
      * @remarks
@@ -5948,6 +6281,21 @@ declare function resolveProviderModel(descriptor: IAiProviderDescriptor, modelOv
  */
 declare type SecretProvider = (secretName: string) => Promise<Result<Uint8Array>>;
 
+/**
+ * The subset of {@link CryptoUtils.KeyPairAlgorithm} whose keypair can be
+ * derived *deterministically* from a fixed secret seed, for use with
+ * {@link CryptoUtils.ICryptoProvider.importKeyPairFromSeed | importKeyPairFromSeed}.
+ *
+ * Only `'ed25519'` is supported today: an Ed25519 private key *is* a 32-byte
+ * seed and its public key is a deterministic function of that seed (RFC 8032),
+ * so the same seed always yields the same keypair on every runtime. The type is
+ * a proper subset because algorithms like RSA or the NIST curves are not
+ * recoverable from a bare seed. It is intentionally left open to grow (e.g.
+ * `'x25519'`) without a breaking change.
+ * @public
+ */
+declare type SeedDerivableAlgorithm = 'ed25519';
+
 /**
  * Default system-prompt suffix appended when {@link AiAssist.IGenerateJsonCompletionParams.promptHint}
  * is `'smart'` (the default). Designed to discourage code fences and prose in
@@ -5956,6 +6304,22 @@ declare type SecretProvider = (secretName: string) => Promise<Result<Uint8Array>
  */
 declare const SMART_JSON_PROMPT_HINT: string;
 
+/**
+ * Strips the fixed DER prefix from an X25519 SubjectPublicKeyInfo blob, returning the raw
+ * 32-byte public key.
+ *
+ * An X25519 SPKI is always exactly 44 bytes: a fixed 12-byte prefix (SEQUENCE / AlgorithmIdentifier
+ * with OID 1.3.101.110 / BIT STRING) followed by the 32-byte raw key. Use this to convert a
+ * SPKI-held recipient public key into the raw form accepted by {@link HpkeProvider.openBase}'s
+ * `recipientPublicKey` parameter.
+ *
+ * @param spki - The DER-encoded X25519 SubjectPublicKeyInfo bytes.
+ * @returns `Success` with the raw 32-byte public key, or `Failure` if `spki` is not a
+ *   well-formed 44-byte X25519 SPKI blob.
+ * @public
+ */
+declare function spkiToRawX25519(spki: Uint8Array): Result<Uint8Array>;
+
 /**
  * Whether a provider declares any embedding capability at all.
  *

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

@@ -93,15 +93,23 @@ export declare class HpkeProvider {
      *
      * @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.
+     *   **Must be extractable** (`extractable: true`) only when `recipientPublicKey` is not
+     *   supplied — the recipient's public key bytes are then recovered from the JWK `x` field
+     *   during Decap. When `recipientPublicKey` is supplied, `recipientPrivateKey` may be
+     *   non-extractable.
      * @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.
+     * @param recipientPublicKey - Optional raw 32-byte X25519 public key matching
+     *   `recipientPrivateKey` (`pkRm` in RFC 9180 §4.1). Public material — supplying it lets
+     *   Decap build `kem_context` without exporting `recipientPrivateKey` to JWK, so
+     *   `recipientPrivateKey` no longer needs to be extractable. A mismatched value only breaks
+     *   the caller's own decryption (AEAD authentication fails) — it cannot be used to attack
+     *   another party's ciphertext.
      * @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>>;
+    openBase(recipientPrivateKey: CryptoKey, info: Uint8Array, aad: Uint8Array, enc: Uint8Array, ciphertext: Uint8Array, recipientPublicKey?: Uint8Array): Promise<Result<Uint8Array>>;
     /**
      * HKDF-SHA256 key derivation (RFC 5869). Extract-then-Expand using SHA-256.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"hpkeProvider.d.ts","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/hpkeProvider.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,MAAM,EAAoD,MAAM,eAAe,CAAC;AAoOzF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC,OAAO;IAIP;;;;;;;OAOG;WACW,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAIhE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,QAAQ,CACnB,kBAAkB,EAAE,SAAS,EAC7B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IAenC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACU,QAAQ,CACnB,mBAAmB,EAAE,SAAS,EAC9B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,UAAU,EACf,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAuB9B;;;;;;;;;;;;;OAaG;IACU,IAAI,CACf,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAQ9B;;;;;;;;OAQG;WACW,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,UAAU;IAIjE;;;;;;;;;OASG;WACW,cAAc,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAAC,eAAe,CAAC;CAY5E"}
+{"version":3,"file":"hpkeProvider.d.ts","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/hpkeProvider.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,MAAM,EAAoD,MAAM,eAAe,CAAC;AA+OzF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC,OAAO;IAIP;;;;;;;OAOG;WACW,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAIhE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,QAAQ,CACnB,kBAAkB,EAAE,SAAS,EAC7B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IAenC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACU,QAAQ,CACnB,mBAAmB,EAAE,SAAS,EAC9B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,UAAU,EACf,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,UAAU,EACtB,kBAAkB,CAAC,EAAE,UAAU,GAC9B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IA4B9B;;;;;;;;;;;;;OAaG;IACU,IAAI,CACf,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAQ9B;;;;;;;;OAQG;WACW,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,UAAU;IAIjE;;;;;;;;;OASG;WACW,cAAc,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAAC,eAAe,CAAC;CAY5E"}