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

package/dist/packlets/crypto-utils/keystore/keyStore.js

@@ -17,9 +17,10 @@
 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
-import { captureResult, fail, succeed } from '@fgv/ts-utils';
+import { captureAsyncResult, captureResult, fail, succeed } from '@fgv/ts-utils';
 import * as Constants from '../constants';
 import { createEncryptedFile } from '../encryptedFile';
+import { keyPairAlgorithmParams } from '../keyPairAlgorithmParams';
 import { ARGON2ID_OWASP_MIN } from '../model';
 import { DEFAULT_KEYSTORE_ITERATIONS, DEFAULT_SECRET_ITERATIONS, KEYSTORE_FORMAT, MIN_SALT_LENGTH } from './model';
 import { keystoreFile, keystoreVaultContents } from './converters';
@@ -29,6 +30,11 @@ import { keystoreFile, keystoreVaultContents } from './converters';
 function getCurrentTimestamp() {
     return new Date().toISOString();
 }
+// WebCrypto key usages that only ever apply to a public key. Filtering these
+// out of the keypair usages yields the usages valid for the private half, which
+// `crypto.subtle.importKey` requires when re-importing a private JWK. Mirrors
+// the same list in `EncryptedFilePrivateKeyStorage`.
+const PUBLIC_ONLY_USAGES = ['verify', 'encrypt', 'wrapKey'];
 // ============================================================================
 // KeyStore Class
 // ============================================================================
