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

package/lib/packlets/crypto-utils/keystore/model.d.ts

@@ -1,11 +1,24 @@
-import { EncryptionAlgorithm, ICryptoProvider, IKeyDerivationParams } from '../model';
+import { EncryptionAlgorithm, ICryptoProvider, IArgon2idParams, IKeyDerivationParams, IPbkdf2KeyDerivationParams, KeyPairAlgorithm } from '../model';
+import { IPrivateKeyStorage } from './privateKeyStorage';
+export { allKeyPairAlgorithms, KeyPairAlgorithm } from '../model';
 /**
  * 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
  */
-export type KeyStoreFormat = 'keystore-v1';
+export type KeyStoreFormat = 'keystore-v1' | 'keystore-v2';
 /**
- * Current format version constant.
+ * All recognized key store format versions (readable by the current library).
+ * @public
+ */
+export declare const allKeyStoreFormats: ReadonlyArray<KeyStoreFormat>;
+/**
+ * Current format version constant. New vaults are written as `'keystore-v2'`.
  * @public
  */
 export declare const KEYSTORE_FORMAT: KeyStoreFormat;
@@ -21,31 +34,55 @@ export declare const DEFAULT_KEYSTORE_ITERATIONS: number;
  */
 export declare const MIN_SALT_LENGTH: number;
 /**
- * Discriminator for secret types stored in the vault.
+ * Discriminator for symmetric secret types stored in the vault.
  * - `'encryption-key'`: A 32-byte AES-256 encryption key.
  * - `'api-key'`: An arbitrary-length API key string (UTF-8 encoded).
  * @public
  */
-export type KeyStoreSecretType = 'encryption-key' | 'api-key';
+export type KeyStoreSymmetricSecretType = 'encryption-key' | 'api-key';
+/**
+ * All valid symmetric secret types.
+ * @public
+ */
+export declare const allKeyStoreSymmetricSecretTypes: ReadonlyArray<KeyStoreSymmetricSecretType>;
+/**
+ * Discriminator for asymmetric secret types stored in the vault.
+ * - `'asymmetric-keypair'`: A public/private key pair. The public key is held in
+ *   the vault as a JWK; the private key lives in the supplied
+ *   {@link CryptoUtils.KeyStore.IPrivateKeyStorage} provider.
+ * @public
+ */
+export type KeyStoreAsymmetricSecretType = 'asymmetric-keypair';
+/**
+ * All valid asymmetric secret types.
+ * @public
+ */
+export declare const allKeyStoreAsymmetricSecretTypes: ReadonlyArray<KeyStoreAsymmetricSecretType>;
+/**
+ * Discriminator for any secret type stored in the vault.
+ * @public
+ */
+export type KeyStoreSecretType = KeyStoreSymmetricSecretType | KeyStoreAsymmetricSecretType;
 /**
  * All valid key store secret types.
  * @public
  */
 export declare const allKeyStoreSecretTypes: ReadonlyArray<KeyStoreSecretType>;
 /**
- * A secret entry stored in the vault (in-memory representation).
+ * A symmetric secret entry stored in the vault (in-memory representation).
+ * Holds the raw key material directly — for `'encryption-key'` it is a 32-byte
+ * AES-256 key; for `'api-key'` it is the UTF-8 encoded API key string.
  * @public
  */
