@fgv/ts-extras 5.1.0-32 → 5.1.0-33

package/dist/ts-extras.d.ts

@@ -751,6 +751,115 @@ declare type EncryptedFileFormat = typeof Constants.ENCRYPTED_FILE_FORMAT;
  */
 declare const encryptedFileFormat: Converter<EncryptedFileFormat>;
 
+/**
+ * {@link CryptoUtils.KeyStore.IPrivateKeyStorage | IPrivateKeyStorage}
+ * implementation that persists each private key as its own AES-256-GCM-encrypted
+ * file in a directory. The file content is the key's JWK, encrypted with a
+ * consumer-supplied 32-byte key via the supplied
+ * {@link CryptoUtils.ICryptoProvider | crypto provider}.
+ *
+ * `supportsNonExtractable` is `false`: persisting to disk requires exporting the
+ * private key to JWK, which only works for `extractable: true` keys. The
+ * keystore generates extractable keys when a backend reports `false` here.
+ *
+ * I/O goes through the {@link FileTree.FileTree | FileTree} abstraction (default
+ * `FsTree`), so the same implementation works against an in-memory tree (tests)
+ * or any other Node-compatible backend.
+ *
+ * This backend is **Node-only**: it round-trips private keys through
+ * `node:crypto` (`crypto.webcrypto.subtle`), so it is intentionally excluded
+ * from the browser entry point. Browser consumers should use
+ * `IdbPrivateKeyStorage` from `@fgv/ts-web-extras` instead.
+ *
+ * Single-process assumption: there is no inter-process locking. Concurrent
+ * writers to the same directory may race.
+ *
+ * @public
+ */
+declare class EncryptedFilePrivateKeyStorage implements IPrivateKeyStorage {
+    /**
+     * `false` — disk persistence round-trips via JWK, which requires extractable
+     * keys.
+     */
+    readonly supportsNonExtractable: false;
+    private readonly _directory;
+    private readonly _encryptionKey;
+    private readonly _cryptoProvider;
+    private constructor();
+    /**
+     * Creates a new {@link CryptoUtils.KeyStore.EncryptedFilePrivateKeyStorage}.
+     * @param params - {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams}.
+     * @returns `Success` with the new instance, or `Failure` if the encryption
+     * key is the wrong size or the storage directory cannot be opened.
+     */
+    static create(params: IEncryptedFilePrivateKeyStorageCreateParams): Result<EncryptedFilePrivateKeyStorage>;
+    /**
+     * Stores `key` under `id` as an encrypted JWK file.
+     * @param id - Storage handle. Must be a safe filename token
+     * (`[A-Za-z0-9._-]+`, not `.`/`..`).
+     * @param key - The extractable private `CryptoKey` to persist.
+     */
+    store(id: string, key: CryptoKey): Promise<Result<string>>;
+    /**
+     * Loads the private key stored under `id`, decrypting and re-importing it from
+     * JWK.
+     * @param id - Storage handle.
+     */
+    load(id: string): Promise<Result<CryptoKey>>;
+    /**
+     * Deletes the entry stored under `id`. Missing ids fail (the read path is
+     * keystore-driven and never asks to delete an id it did not store).
+     * @param id - Storage handle.
+     */
+    delete(id: string): Promise<Result<string>>;
+    /**
+     * Lists every stored id.
+     */
+    list(): Promise<Result<readonly string[]>>;
+    private _fileNameFor;
+    /**
+     * Validates the synchronous preconditions for a store: the id is filename-safe,
+     * the key is actually a private key, and its algorithm is one we support.
+     * Returns the resolved filename and algorithm so the async pipeline can run
+     * without re-deriving them.
+     */
+    private _validateKeyToStore;
+    /**
+     * Exports `key` to JWK, wraps it in the stored envelope, encrypts it with
+     * AES-256-GCM, and writes the resulting file as serialized JSON to `fileName`.
+     * Returns the stored `id` on success.
+     */
+    private _encryptAndWrite;
+    private _algorithmOf;
+    private _findFile;
+    private _writeFile;
+    /**
+     * Reads `file`, decrypts the AES-256-GCM envelope, and validates it into the
+     * typed `IStoredPrivateKeyEnvelope`. Read, decrypt, and shape failures
+     * all surface as a decrypt failure for `id`.
+     */
+    private _decryptEnvelope;
+    /**
+     * Parses and shape-validates the stored JWK, then re-imports it as a private
+     * `CryptoKey` for the envelope's algorithm. The WebCrypto JWK-import algorithm
+     * descriptor is shared between public and private keys for every supported
+     * algorithm, so `IKeyPairAlgorithmParams.importPublicKey` is reused here;
+     * the public/private distinction is carried by the requested `usages`.
+     */
+    private _importPrivateKey;
+    /**
+     * Computes the key usages to request when re-importing a stored private key.
+     * WebCrypto rejects `importKey` if the requested usages include operations
+     * absent from the JWK's `key_ops`, so a key originally created with a narrower
+     * usage set than the algorithm default (e.g. an ECDH key with only
+     * `deriveBits`) would fail to load against the algorithm-wide defaults.
+     * Intersect the algorithm's private usages with the JWK's recorded `key_ops`
+     * so we request exactly the operations the stored key actually supports;
+     * fall back to the algorithm's private usages when `key_ops` is absent.
+     */
+    private _importUsagesFor;
+}
+
 /**
  * Supported encryption algorithms.
  * @public
@@ -2260,6 +2369,42 @@ declare interface IEncryptedFile<TMetadata = JsonValue> {
     readonly keyDerivation?: IKeyDerivationParams;
 }
 
+/**
+ * Parameters for {@link CryptoUtils.KeyStore.EncryptedFilePrivateKeyStorage.create}.
+ * @public
+ */
+declare interface IEncryptedFilePrivateKeyStorageCreateParams {
+    /**
+     * Filesystem path to the directory that holds the encrypted private-key
+     * files. Used only when {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams.tree}
+     * is omitted (the default `FsTree` backing). The directory must already
+     * exist.
+     */
+    readonly directory: string;
+    /**
+     * Raw AES-256-GCM key (32 bytes) used to encrypt each file's JWK content.
+     * Consumer-supplied and decoupled from the keystore's password lifecycle —
+     * derive it however the application sees fit (typically the same
+     * password-derived key material the keystore vault uses).
+     */
+    readonly encryptionKey: Uint8Array;
+    /**
+     * {@link CryptoUtils.ICryptoProvider | Crypto provider} used for the
+     * AES-256-GCM encrypt/decrypt of each file's contents.
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * Optional {@link FileTree.IFileTreeDirectoryItem | FileTree directory}
+     * override. When supplied it is used as the storage directory directly and
+     * {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams.directory} is ignored —
+     * pass an in-memory tree for tests, or another Node-compatible backend. When
+     * omitted, a mutable `FsTree` rooted at `directory` is used. (This backend is
+     * Node-only — it round-trips keys through `node:crypto` — so a browser file
+     * tree is not a supported target.)
+     */
+    readonly tree?: FileTree.IFileTreeDirectoryItem;
+}
+
 /**
  * Configuration for encrypted file handling during loading.
  * @public
@@ -3101,9 +3246,12 @@ declare interface IPbkdf2KeyDerivationParams {
 
 /**
  * Pluggable backend that persists raw asymmetric private keys outside of the
- * encrypted keystore vault. Concrete implementations live in platform-specific
- * packages (e.g. an IndexedDB-backed implementation in `@fgv/ts-web-extras` or
- * an encrypted-file implementation in `@fgv/ts-chocolate`).
+ * 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,
@@ -3666,6 +3814,8 @@ declare namespace KeyStore {
     export {
         Converters_2 as Converters,
         KeyStore_2 as KeyStore,
+        EncryptedFilePrivateKeyStorage,
+        IEncryptedFilePrivateKeyStorageCreateParams,
         isKeyStoreFile,
         allKeyPairAlgorithms,
         KeyPairAlgorithm,

package/lib/packlets/crypto-utils/index.browser.d.ts

@@ -5,7 +5,7 @@
  */
 export * from './model';
 export { AES_256_KEY_SIZE, DEFAULT_ALGORITHM, ENCRYPTED_FILE_FORMAT, GCM_AUTH_TAG_SIZE, GCM_IV_SIZE } from './constants';