@@ -61,6 +67,20 @@ function getCurrentTimestamp() {
  * 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
  */
 export class KeyStore {
@@ -286,6 +306,12 @@ export class KeyStore {
      * 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
@@ -773,8 +799,16 @@ export class KeyStore {
         if (options.extractable === false && backendExtractable) {
             return fail(`Cannot create non-extractable keypair for '${name}': storage backend does not support non-extractable keys`);
         }
-        const extractable = (_a = options.extractable) !== null && _a !== void 0 ? _a : backendExtractable;
-        const keyPairResult = await this._cryptoProvider.generateKeyPair(options.algorithm, extractable);
+        // Extractability of the LIVE stored key. Escrow is orthogonal — it never
+        // changes this; the escrow copy is captured separately from a transient
+        // extractable key.
+        const liveExtractable = (_a = options.extractable) !== null && _a !== void 0 ? _a : backendExtractable;
+        // For escrow we must be able to export the private key to JWK, which only
+        // works on an extractable key, so the transient keypair is generated
+        // extractable regardless of `liveExtractable`. Without escrow it is
+        // generated directly at the live setting.
+        const generateExtractable = options.escrow === true ? true : liveExtractable;
+        const keyPairResult = await this._cryptoProvider.generateKeyPair(options.algorithm, generateExtractable);
         /* c8 ignore next 3 - crypto provider errors covered in nodeCryptoProvider tests; cannot be triggered here without mocking */
         if (keyPairResult.isFailure()) {
             return fail(`Failed to generate keypair for '${name}': ${keyPairResult.message}`);
@@ -785,6 +819,34 @@ export class KeyStore {
         if (jwkResult.isFailure()) {
             return fail(`Failed to export public key for '${name}': ${jwkResult.message}`);
         }
+        // Escrow (opt-in). The bare private key exists only as three local
+        // artifacts, none of which is returned or logged: (1) the transient
+        // extractable `privateKey` above; (2) the exported `escrowedPrivateKeyJwk`,
+        // which is carried in the vault entry (same custody class as the public
+        // JWK); (3) a freshly re-imported non-extractable key handed to `store()`
+        // when the live copy must be non-extractable. When the live copy is
+        // extractable the transient key IS the live copy and is stored directly.
+        let escrowedPrivateKeyJwk;
+        let keyToStore = privateKey;
+        if (options.escrow === true) {
+            // Chain the export → (conditional) non-extractable re-import so the
+            // failure dispatch lives in ts-utils rather than in local branch nodes.
+            // When the live copy is extractable the transient key IS the live copy;
+            // otherwise a freshly re-imported non-extractable key is stored instead.
+            const escrowPrepResult = await (await this._exportPrivateKeyJwk(privateKey, name)).thenOnSuccess(async (jwk) => {
+                if (liveExtractable) {
+                    return succeed({ jwk, keyToStore: privateKey });
+                }
+                return (await this._importEscrowedPrivateKey(jwk, options.algorithm, false))
+                    .withErrorFormat((msg) => `Failed to prepare non-extractable key for '${name}': ${msg}`)
+                    .onSuccess((reimported) => succeed({ jwk, keyToStore: reimported }));
+            });
+            /* c8 ignore next 3 - escrowPrepResult only fails if exporting or re-importing a freshly-generated valid key fails, which a healthy provider cannot do (same untestable class as the keyPairResult/jwkResult/idResult guards); the import-failure path itself is covered via getKeyPair rehydration of a malformed escrow JWK */
+            if (escrowPrepResult.isFailure()) {
+                return fail(escrowPrepResult.message);
+            }
+            ({ jwk: escrowedPrivateKeyJwk, keyToStore } = escrowPrepResult.value);
+        }
         const idResult = this._generateId();
         /* c8 ignore next 3 - random-bytes failure is hard to trigger with a healthy provider */
         if (idResult.isFailure()) {
@@ -792,7 +854,7 @@ export class KeyStore {
         }
         const id = idResult.value;
         // Storage-first: write the private key before committing the vault entry.
-        const storeResult = await this._privateKeyStorage.store(id, privateKey);
+        const storeResult = await this._privateKeyStorage.store(id, keyToStore);
         if (storeResult.isFailure()) {
             return fail(`Failed to persist private key for '${name}': ${storeResult.message}`);
         }
@@ -802,6 +864,7 @@ export class KeyStore {
             id,
             algorithm: options.algorithm,
             publicKeyJwk: jwkResult.value,
+            escrowedPrivateKeyJwk,
             description: options.description,
             createdAt: getCurrentTimestamp()
         };
@@ -816,12 +879,23 @@ export class KeyStore {
      * 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
      */
-    async getKeyPair(name) {
+    async getKeyPair(name, options) {
         if (!this._secrets) {
             return fail('Key store is locked');
         }
@@ -835,16 +909,9 @@ export class KeyStore {
         if (!this._privateKeyStorage) {
             return fail('No private key storage configured');
         }
-        const privateResult = await this._privateKeyStorage.load(entry.id);
-        if (privateResult.isFailure()) {
-            return fail(`Failed to load private key for '${name}': ${privateResult.message}`);
-        }
-        const publicResult = await this._cryptoProvider.importPublicKeyJwk(entry.publicKeyJwk, entry.algorithm);
-        /* c8 ignore next 3 - vault JWKs that previously exported cleanly are extremely unlikely to fail re-import */
-        if (publicResult.isFailure()) {
-            return fail(`Failed to re-import public key for '${name}': ${publicResult.message}`);
-        }
-        return succeed({ publicKey: publicResult.value, privateKey: privateResult.value });
+        return (await this._loadOrRehydratePrivateKey(name, entry, options)).thenOnSuccess(async (privateKey) => (await this._cryptoProvider.importPublicKeyJwk(entry.publicKeyJwk, entry.algorithm))
+            .withErrorFormat((msg) => `Failed to re-import public key for '${name}': ${msg}`)
+            .onSuccess((publicKey) => succeed({ publicKey, privateKey })));
     }
     /**
      * Lists secret names filtered by type.
@@ -1079,6 +1146,7 @@ export class KeyStore {
                     id: entry.id,
                     algorithm: entry.algorithm,
                     publicKeyJwk: entry.publicKeyJwk,
+                    escrowedPrivateKeyJwk: entry.escrowedPrivateKeyJwk,
                     description: entry.description,
                     createdAt: entry.createdAt
                 };
@@ -1178,6 +1246,7 @@ export class KeyStore {
                     id: jsonEntry.id,
                     algorithm: jsonEntry.algorithm,
                     publicKeyJwk: jsonEntry.publicKeyJwk,
+                    escrowedPrivateKeyJwk: jsonEntry.escrowedPrivateKeyJwk,
                     description: jsonEntry.description,
                     createdAt: jsonEntry.createdAt
                 };
@@ -1233,6 +1302,76 @@ export class KeyStore {
         entry.key.fill(0);
         return undefined;
     }
+    /**
+     * 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.
+     */
+    async _exportPrivateKeyJwk(privateKey, name) {
+        return captureAsyncResult(() => globalThis.crypto.subtle.exportKey('jwk', privateKey)).withErrorFormat((msg) => `Failed to export private key for escrow of '${name}': ${msg}`);
+    }
+    /**
+     * 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`.
+     */
+    async _importEscrowedPrivateKey(jwk, algorithm, extractable) {
+        const params = keyPairAlgorithmParams[algorithm];
+        const usages = KeyStore._privateKeyUsagesFor(jwk, params);
+        return captureAsyncResult(() => globalThis.crypto.subtle.importKey('jwk', jwk, params.importPublicKey, extractable, usages)).withErrorFormat((msg) => `Failed to import escrowed private key: ${msg}`);
+    }
+    /**
+     * 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.
+     */
+    async _loadOrRehydratePrivateKey(name, entry, options) {
+        // Non-undefined by getKeyPair's precondition check.
+        const storage = this._privateKeyStorage;
+        const loadResult = await storage.load(entry.id);
+        if (loadResult.isSuccess()) {
+            return succeed(loadResult.value);
+        }
+        if ((options === null || options === void 0 ? void 0 : options.rehydrate) !== true || entry.escrowedPrivateKeyJwk === undefined) {
+            return fail(`Failed to load private key for '${name}': ${loadResult.message}`);
+        }
+        // Fill-a-gap recovery: import the escrowed key non-extractable where the
+        // backend supports it (extractable otherwise, since a JWK-round-tripping
+        // backend cannot store a non-extractable key), then persist it.
+        const backendExtractable = !storage.supportsNonExtractable;
+        const importResult = await this._importEscrowedPrivateKey(entry.escrowedPrivateKeyJwk, entry.algorithm, backendExtractable);
+        if (importResult.isFailure()) {
+            return fail(`Failed to rehydrate private key for '${name}' from escrow: ${importResult.message}`);
+        }
+        const storeResult = await storage.store(entry.id, importResult.value);
+        if (storeResult.isFailure()) {
+            return fail(`Failed to persist rehydrated private key for '${name}': ${storeResult.message}`);
+        }
+        return succeed(importResult.value);
+    }
+    /**
+     * 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.
+     */
+    static _privateKeyUsagesFor(jwk, params) {
+        const privateUsages = params.keyPairUsages.filter((usage) => !PUBLIC_ONLY_USAGES.includes(usage));
+        const keyOps = jwk.key_ops;
+        if (keyOps === undefined) {
+            return [...privateUsages];
+        }
+        return privateUsages.filter((usage) => keyOps.includes(usage));
+    }
     /**
      * Constant-time byte comparison. Returns false immediately for length
      * mismatch (length is not secret); for equal-length inputs, walks the full