-export interface IKeyStoreSecretEntry {
+export interface IKeyStoreSymmetricEntry {
     /**
      * Unique name for this secret (used as lookup key).
      */
     readonly name: string;
     /**
-     * Secret type discriminator.
-     * Defaults to `'encryption-key'` for backwards compatibility.
+     * Symmetric secret type discriminator.
      */
-    readonly type: KeyStoreSecretType;
+    readonly type: KeyStoreSymmetricSecretType;
     /**
      * The secret data.
      * - For `'encryption-key'`: 32-byte AES-256 key.
@@ -62,19 +99,98 @@ export interface IKeyStoreSecretEntry {
     readonly createdAt: string;
 }
 /**
- * JSON-serializable version of secret entry (for storage).
+ * An asymmetric keypair entry stored in the vault (in-memory representation).
+ * Holds only the public key (as a JWK) and a stable handle (`id`) the
+ * {@link CryptoUtils.KeyStore.IPrivateKeyStorage} provider uses to fetch the private key.
  * @public
  */
-export interface IKeyStoreSecretEntryJson {
+export interface IKeyStoreAsymmetricEntry {
+    /**
+     * Unique name for this entry (used as vault lookup key, renameable).
+     */
+    readonly name: string;
+    /**
+     * Asymmetric secret type discriminator.
+     */
+    readonly type: KeyStoreAsymmetricSecretType;
+    /**
+     * Immutable handle used by {@link CryptoUtils.KeyStore.IPrivateKeyStorage} to address the
+     * private key. Independent of `name`; survives renames.
+     */
+    readonly id: string;
+    /**
+     * Algorithm used to generate this keypair.
+     */
+    readonly algorithm: KeyPairAlgorithm;
+    /**
+     * 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.
+     */
+    readonly description?: string;
+    /**
+     * When this entry was added (ISO 8601).
+     */
+    readonly createdAt: string;
+}
+/**
+ * Any vault entry, discriminated by `type`.
+ * @public
+ */
+export type IKeyStoreEntry = IKeyStoreSymmetricEntry | IKeyStoreAsymmetricEntry;
+/**
+ * Backwards-compatible alias for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntry}.
+ * @deprecated Use {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntry} for symmetric
+ * entries or {@link CryptoUtils.KeyStore.IKeyStoreEntry} for the discriminated union.
+ * @public
+ */
+export type IKeyStoreSecretEntry = IKeyStoreSymmetricEntry;
+/**
+ * JSON-serializable representation of a symmetric secret entry.
+ *
+ * @remarks
+ * Describes the *normalized* shape after parsing. `type` is required here
+ * because the converter (see
+ * {@link CryptoUtils.KeyStore.Converters.keystoreSymmetricEntryJson | keystoreSymmetricEntryJson})
+ * injects the default `'encryption-key'` when reading vaults written before
+ * asymmetric-keypair support added the discriminator. Raw on-wire bytes from
+ * a legacy vault may therefore omit `type`; downstream code only ever sees
+ * the post-conversion shape declared here.
+ *
+ * @public
+ */
+export interface IKeyStoreSymmetricEntryJson {
     /**
      * Unique name for this secret.
      */
     readonly name: string;
     /**
-     * Secret type discriminator.
-     * Optional for backwards compatibility — missing means `'encryption-key'`.
+     * Symmetric secret type discriminator.
+     *
+     * Required on this normalized model type. Vaults written prior to the
+     * asymmetric-keypair support may omit this field on the wire; the
+     * converter injects `'encryption-key'` when missing for backwards
+     * compatibility, so by the time a value of this type is observed the
+     * discriminator is always present.
      */
-    readonly type?: KeyStoreSecretType;
+    readonly type: KeyStoreSymmetricSecretType;
     /**
      * Base64-encoded secret data.
      */
@@ -89,7 +205,63 @@ export interface IKeyStoreSecretEntryJson {
     readonly createdAt: string;
 }
 /**
- * The decrypted vault contents - a versioned map of secrets.
+ * JSON-serializable representation of an asymmetric keypair entry.
+ * The private key is not present here — it lives in the
+ * {@link CryptoUtils.KeyStore.IPrivateKeyStorage} provider, addressed by `id`.
+ * @public
+ */
+export interface IKeyStoreAsymmetricEntryJson {
+    /**
+     * Unique name for this entry.
+     */
+    readonly name: string;
+    /**
+     * Asymmetric secret type discriminator.
+     */
+    readonly type: KeyStoreAsymmetricSecretType;
+    /**
+     * Immutable handle used by {@link CryptoUtils.KeyStore.IPrivateKeyStorage} to address the
+     * private key.
+     */
+    readonly id: string;
+    /**
+     * Algorithm used to generate this keypair.
+     */
+    readonly algorithm: KeyPairAlgorithm;
+    /**
+     * 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.
+     */
+    readonly description?: string;
+    /**
+     * When this entry was added (ISO 8601).
+     */
+    readonly createdAt: string;
+}
+/**
+ * Any JSON vault entry, discriminated by `type`.
+ * @public
+ */
+export type IKeyStoreEntryJson = IKeyStoreSymmetricEntryJson | IKeyStoreAsymmetricEntryJson;
+/**
+ * Backwards-compatible alias for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson}.
+ * @deprecated Use {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson} for
+ * symmetric entries or {@link CryptoUtils.KeyStore.IKeyStoreEntryJson} for the
+ * discriminated union.
+ * @public
+ */
+export type IKeyStoreSecretEntryJson = IKeyStoreSymmetricEntryJson;
+/**
+ * The decrypted vault contents - a versioned map of entries.
  * @public
  */
 export interface IKeyStoreVaultContents {
@@ -98,9 +270,9 @@ export interface IKeyStoreVaultContents {
      */
     readonly version: KeyStoreFormat;
     /**
-     * Map of secret name to secret entry.
+     * Map of entry name to entry (symmetric or asymmetric).
      */
-    readonly secrets: Record<string, IKeyStoreSecretEntryJson>;
+    readonly secrets: Record<string, IKeyStoreEntryJson>;
 }
 /**
  * The encrypted key store file format.
@@ -128,9 +300,9 @@ export 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;
 }
 /**
  * Key store lock state.
@@ -150,6 +322,12 @@ export interface IKeyStoreCreateParams {
      * PBKDF2 iterations (defaults to DEFAULT_KEYSTORE_ITERATIONS).
      */
     readonly iterations?: number;
+    /**
+     * Optional private-key storage backend. Required to use `addKeyPair` /
+     * `getKeyPair`; absent backends still permit opening, listing, and reading
+     * public-key metadata for asymmetric entries.
+     */
+    readonly privateKeyStorage?: IPrivateKeyStorage;
 }
 /**
  * Parameters for opening an existing key store.
@@ -164,6 +342,12 @@ export interface IKeyStoreOpenParams {
      * The encrypted key store file content.
      */
     readonly keystoreFile: IKeyStoreFile;
+    /**
+     * Optional private-key storage backend. Required to use `addKeyPair` /
+     * `getKeyPair`; absent backends still permit opening, listing, and reading
+     * public-key metadata for asymmetric entries.
+     */
+    readonly privateKeyStorage?: IPrivateKeyStorage;
 }
 /**
  * Result of adding a secret to the key store.
@@ -173,11 +357,19 @@ export interface IAddSecretResult {
     /**
      * The secret entry that was added.
      */
-    readonly entry: IKeyStoreSecretEntry;
+    readonly entry: IKeyStoreSymmetricEntry;
     /**
      * Whether this replaced an existing secret.
      */
     readonly replaced: boolean;
+    /**
+     * Best-effort warning from displaced-resource cleanup. Set when this call
+     * replaced an asymmetric-keypair entry but the corresponding
+     * {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete failed; the new
+     * entry is still committed and the orphaned blob is left for consumer-side
+     * GC to reconcile.
+     */
+    readonly warning?: string;
 }
 /**
  * Options for adding a secret.
@@ -199,6 +391,18 @@ export interface IImportSecretOptions extends IAddSecretOptions {
      */
     readonly replace?: boolean;
 }
+/**
+ * Options for importing raw key material via {@link KeyStore.importSecret}.
+ * Extends {@link IImportSecretOptions} with a type classification.
+ * @public
+ */
+export interface IImportKeyOptions extends IImportSecretOptions {
+    /**
+     * Symmetric secret type classification for the imported key material.
+     * @defaultValue 'encryption-key'
+     */
+    readonly type?: KeyStoreSymmetricSecretType;
+}
 /**
  * Options for adding a secret derived from a password.
  * @public
@@ -234,6 +438,131 @@ export interface IAddSecretFromPasswordResult extends IAddSecretResult {
      */
     readonly keyDerivation: IKeyDerivationParams;
 }