-import * as KeyStore from './keystore';
+import * as KeyStore from './keystore/index.browser';
 export { KeyStore };
 import * as Converters from './converters';
 export { Converters };

package/lib/packlets/crypto-utils/index.browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.browser.d.ts","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/index.browser.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AAGH,cAAc,SAAS,CAAC;AAGxB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACZ,MAAM,aAAa,CAAC;AAGrB,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,CAAC;AAGpB,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,CAAC;AAGtB,OAAO,EAAE,wBAAwB,EAAE,+BAA+B,EAAE,MAAM,4BAA4B,CAAC;AAGvG,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAM3F,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,UAAU,EACV,0BAA0B,EAC1B,QAAQ,EACR,cAAc,EACf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,8BAA8B,EAC9B,gCAAgC,EAChC,wBAAwB,EACxB,wBAAwB,EACzB,MAAM,eAAe,CAAC;AAIvB,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.browser.d.ts","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/index.browser.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AAGH,cAAc,SAAS,CAAC;AAGxB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACZ,MAAM,aAAa,CAAC;AAIrB,OAAO,KAAK,QAAQ,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,CAAC;AAGpB,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,CAAC;AAGtB,OAAO,EAAE,wBAAwB,EAAE,+BAA+B,EAAE,MAAM,4BAA4B,CAAC;AAGvG,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAM3F,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,UAAU,EACV,0BAA0B,EAC1B,QAAQ,EACR,cAAc,EACf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,8BAA8B,EAC9B,gCAAgC,EAChC,wBAAwB,EACxB,wBAAwB,EACzB,MAAM,eAAe,CAAC;AAIvB,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/lib/packlets/crypto-utils/index.browser.js