+/**
+ * Options for adding an Argon2id password-derived secret.
+ * @public
+ */
+export 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 an asymmetric keypair to the key store.
+ * @public
+ */
+export interface IAddKeyPairOptions {
+    /**
+     * Algorithm to use for the new keypair.
+     */
+    readonly algorithm: KeyPairAlgorithm;
+    /**
+     * Optional description for the entry.
+     */
+    readonly description?: string;
+    /**
+     * Whether to replace an existing entry with the same name.
+     * Replacement mints a fresh storage `id` and best-effort deletes the
+     * displaced storage blob; see the keystore design doc for details.
+     */
+    readonly replace?: boolean;
+    /**
+     * Overrides the storage-backend-derived extractability for this key only.
+     * Omit to keep the default (`!privateKeyStorage.supportsNonExtractable`).
+     * A value the backend cannot honor fails loudly rather than silently
+     * 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;
+}
+/**
+ * Options for retrieving an asymmetric keypair via {@link CryptoUtils.KeyStore.KeyStore.getKeyPair}.
+ * @public
+ */
+export 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;
+}
+/**
+ * Result of adding an asymmetric keypair to the key store.
+ * @public
+ */
+export interface IAddKeyPairResult {
+    /**
+     * The asymmetric entry that was added.
+     */
+    readonly entry: IKeyStoreAsymmetricEntry;
+    /**
+     * Whether this replaced an existing entry.
+     */
+    readonly replaced: boolean;
+    /**
+     * Best-effort warning from displaced-resource cleanup. Set when this call
+     * replaced a prior entry but the corresponding
+     * {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete failed; the new
+     * keypair is still committed and the orphaned blob is left for consumer-side
+     * GC to reconcile.
+     */
+    readonly warning?: string;
+}
+/**
+ * Result of removing a secret from the key store.
+ * @public
+ */
+export interface IRemoveSecretResult {
+    /**
+     * The secret entry that was removed from the vault.
+     */
+    readonly entry: IKeyStoreEntry;
+    /**
+     * Best-effort warning from {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete
+     * for asymmetric entries when the storage call failed. The vault entry is
+     * still considered removed and the orphaned blob is left for consumer-side
+     * GC to reconcile.
+     */
+    readonly warning?: string;
+}
 /**
  * Checks if a JSON object appears to be a key store file.
  * Uses the format field as a discriminator.

package/lib/packlets/crypto-utils/keystore/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../../src/packlets/crypto-utils/keystore/model.ts"],"names":[],"mappings":"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"}

package/lib/packlets/crypto-utils/keystore/model.js

@@ -19,13 +19,22 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SECRET_ITERATIONS = exports.allKeyStoreSecretTypes = exports.MIN_SALT_LENGTH = exports.DEFAULT_KEYSTORE_ITERATIONS = exports.KEYSTORE_FORMAT = void 0;
+exports.DEFAULT_SECRET_ITERATIONS = exports.allKeyStoreSecretTypes = exports.allKeyStoreAsymmetricSecretTypes = exports.allKeyStoreSymmetricSecretTypes = exports.MIN_SALT_LENGTH = exports.DEFAULT_KEYSTORE_ITERATIONS = exports.KEYSTORE_FORMAT = exports.allKeyStoreFormats = exports.allKeyPairAlgorithms = void 0;
 exports.isKeyStoreFile = isKeyStoreFile;
+// Re-export so consumers can continue to access the algorithm enum via the
+// CryptoUtils.KeyStore namespace alongside the rest of the keystore types.
+var model_1 = require("../model");
+Object.defineProperty(exports, "allKeyPairAlgorithms", { enumerable: true, get: function () { return model_1.allKeyPairAlgorithms; } });
 /**
- * Current format version constant.
+ * All recognized key store format versions (readable by the current library).
  * @public
  */
-exports.KEYSTORE_FORMAT = 'keystore-v1';
+exports.allKeyStoreFormats = ['keystore-v1', 'keystore-v2'];
+/**
+ * Current format version constant. New vaults are written as `'keystore-v2'`.
+ * @public
+ */
+exports.KEYSTORE_FORMAT = 'keystore-v2';
 /**
  * Default PBKDF2 iterations for key store encryption.
  * Higher than regular files since this protects the master key vault.
@@ -37,11 +46,29 @@ exports.DEFAULT_KEYSTORE_ITERATIONS = 600000;
  * @public
  */
 exports.MIN_SALT_LENGTH = 16;
+/**
+ * All valid symmetric secret types.
+ * @public
+ */
+exports.allKeyStoreSymmetricSecretTypes = [
+    'encryption-key',
+    'api-key'
+];
+/**
+ * All valid asymmetric secret types.
+ * @public
+ */
+exports.allKeyStoreAsymmetricSecretTypes = [
+    'asymmetric-keypair'
+];
 /**
  * All valid key store secret types.
  * @public
  */
-exports.allKeyStoreSecretTypes = ['encryption-key', 'api-key'];
+exports.allKeyStoreSecretTypes = [
+    ...exports.allKeyStoreAsymmetricSecretTypes,
+    ...exports.allKeyStoreSymmetricSecretTypes
+];
 /**
  * Default PBKDF2 iterations for secret-level key derivation.
  * Lower than keystore encryption since these are used more frequently.
@@ -63,6 +90,6 @@ function isKeyStoreFile(json) {
         return false;
     }
     const obj = json;
-    return obj.format === exports.KEYSTORE_FORMAT;
+    return typeof obj.format === 'string' && exports.allKeyStoreFormats.includes(obj.format);
 }
 //# sourceMappingURL=model.js.map

package/lib/packlets/crypto-utils/keystore/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../../src/packlets/crypto-utils/keystore/model.ts"],"names":[],"mappings":";AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;;;AAmrBZ,wCAMC;AA7qBD,2EAA2E;AAC3E,2EAA2E;AAC3E,kCAAkE;AAAzD,6GAAA,oBAAoB,OAAA;AAkB7B;;;GAGG;AACU,QAAA,kBAAkB,GAAkC,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;AAEhG;;;GAGG;AACU,QAAA,eAAe,GAAmB,aAAa,CAAC;AAE7D;;;;GAIG;AACU,QAAA,2BAA2B,GAAW,MAAM,CAAC;AAE1D;;;GAGG;AACU,QAAA,eAAe,GAAW,EAAE,CAAC;AAc1C;;;GAGG;AACU,QAAA,+BAA+B,GAA+C;IACzF,gBAAgB;IAChB,SAAS;CACV,CAAC;AAWF;;;GAGG;AACU,QAAA,gCAAgC,GAAgD;IAC3F,oBAAoB;CACrB,CAAC;AAQF;;;GAGG;AACU,QAAA,sBAAsB,GAAsC;IACvE,GAAG,wCAAgC;IACnC,GAAG,uCAA+B;CACnC,CAAC;AA6ZF;;;;GAIG;AACU,QAAA,yBAAyB,GAAW,MAAM,CAAC;AA0JxD,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,IAAa;IAC1C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,GAAG,GAAG,IAA+B,CAAC;IAC5C,OAAO,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAK,0BAA4C,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC9G,CAAC","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\nimport {\n  EncryptionAlgorithm,\n  ICryptoProvider,\n  IArgon2idParams,\n  IKeyDerivationParams,\n  IPbkdf2KeyDerivationParams,\n  KeyPairAlgorithm\n} from '../model';\nimport { IPrivateKeyStorage } from './privateKeyStorage';\n\n// Re-export so consumers can continue to access the algorithm enum via the\n// CryptoUtils.KeyStore namespace alongside the rest of the keystore types.\nexport { allKeyPairAlgorithms, KeyPairAlgorithm } from '../model';\n\n// ============================================================================\n// Key Store Format Types\n// ============================================================================\n\n/**\n * Format version for key store files.\n *\n * - `'keystore-v1'`: the original format (no private-key escrow).\n * - `'keystore-v2'`: adds the optional `escrowedPrivateKeyJwk` field on\n *   asymmetric-keypair entries. A strict superset of v1 — the field is\n *   optional, so a v2 reader opens a v1 vault with no special-casing, and a\n *   v1 vault opened and re-saved is silently upgraded to v2.\n * @public\n */\nexport type KeyStoreFormat = 'keystore-v1' | 'keystore-v2';\n\n/**\n * All recognized key store format versions (readable by the current library).\n * @public\n */\nexport const allKeyStoreFormats: ReadonlyArray<KeyStoreFormat> = ['keystore-v1', 'keystore-v2'];\n\n/**\n * Current format version constant. New vaults are written as `'keystore-v2'`.\n * @public\n */\nexport const KEYSTORE_FORMAT: KeyStoreFormat = 'keystore-v2';\n\n/**\n * Default PBKDF2 iterations for key store encryption.\n * Higher than regular files since this protects the master key vault.\n * @public\n */\nexport const DEFAULT_KEYSTORE_ITERATIONS: number = 600000;\n\n/**\n * Minimum salt length for key derivation.\n * @public\n */\nexport const MIN_SALT_LENGTH: number = 16;\n\n// ============================================================================\n// Key Store Vault Contents (Decrypted State)\n// ============================================================================\n\n/**\n * Discriminator for symmetric secret types stored in the vault.\n * - `'encryption-key'`: A 32-byte AES-256 encryption key.\n * - `'api-key'`: An arbitrary-length API key string (UTF-8 encoded).\n * @public\n */\nexport type KeyStoreSymmetricSecretType = 'encryption-key' | 'api-key';\n\n/**\n * All valid symmetric secret types.\n * @public\n */\nexport const allKeyStoreSymmetricSecretTypes: ReadonlyArray<KeyStoreSymmetricSecretType> = [\n  'encryption-key',\n  'api-key'\n];\n\n/**\n * Discriminator for asymmetric secret types stored in the vault.\n * - `'asymmetric-keypair'`: A public/private key pair. The public key is held in\n *   the vault as a JWK; the private key lives in the supplied\n *   {@link CryptoUtils.KeyStore.IPrivateKeyStorage} provider.\n * @public\n */\nexport type KeyStoreAsymmetricSecretType = 'asymmetric-keypair';\n\n/**\n * All valid asymmetric secret types.\n * @public\n */\nexport const allKeyStoreAsymmetricSecretTypes: ReadonlyArray<KeyStoreAsymmetricSecretType> = [\n  'asymmetric-keypair'\n];\n\n/**\n * Discriminator for any secret type stored in the vault.\n * @public\n */\nexport type KeyStoreSecretType = KeyStoreSymmetricSecretType | KeyStoreAsymmetricSecretType;\n\n/**\n * All valid key store secret types.\n * @public\n */\nexport const allKeyStoreSecretTypes: ReadonlyArray<KeyStoreSecretType> = [\n  ...allKeyStoreAsymmetricSecretTypes,\n  ...allKeyStoreSymmetricSecretTypes\n];\n\n/**\n * A symmetric secret entry stored in the vault (in-memory representation).\n * Holds the raw key material directly — for `'encryption-key'` it is a 32-byte\n * AES-256 key; for `'api-key'` it is the UTF-8 encoded API key string.\n * @public\n */\nexport interface IKeyStoreSymmetricEntry {\n  /**\n   * Unique name for this secret (used as lookup key).\n   */\n  readonly name: string;\n\n  /**\n   * Symmetric secret type discriminator.\n   */\n  readonly type: KeyStoreSymmetricSecretType;\n\n  /**\n   * The secret data.\n   * - For `'encryption-key'`: 32-byte AES-256 key.\n   * - For `'api-key'`: UTF-8 encoded API key string (arbitrary length).\n   */\n  readonly key: Uint8Array;\n\n  /**\n   * Optional description for this secret.\n   */\n  readonly description?: string;\n\n  /**\n   * When this secret was added (ISO 8601).\n   */\n  readonly createdAt: string;\n}\n\n/**\n * An asymmetric keypair entry stored in the vault (in-memory representation).\n * Holds only the public key (as a JWK) and a stable handle (`id`) the\n * {@link CryptoUtils.KeyStore.IPrivateKeyStorage} provider uses to fetch the private key.\n * @public\n */\nexport interface IKeyStoreAsymmetricEntry {\n  /**\n   * Unique name for this entry (used as vault lookup key, renameable).\n   */\n  readonly name: string;\n\n  /**\n   * Asymmetric secret type discriminator.\n   */\n  readonly type: KeyStoreAsymmetricSecretType;\n\n  /**\n   * Immutable handle used by {@link CryptoUtils.KeyStore.IPrivateKeyStorage} to address the\n   * private key. Independent of `name`; survives renames.\n   */\n  readonly id: string;\n\n  /**\n   * Algorithm used to generate this keypair.\n   */\n  readonly algorithm: KeyPairAlgorithm;\n\n  /**\n   * The public key as a JSON Web Key.\n   */\n  readonly publicKeyJwk: JsonWebKey;\n\n  /**\n   * Optional escrowed copy of the private key, as a JSON Web Key. Present only\n   * when the entry was created with `addKeyPair(name, { escrow: true })`.\n   *\n   * This is an opt-in cross-device recovery affordance: the private key is\n   * carried inside the vault's AES-GCM ciphertext (same custody class as\n   * `publicKeyJwk`), so a recovered vault plus the master password can\n   * reconstitute the signing/decryption identity on a fresh device via\n   * `getKeyPair(name, { rehydrate: true })`.\n   *\n   * SECURITY: when present, the master password becomes the sole gate\n   * protecting this private key. Use a strong KDF for escrow-bearing stores.\n   * See the {@link CryptoUtils.KeyStore.KeyStore} class docs.\n   */\n  readonly escrowedPrivateKeyJwk?: JsonWebKey;\n\n  /**\n   * Optional description for this entry.\n   */\n  readonly description?: string;\n\n  /**\n   * When this entry was added (ISO 8601).\n   */\n  readonly createdAt: string;\n}\n\n/**\n * Any vault entry, discriminated by `type`.\n * @public\n */\nexport type IKeyStoreEntry = IKeyStoreSymmetricEntry | IKeyStoreAsymmetricEntry;\n\n/**\n * Backwards-compatible alias for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntry}.\n * @deprecated Use {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntry} for symmetric\n * entries or {@link CryptoUtils.KeyStore.IKeyStoreEntry} for the discriminated union.\n * @public\n */\nexport type IKeyStoreSecretEntry = IKeyStoreSymmetricEntry;\n\n/**\n * JSON-serializable representation of a symmetric secret entry.\n *\n * @remarks\n * Describes the *normalized* shape after parsing. `type` is required here\n * because the converter (see\n * {@link CryptoUtils.KeyStore.Converters.keystoreSymmetricEntryJson | keystoreSymmetricEntryJson})\n * injects the default `'encryption-key'` when reading vaults written before\n * asymmetric-keypair support added the discriminator. Raw on-wire bytes from\n * a legacy vault may therefore omit `type`; downstream code only ever sees\n * the post-conversion shape declared here.\n *\n * @public\n */\nexport interface IKeyStoreSymmetricEntryJson {\n  /**\n   * Unique name for this secret.\n   */\n  readonly name: string;\n\n  /**\n   * Symmetric secret type discriminator.\n   *\n   * Required on this normalized model type. Vaults written prior to the\n   * asymmetric-keypair support may omit this field on the wire; the\n   * converter injects `'encryption-key'` when missing for backwards\n   * compatibility, so by the time a value of this type is observed the\n   * discriminator is always present.\n   */\n  readonly type: KeyStoreSymmetricSecretType;\n\n  /**\n   * Base64-encoded secret data.\n   */\n  readonly key: string;\n\n  /**\n   * Optional description.\n   */\n  readonly description?: string;\n\n  /**\n   * When this secret was added (ISO 8601).\n   */\n  readonly createdAt: string;\n}\n\n/**\n * JSON-serializable representation of an asymmetric keypair entry.\n * The private key is not present here — it lives in the\n * {@link CryptoUtils.KeyStore.IPrivateKeyStorage} provider, addressed by `id`.\n * @public\n */\nexport interface IKeyStoreAsymmetricEntryJson {\n  /**\n   * Unique name for this entry.\n   */\n  readonly name: string;\n\n  /**\n   * Asymmetric secret type discriminator.\n   */\n  readonly type: KeyStoreAsymmetricSecretType;\n\n  /**\n   * Immutable handle used by {@link CryptoUtils.KeyStore.IPrivateKeyStorage} to address the\n   * private key.\n   */\n  readonly id: string;\n\n  /**\n   * Algorithm used to generate this keypair.\n   */\n  readonly algorithm: KeyPairAlgorithm;\n\n  /**\n   * The public key as a JSON Web Key.\n   */\n  readonly publicKeyJwk: JsonWebKey;\n\n  /**\n   * Optional escrowed copy of the private key, as a JSON Web Key. Present only\n   * on `'keystore-v2'` vaults whose entry was created with escrow enabled. A\n   * v1 vault omits the field; a v2 reader treats its absence as \"no escrow\".\n   */\n  readonly escrowedPrivateKeyJwk?: JsonWebKey;\n\n  /**\n   * Optional description.\n   */\n  readonly description?: string;\n\n  /**\n   * When this entry was added (ISO 8601).\n   */\n  readonly createdAt: string;\n}\n\n/**\n * Any JSON vault entry, discriminated by `type`.\n * @public\n */\nexport type IKeyStoreEntryJson = IKeyStoreSymmetricEntryJson | IKeyStoreAsymmetricEntryJson;\n\n/**\n * Backwards-compatible alias for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson}.\n * @deprecated Use {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson} for\n * symmetric entries or {@link CryptoUtils.KeyStore.IKeyStoreEntryJson} for the\n * discriminated union.\n * @public\n */\nexport type IKeyStoreSecretEntryJson = IKeyStoreSymmetricEntryJson;\n\n/**\n * The decrypted vault contents - a versioned map of entries.\n * @public\n */\nexport interface IKeyStoreVaultContents {\n  /**\n   * Format version for vault contents.\n   */\n  readonly version: KeyStoreFormat;\n\n  /**\n   * Map of entry name to entry (symmetric or asymmetric).\n   */\n  readonly secrets: Record<string, IKeyStoreEntryJson>;\n}\n\n// ============================================================================\n// Key Store File Format (Encrypted State)\n// ============================================================================\n\n/**\n * The encrypted key store file format.\n * @public\n */\nexport interface IKeyStoreFile {\n  /**\n   * Format identifier.\n   */\n  readonly format: KeyStoreFormat;\n\n  /**\n   * Algorithm used for encryption.\n   */\n  readonly algorithm: EncryptionAlgorithm;\n\n  /**\n   * Base64-encoded initialization vector.\n   */\n  readonly iv: string;\n\n  /**\n   * Base64-encoded authentication tag.\n   */\n  readonly authTag: string;\n\n  /**\n   * Base64-encoded encrypted vault contents.\n   */\n  readonly encryptedData: string;\n\n  /**\n   * Key derivation parameters for the vault master key (always PBKDF2).\n   */\n  readonly keyDerivation: IPbkdf2KeyDerivationParams;\n}\n\n// ============================================================================\n// Key Store State and Configuration\n// ============================================================================\n\n/**\n * Key store lock state.\n * @public\n */\nexport type KeyStoreLockState = 'locked' | 'unlocked';\n\n/**\n * Parameters for creating a new key store.\n * @public\n */\nexport interface IKeyStoreCreateParams {\n  /**\n   * Crypto provider to use.\n   */\n  readonly cryptoProvider: ICryptoProvider;\n\n  /**\n   * PBKDF2 iterations (defaults to DEFAULT_KEYSTORE_ITERATIONS).\n   */\n  readonly iterations?: number;\n\n  /**\n   * Optional private-key storage backend. Required to use `addKeyPair` /\n   * `getKeyPair`; absent backends still permit opening, listing, and reading\n   * public-key metadata for asymmetric entries.\n   */\n  readonly privateKeyStorage?: IPrivateKeyStorage;\n}\n\n/**\n * Parameters for opening an existing key store.\n * @public\n */\nexport interface IKeyStoreOpenParams {\n  /**\n   * Crypto provider to use.\n   */\n  readonly cryptoProvider: ICryptoProvider;\n\n  /**\n   * The encrypted key store file content.\n   */\n  readonly keystoreFile: IKeyStoreFile;\n\n  /**\n   * Optional private-key storage backend. Required to use `addKeyPair` /\n   * `getKeyPair`; absent backends still permit opening, listing, and reading\n   * public-key metadata for asymmetric entries.\n   */\n  readonly privateKeyStorage?: IPrivateKeyStorage;\n}\n\n/**\n * Result of adding a secret to the key store.\n * @public\n */\nexport interface IAddSecretResult {\n  /**\n   * The secret entry that was added.\n   */\n  readonly entry: IKeyStoreSymmetricEntry;\n\n  /**\n   * Whether this replaced an existing secret.\n   */\n  readonly replaced: boolean;\n\n  /**\n   * Best-effort warning from displaced-resource cleanup. Set when this call\n   * replaced an asymmetric-keypair entry but the corresponding\n   * {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete failed; the new\n   * entry is still committed and the orphaned blob is left for consumer-side\n   * GC to reconcile.\n   */\n  readonly warning?: string;\n}\n\n/**\n * Options for adding a secret.\n * @public\n */\nexport interface IAddSecretOptions {\n  /**\n   * Optional description for the secret.\n   */\n  readonly description?: string;\n}\n\n/**\n * Options for importing a secret.\n * @public\n */\nexport interface IImportSecretOptions extends IAddSecretOptions {\n  /**\n   * Whether to replace an existing secret with the same name.\n   */\n  readonly replace?: boolean;\n}\n\n/**\n * Options for importing raw key material via {@link KeyStore.importSecret}.\n * Extends {@link IImportSecretOptions} with a type classification.\n * @public\n */\nexport interface IImportKeyOptions extends IImportSecretOptions {\n  /**\n   * Symmetric secret type classification for the imported key material.\n   * @defaultValue 'encryption-key'\n   */\n  readonly type?: KeyStoreSymmetricSecretType;\n}\n\n/**\n * Options for adding a secret derived from a password.\n * @public\n */\nexport interface IAddSecretFromPasswordOptions extends IAddSecretOptions {\n  /**\n   * Whether to replace an existing secret with the same name.\n   */\n  readonly replace?: boolean;\n\n  /**\n   * PBKDF2 iterations for key derivation.\n   * @defaultValue DEFAULT_SECRET_ITERATIONS (350000)\n   */\n  readonly iterations?: number;\n}\n\n/**\n * Default PBKDF2 iterations for secret-level key derivation.\n * Lower than keystore encryption since these are used more frequently.\n * @public\n */\nexport const DEFAULT_SECRET_ITERATIONS: number = 350000;\n\n/**\n * Result of adding a password-derived secret.\n * Extends {@link IAddSecretResult} with key derivation parameters\n * needed to store alongside encrypted files.\n * @public\n */\nexport interface IAddSecretFromPasswordResult extends IAddSecretResult {\n  /**\n   * Key derivation parameters used to derive the secret key.\n   * Store these in encrypted file metadata so the password alone\n   * can re-derive the same key for decryption.\n   */\n  readonly keyDerivation: IKeyDerivationParams;\n}\n\n/**\n * Options for adding an Argon2id password-derived secret.\n * @public\n */\nexport interface IAddSecretFromPasswordArgon2idOptions {\n  /**\n   * Argon2id parameters. Defaults to {@link CryptoUtils.ARGON2ID_OWASP_MIN}.\n   */\n  readonly params?: IArgon2idParams;\n  /**\n   * Optional description for the secret.\n   */\n  readonly description?: string;\n  /**\n   * Whether to replace an existing secret with the same name.\n   */\n  readonly replace?: boolean;\n}\n\n/**\n * Options for adding an asymmetric keypair to the key store.\n * @public\n */\nexport interface IAddKeyPairOptions {\n  /**\n   * Algorithm to use for the new keypair.\n   */\n  readonly algorithm: KeyPairAlgorithm;\n\n  /**\n   * Optional description for the entry.\n   */\n  readonly description?: string;\n\n  /**\n   * Whether to replace an existing entry with the same name.\n   * Replacement mints a fresh storage `id` and best-effort deletes the\n   * displaced storage blob; see the keystore design doc for details.\n   */\n  readonly replace?: boolean;\n\n  /**\n   * Overrides the storage-backend-derived extractability for this key only.\n   * Omit to keep the default (`!privateKeyStorage.supportsNonExtractable`).\n   * A value the backend cannot honor fails loudly rather than silently\n   * downgrading.\n   */\n  readonly extractable?: boolean;\n\n  /**\n   * Opt in to private-key escrow. When `true`, an encrypted copy of the\n   * private key (as a JWK) is carried inside the vault entry\n   * (`escrowedPrivateKeyJwk`), enabling cross-device recovery from the vault\n   * file plus the master password alone via\n   * `getKeyPair(name, { rehydrate: true })`.\n   *\n   * Orthogonal to `extractable`: the escrow copy is always captured (the\n   * transient keypair is generated extractable so it can be exported to JWK),\n   * while the LIVE stored key's extractability still follows the normal rule\n   * (`extractable` override, else the backend default). So escrow does not\n   * change how extractable the day-to-day key is — only whether a recovery\n   * copy is retained in the vault.\n   *\n   * @defaultValue false — no escrow copy is written (today's behavior).\n   *\n   * SECURITY: escrow makes the master password the sole gate protecting a\n   * private key that would otherwise be unrecoverable from the vault. Use a\n   * strong KDF (Argon2id-derived or high-iteration PBKDF2) for escrow-bearing\n   * stores. See the {@link CryptoUtils.KeyStore.KeyStore} class docs.\n   */\n  readonly escrow?: boolean;\n}\n\n/**\n * Options for retrieving an asymmetric keypair via {@link CryptoUtils.KeyStore.KeyStore.getKeyPair}.\n * @public\n */\nexport interface IGetKeyPairOptions {\n  /**\n   * Opt in to escrow rehydration. When `true` AND no private-key blob exists\n   * under the entry's storage `id` AND the entry carries an\n   * `escrowedPrivateKeyJwk`, the escrowed JWK is imported (non-extractable\n   * where the backend supports it) and stored under the entry's `id` before\n   * being returned — filling a gap on a fresh device from the recovered vault.\n   *\n   * Fill-a-gap only: an existing storage blob is never overwritten. When a\n   * blob is present it is loaded as usual and the escrow copy is ignored.\n   *\n   * @defaultValue false — today's behavior: load from storage or fail.\n   */\n  readonly rehydrate?: boolean;\n}\n\n/**\n * Result of adding an asymmetric keypair to the key store.\n * @public\n */\nexport interface IAddKeyPairResult {\n  /**\n   * The asymmetric entry that was added.\n   */\n  readonly entry: IKeyStoreAsymmetricEntry;\n\n  /**\n   * Whether this replaced an existing entry.\n   */\n  readonly replaced: boolean;\n\n  /**\n   * Best-effort warning from displaced-resource cleanup. Set when this call\n   * replaced a prior entry but the corresponding\n   * {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete failed; the new\n   * keypair is still committed and the orphaned blob is left for consumer-side\n   * GC to reconcile.\n   */\n  readonly warning?: string;\n}\n\n/**\n * Result of removing a secret from the key store.\n * @public\n */\nexport interface IRemoveSecretResult {\n  /**\n   * The secret entry that was removed from the vault.\n   */\n  readonly entry: IKeyStoreEntry;\n\n  /**\n   * Best-effort warning from {@link CryptoUtils.KeyStore.IPrivateKeyStorage}.delete\n   * for asymmetric entries when the storage call failed. The vault entry is\n   * still considered removed and the orphaned blob is left for consumer-side\n   * GC to reconcile.\n   */\n  readonly warning?: string;\n}\n\n// ============================================================================\n// Detection Helper\n// ============================================================================\n\n/**\n * Checks if a JSON object appears to be a key store file.\n * Uses the format field as a discriminator.\n * @param json - JSON object to check\n * @returns true if the object has the key store format field\n * @public\n */\nexport function isKeyStoreFile(json: unknown): boolean {\n  if (typeof json !== 'object' || json === null) {\n    return false;\n  }\n  const obj = json as Record<string, unknown>;\n  return typeof obj.format === 'string' && (allKeyStoreFormats as ReadonlyArray<string>).includes(obj.format);\n}\n"]}