@@ -70,8 +70,9 @@ Object.defineProperty(exports, "DEFAULT_ALGORITHM", { enumerable: true, get: fun
 Object.defineProperty(exports, "ENCRYPTED_FILE_FORMAT", { enumerable: true, get: function () { return constants_1.ENCRYPTED_FILE_FORMAT; } });
 Object.defineProperty(exports, "GCM_AUTH_TAG_SIZE", { enumerable: true, get: function () { return constants_1.GCM_AUTH_TAG_SIZE; } });
 Object.defineProperty(exports, "GCM_IV_SIZE", { enumerable: true, get: function () { return constants_1.GCM_IV_SIZE; } });
-// KeyStore namespace
-const KeyStore = __importStar(require("./keystore"));
+// KeyStore namespace (browser-safe barrel — omits the Node-only
+// EncryptedFilePrivateKeyStorage so the browser entry stays free of node:crypto)
+const KeyStore = __importStar(require("./keystore/index.browser"));
 exports.KeyStore = KeyStore;
 // Converters namespace
 const Converters = __importStar(require("./converters"));

package/lib/packlets/crypto-utils/index.browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.browser.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/index.browser.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEZ;;;;GAIG;AAEH,iCAAiC;AACjC,0CAAwB;AAExB,YAAY;AACZ,yCAMqB;AALnB,6GAAA,gBAAgB,OAAA;AAChB,8GAAA,iBAAiB,OAAA;AACjB,kHAAA,qBAAqB,OAAA;AACrB,8GAAA,iBAAiB,OAAA;AACjB,wGAAA,WAAW,OAAA;AAGb,qBAAqB;AACrB,qDAAuC;AAC9B,4BAAQ;AAEjB,uBAAuB;AACvB,yDAA2C;AAClC,gCAAU;AAEnB,6BAA6B;AAC7B,uEAAuG;AAA9F,oIAAA,wBAAwB,OAAA;AAEjC,8DAA8D;AAC9D,mEAA2F;AAAzD,gIAAA,sBAAsB,OAAA;AAExD,8DAA8D;AAC9D,4DAA4D;AAE5D,yBAAyB;AACzB,iDAOyB;AANvB,oHAAA,mBAAmB,OAAA;AACnB,4GAAA,WAAW,OAAA;AACX,2GAAA,UAAU,OAAA;AAEV,yGAAA,QAAQ,OAAA;AACR,+GAAA,cAAc,OAAA;AAGhB,yBAAyB;AACzB,6CAKuB;AAJrB,6HAAA,8BAA8B,OAAA;AAC9B,+HAAA,gCAAgC,OAAA;AAChC,uHAAA,wBAAwB,OAAA;AACxB,uHAAA,wBAAwB,OAAA;AAG1B,qFAAqF;AACrF,uFAAuF;AACvF,+CAA+D;AAAtD,4GAAA,YAAY,OAAA","sourcesContent":["// Copyright (c) 2024 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\n/**\n * Crypto utilities for encrypted file handling and key management (browser version).\n * Note: For browser crypto provider, use \\@fgv/ts-web-extras.\n * @packageDocumentation\n */\n\n// Re-export all types from model\nexport * from './model';\n\n// Constants\nexport {\n  AES_256_KEY_SIZE,\n  DEFAULT_ALGORITHM,\n  ENCRYPTED_FILE_FORMAT,\n  GCM_AUTH_TAG_SIZE,\n  GCM_IV_SIZE\n} from './constants';\n\n// KeyStore namespace\nimport * as KeyStore from './keystore';\nexport { KeyStore };\n\n// Converters namespace\nimport * as Converters from './converters';\nexport { Converters };\n\n// Direct encryption provider\nexport { DirectEncryptionProvider, IDirectEncryptionProviderParams } from './directEncryptionProvider';\n\n// WebCrypto parameter table for asymmetric keypair algorithms\nexport { IKeyPairAlgorithmParams, keyPairAlgorithmParams } from './keyPairAlgorithmParams';\n\n// Note: NodeCryptoProvider is NOT exported in browser version\n// Use BrowserCryptoProvider from @fgv/ts-web-extras instead\n\n// Encrypted file helpers\nexport {\n  createEncryptedFile,\n  decryptFile,\n  fromBase64,\n  ICreateEncryptedFileParams,\n  toBase64,\n  tryDecryptFile\n} from './encryptedFile';\n\n// Multibase/SPKI helpers\nexport {\n  exportPublicKeyAsMultibaseSpki,\n  importPublicKeyFromMultibaseSpki,\n  multibaseBase64UrlDecode,\n  multibaseBase64UrlEncode\n} from './spkiHelpers';\n\n// HPKE base mode (RFC 9180) — DHKEM(X25519, HKDF-SHA256) + HKDF-SHA256 + AES-256-GCM\n// hpkeProvider.ts has no Node-specific imports and is safe in the browser entry point.\nexport { HpkeProvider, IHpkeSealResult } from './hpkeProvider';\n"]}
+{"version":3,"file":"index.browser.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/index.browser.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEZ;;;;GAIG;AAEH,iCAAiC;AACjC,0CAAwB;AAExB,YAAY;AACZ,yCAMqB;AALnB,6GAAA,gBAAgB,OAAA;AAChB,8GAAA,iBAAiB,OAAA;AACjB,kHAAA,qBAAqB,OAAA;AACrB,8GAAA,iBAAiB,OAAA;AACjB,wGAAA,WAAW,OAAA;AAGb,gEAAgE;AAChE,iFAAiF;AACjF,mEAAqD;AAC5C,4BAAQ;AAEjB,uBAAuB;AACvB,yDAA2C;AAClC,gCAAU;AAEnB,6BAA6B;AAC7B,uEAAuG;AAA9F,oIAAA,wBAAwB,OAAA;AAEjC,8DAA8D;AAC9D,mEAA2F;AAAzD,gIAAA,sBAAsB,OAAA;AAExD,8DAA8D;AAC9D,4DAA4D;AAE5D,yBAAyB;AACzB,iDAOyB;AANvB,oHAAA,mBAAmB,OAAA;AACnB,4GAAA,WAAW,OAAA;AACX,2GAAA,UAAU,OAAA;AAEV,yGAAA,QAAQ,OAAA;AACR,+GAAA,cAAc,OAAA;AAGhB,yBAAyB;AACzB,6CAKuB;AAJrB,6HAAA,8BAA8B,OAAA;AAC9B,+HAAA,gCAAgC,OAAA;AAChC,uHAAA,wBAAwB,OAAA;AACxB,uHAAA,wBAAwB,OAAA;AAG1B,qFAAqF;AACrF,uFAAuF;AACvF,+CAA+D;AAAtD,4GAAA,YAAY,OAAA","sourcesContent":["// Copyright (c) 2024 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\n/**\n * Crypto utilities for encrypted file handling and key management (browser version).\n * Note: For browser crypto provider, use \\@fgv/ts-web-extras.\n * @packageDocumentation\n */\n\n// Re-export all types from model\nexport * from './model';\n\n// Constants\nexport {\n  AES_256_KEY_SIZE,\n  DEFAULT_ALGORITHM,\n  ENCRYPTED_FILE_FORMAT,\n  GCM_AUTH_TAG_SIZE,\n  GCM_IV_SIZE\n} from './constants';\n\n// KeyStore namespace (browser-safe barrel — omits the Node-only\n// EncryptedFilePrivateKeyStorage so the browser entry stays free of node:crypto)\nimport * as KeyStore from './keystore/index.browser';\nexport { KeyStore };\n\n// Converters namespace\nimport * as Converters from './converters';\nexport { Converters };\n\n// Direct encryption provider\nexport { DirectEncryptionProvider, IDirectEncryptionProviderParams } from './directEncryptionProvider';\n\n// WebCrypto parameter table for asymmetric keypair algorithms\nexport { IKeyPairAlgorithmParams, keyPairAlgorithmParams } from './keyPairAlgorithmParams';\n\n// Note: NodeCryptoProvider is NOT exported in browser version\n// Use BrowserCryptoProvider from @fgv/ts-web-extras instead\n\n// Encrypted file helpers\nexport {\n  createEncryptedFile,\n  decryptFile,\n  fromBase64,\n  ICreateEncryptedFileParams,\n  toBase64,\n  tryDecryptFile\n} from './encryptedFile';\n\n// Multibase/SPKI helpers\nexport {\n  exportPublicKeyAsMultibaseSpki,\n  importPublicKeyFromMultibaseSpki,\n  multibaseBase64UrlDecode,\n  multibaseBase64UrlEncode\n} from './spkiHelpers';\n\n// HPKE base mode (RFC 9180) — DHKEM(X25519, HKDF-SHA256) + HKDF-SHA256 + AES-256-GCM\n// hpkeProvider.ts has no Node-specific imports and is safe in the browser entry point.\nexport { HpkeProvider, IHpkeSealResult } from './hpkeProvider';\n"]}

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

@@ -0,0 +1,148 @@
+import { Result } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+import { ICryptoProvider } from '../model';
+import { IPrivateKeyStorage } from './privateKeyStorage';
+/**
+ * Parameters for {@link CryptoUtils.KeyStore.EncryptedFilePrivateKeyStorage.create}.
+ * @public
+ */
+export interface IEncryptedFilePrivateKeyStorageCreateParams {
+    /**
+     * Filesystem path to the directory that holds the encrypted private-key
+     * files. Used only when {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams.tree}
+     * is omitted (the default `FsTree` backing). The directory must already
+     * exist.
+     */
+    readonly directory: string;
+    /**
+     * Raw AES-256-GCM key (32 bytes) used to encrypt each file's JWK content.
+     * Consumer-supplied and decoupled from the keystore's password lifecycle —
+     * derive it however the application sees fit (typically the same
+     * password-derived key material the keystore vault uses).
+     */
+    readonly encryptionKey: Uint8Array;
+    /**
+     * {@link CryptoUtils.ICryptoProvider | Crypto provider} used for the
+     * AES-256-GCM encrypt/decrypt of each file's contents.
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * Optional {@link FileTree.IFileTreeDirectoryItem | FileTree directory}
+     * override. When supplied it is used as the storage directory directly and
+     * {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams.directory} is ignored —
+     * pass an in-memory tree for tests, or another Node-compatible backend. When
+     * omitted, a mutable `FsTree` rooted at `directory` is used. (This backend is
+     * Node-only — it round-trips keys through `node:crypto` — so a browser file
+     * tree is not a supported target.)
+     */
+    readonly tree?: FileTree.IFileTreeDirectoryItem;
+}
+/**
+ * {@link CryptoUtils.KeyStore.IPrivateKeyStorage | IPrivateKeyStorage}
+ * implementation that persists each private key as its own AES-256-GCM-encrypted
+ * file in a directory. The file content is the key's JWK, encrypted with a
+ * consumer-supplied 32-byte key via the supplied
+ * {@link CryptoUtils.ICryptoProvider | crypto provider}.
+ *
+ * `supportsNonExtractable` is `false`: persisting to disk requires exporting the
+ * private key to JWK, which only works for `extractable: true` keys. The
+ * keystore generates extractable keys when a backend reports `false` here.
+ *
+ * I/O goes through the {@link FileTree.FileTree | FileTree} abstraction (default
+ * `FsTree`), so the same implementation works against an in-memory tree (tests)
+ * or any other Node-compatible backend.
+ *
+ * This backend is **Node-only**: it round-trips private keys through
+ * `node:crypto` (`crypto.webcrypto.subtle`), so it is intentionally excluded
+ * from the browser entry point. Browser consumers should use
+ * `IdbPrivateKeyStorage` from `@fgv/ts-web-extras` instead.
+ *
+ * Single-process assumption: there is no inter-process locking. Concurrent
+ * writers to the same directory may race.
+ *
+ * @public
+ */
+export declare class EncryptedFilePrivateKeyStorage implements IPrivateKeyStorage {
+    /**
+     * `false` — disk persistence round-trips via JWK, which requires extractable
+     * keys.
+     */
+    readonly supportsNonExtractable: false;
+    private readonly _directory;
+    private readonly _encryptionKey;
+    private readonly _cryptoProvider;
+    private constructor();
+    /**
+     * Creates a new {@link CryptoUtils.KeyStore.EncryptedFilePrivateKeyStorage}.
+     * @param params - {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams}.
+     * @returns `Success` with the new instance, or `Failure` if the encryption
+     * key is the wrong size or the storage directory cannot be opened.
+     */
+    static create(params: IEncryptedFilePrivateKeyStorageCreateParams): Result<EncryptedFilePrivateKeyStorage>;
+    /**
+     * Stores `key` under `id` as an encrypted JWK file.
+     * @param id - Storage handle. Must be a safe filename token
+     * (`[A-Za-z0-9._-]+`, not `.`/`..`).
+     * @param key - The extractable private `CryptoKey` to persist.
+     */
+    store(id: string, key: CryptoKey): Promise<Result<string>>;
+    /**
+     * Loads the private key stored under `id`, decrypting and re-importing it from
+     * JWK.
+     * @param id - Storage handle.
+     */
+    load(id: string): Promise<Result<CryptoKey>>;
+    /**
+     * Deletes the entry stored under `id`. Missing ids fail (the read path is
+     * keystore-driven and never asks to delete an id it did not store).
+     * @param id - Storage handle.
+     */
+    delete(id: string): Promise<Result<string>>;
+    /**
+     * Lists every stored id.
+     */
+    list(): Promise<Result<readonly string[]>>;
+    private _fileNameFor;
+    /**
+     * Validates the synchronous preconditions for a store: the id is filename-safe,
+     * the key is actually a private key, and its algorithm is one we support.
+     * Returns the resolved filename and algorithm so the async pipeline can run
+     * without re-deriving them.
+     */
+    private _validateKeyToStore;
+    /**
+     * Exports `key` to JWK, wraps it in the stored envelope, encrypts it with
+     * AES-256-GCM, and writes the resulting file as serialized JSON to `fileName`.
+     * Returns the stored `id` on success.
+     */
+    private _encryptAndWrite;
+    private _algorithmOf;
+    private _findFile;
+    private _writeFile;
+    /**
+     * Reads `file`, decrypts the AES-256-GCM envelope, and validates it into the
+     * typed `IStoredPrivateKeyEnvelope`. Read, decrypt, and shape failures
+     * all surface as a decrypt failure for `id`.
+     */
+    private _decryptEnvelope;
+    /**
+     * Parses and shape-validates the stored JWK, then re-imports it as a private
+     * `CryptoKey` for the envelope's algorithm. The WebCrypto JWK-import algorithm
+     * descriptor is shared between public and private keys for every supported
+     * algorithm, so `IKeyPairAlgorithmParams.importPublicKey` is reused here;
+     * the public/private distinction is carried by the requested `usages`.
+     */
+    private _importPrivateKey;
+    /**
+     * Computes the key usages to request when re-importing a stored private key.
+     * WebCrypto rejects `importKey` if the requested usages include operations
+     * absent from the JWK's `key_ops`, so a key originally created with a narrower
+     * usage set than the algorithm default (e.g. an ECDH key with only
+     * `deriveBits`) would fail to load against the algorithm-wide defaults.
+     * Intersect the algorithm's private usages with the JWK's recorded `key_ops`
+     * so we request exactly the operations the stored key actually supports;
+     * fall back to the algorithm's private usages when `key_ops` is absent.
+     */
+    private _importUsagesFor;
+}
+//# sourceMappingURL=encryptedFilePrivateKeyStorage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"encryptedFilePrivateKeyStorage.d.ts","sourceRoot":"","sources":["../../../../src/packlets/crypto-utils/keystore/encryptedFilePrivateKeyStorage.ts"],"names":[],"mappings":"AAqBA,OAAO,EAML,MAAM,EAEP,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,QAAQ,EAAc,MAAM,mBAAmB,CAAC;AAGzD,OAAO,EAAE,eAAe,EAAoB,MAAM,UAAU,CAAC;AAG7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,2CAA2C;IAC1D;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IAEnC;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,eAAe,CAAC;IAEzC;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,sBAAsB,CAAC;CACjD;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,8BAA+B,YAAW,kBAAkB;IACvE;;;OAGG;IACH,SAAgB,sBAAsB,EAAE,KAAK,CAAS;IAEtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAa;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAElD,OAAO;IAYP;;;;;OAKG;WACW,MAAM,CAClB,MAAM,EAAE,2CAA2C,GAClD,MAAM,CAAC,8BAA8B,CAAC;IAgBzC;;;;;OAKG;IACU,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAMvE;;;;OAIG;IACU,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAUzD;;;;OAIG;IACU,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAsBxD;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IAWvD,OAAO,CAAC,YAAY;IAOpB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAc3B;;;;OAIG;YACW,gBAAgB;IAuB9B,OAAO,CAAC,YAAY;IA6BpB,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,UAAU;IAiBlB;;;;OAIG;YACW,gBAAgB;IAW9B;;;;;;OAMG;YACW,iBAAiB;IAsB/B;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB;CAQzB"}