package/lib/packlets/crypto-utils/keystore/privateKeyStorage.d.ts

@@ -0,0 +1,53 @@
+import { Result } from '@fgv/ts-utils';
+/**
+ * Pluggable backend that persists raw asymmetric private keys outside of the
+ * encrypted keystore vault. Concrete implementations:
+ * - {@link CryptoUtils.KeyStore.EncryptedFilePrivateKeyStorage} in
+ *   `@fgv/ts-extras` — directory-on-disk, AES-256-GCM-encrypted JWK per key
+ *   (Node; `supportsNonExtractable: false`).
+ * - `IdbPrivateKeyStorage` in `@fgv/ts-web-extras` — IndexedDB-backed, stores
+ *   `CryptoKey` objects directly (browser; `supportsNonExtractable: true`).
+ *
+ * The keystore writes storage-first: a private key is always stored here
+ * before the corresponding public-key vault entry is committed. Conversely,
+ * deletes hit the vault first and then this storage best-effort. As a result,
+ * crashes or skipped saves can leave orphaned blobs here; callers are expected
+ * to reconcile via {@link CryptoUtils.KeyStore.IPrivateKeyStorage.list} cross-referenced
+ * against the keystore's asymmetric entries.
+ *
+ * @public
+ */
+export interface IPrivateKeyStorage {
+    /**
+     * Whether keys generated for this backend may be marked
+     * `extractable: false`. `true` on backends that store `CryptoKey`
+     * objects directly (e.g. IndexedDB). `false` on backends that must
+     * round-trip via JWK (e.g. encrypted-file backends).
+     */
+    readonly supportsNonExtractable: boolean;
+    /**
+     * Stores `key` under `id`. Returns the stored `id` on success so the
+     * call can compose into a Result chain.
+     * @param id - Storage handle to write under.
+     * @param key - The private `CryptoKey` to persist.
+     */
+    store(id: string, key: CryptoKey): Promise<Result<string>>;
+    /**
+     * Loads the private key previously stored under `id`.
+     * @param id - Storage handle to look up.
+     */
+    load(id: string): Promise<Result<CryptoKey>>;
+    /**
+     * Deletes the entry stored under `id`. Returns the deleted `id` on
+     * success so the call can compose into a Result chain.
+     * @param id - Storage handle to remove.
+     */
+    delete(id: string): Promise<Result<string>>;
+    /**
+     * Lists every `id` currently held by the backend. Used by consumers to
+     * garbage-collect orphans left by crashes or aborted sessions; the
+     * keystore itself does not invoke this automatically.
+     */
+    list(): Promise<Result<readonly string[]>>;
+}
+//# sourceMappingURL=privateKeyStorage.d.ts.map

package/lib/packlets/crypto-utils/keystore/privateKeyStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"privateKeyStorage.d.ts","sourceRoot":"","sources":["../../../../src/packlets/crypto-utils/keystore/privateKeyStorage.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;IAEzC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAE3D;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IAE7C;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAE5C;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;CAC5C"}