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

package/dist/packlets/crypto-utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/index.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;;;GAGG;AAEH,iCAAiC;AACjC,cAAc,SAAS,CAAC;AAExB,YAAY;AACZ,OAAO,KAAK,SAAS,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,qBAAqB;AACrB,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,CAAC;AAEpB,uBAAuB;AACvB,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,6BAA6B;AAC7B,OAAO,EAAE,wBAAwB,EAAmC,MAAM,4BAA4B,CAAC;AAEvG,8DAA8D;AAC9D,OAAO,EAA2B,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAE3F,qDAAqD;AACrD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE9E,yBAAyB;AACzB,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,UAAU,EAEV,QAAQ,EACR,cAAc,EACf,MAAM,iBAAiB,CAAC;AAEzB,qCAAqC;AACrC,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,8BAA8B,EAC9B,gCAAgC,EAChC,6BAA6B,EAC7B,4BAA4B,EAC5B,wBAAwB,EACxB,wBAAwB,EACzB,MAAM,eAAe,CAAC;AAEvB,qFAAqF;AACrF,OAAO,EAAE,YAAY,EAAmB,MAAM,gBAAgB,CAAC","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.\n * @packageDocumentation\n */\n\n// Re-export all types from model\nexport * from './model';\n\n// Constants\nimport * as Constants from './constants';\nexport { 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// Node.js crypto provider (Node.js environment only)\nexport { NodeCryptoProvider, nodeCryptoProvider } from './nodeCryptoProvider';\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 + base64url helpers\nexport {\n  base64UrlNoPadDecode,\n  base64UrlNoPadEncode,\n  exportPublicKeyAsMultibaseSpki,\n  importPublicKeyFromMultibaseSpki,\n  isValidMultibaseSpkiPublicKey,\n  MultibaseSpkiPublicKeyRegExp,\n  multibaseBase64UrlDecode,\n  multibaseBase64UrlEncode\n} from './spkiHelpers';\n\n// HPKE base mode (RFC 9180) — DHKEM(X25519, HKDF-SHA256) + HKDF-SHA256 + AES-256-GCM\nexport { HpkeProvider, IHpkeSealResult } from './hpkeProvider';\n"]}

package/dist/packlets/crypto-utils/keyPairAlgorithmParams.js

@@ -0,0 +1,71 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// 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.
+/**
+ * Lookup table from {@link CryptoUtils.KeyPairAlgorithm} to the WebCrypto
+ * parameters needed to drive `crypto.subtle`. Shared between every
+ * {@link CryptoUtils.ICryptoProvider} implementation since both Node and
+ * browser providers speak the same WebCrypto API. Exposed for downstream
+ * provider implementations (e.g. browser-side providers in `@fgv/ts-web-extras`).
+ * @public
+ */
+export const keyPairAlgorithmParams = {
+    'ecdsa-p256': {
+        generateKey: { name: 'ECDSA', namedCurve: 'P-256' },
+        importPublicKey: { name: 'ECDSA', namedCurve: 'P-256' },
+        keyPairUsages: ['sign', 'verify'],
+        publicKeyUsages: ['verify']
+    },
+    'rsa-oaep-2048': {
+        generateKey: {
+            name: 'RSA-OAEP',
+            modulusLength: 2048,
+            publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
+            hash: 'SHA-256'
+        },
+        importPublicKey: { name: 'RSA-OAEP', hash: 'SHA-256' },
+        keyPairUsages: ['encrypt', 'decrypt'],
+        publicKeyUsages: ['encrypt']
+    },
+    'ecdh-p256': {
+        generateKey: { name: 'ECDH', namedCurve: 'P-256' },
+        importPublicKey: { name: 'ECDH', namedCurve: 'P-256' },
+        // WebCrypto filters per-role: the private key takes both derive usages,
+        // and the public key gets [] since an ECDH public key alone cannot derive.
+        keyPairUsages: ['deriveKey', 'deriveBits'],
+        // Importing only the recipient's public key — empty usages because a
+        // standalone ECDH public key has no derivation capability.
+        publicKeyUsages: []
+    },
+    ed25519: {
+        generateKey: { name: 'Ed25519' },
+        importPublicKey: { name: 'Ed25519' },
+        keyPairUsages: ['sign', 'verify'],
+        publicKeyUsages: ['verify']
+    },
+    x25519: {
+        generateKey: { name: 'X25519' },
+        importPublicKey: { name: 'X25519' },
+        // WebCrypto filters per-role: the private key takes both derive usages,
+        // the public key gets [] since a standalone X25519 public key cannot derive.
+        keyPairUsages: ['deriveKey', 'deriveBits'],
+        publicKeyUsages: []
+    }
+};
+//# sourceMappingURL=keyPairAlgorithmParams.js.map

package/dist/packlets/crypto-utils/keyPairAlgorithmParams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyPairAlgorithmParams.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/keyPairAlgorithmParams.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;AAmDZ;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAgE;IACjG,YAAY,EAAE;QACZ,WAAW,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE;QACnD,eAAe,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE;QACvD,aAAa,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;QACjC,eAAe,EAAE,CAAC,QAAQ,CAAC;KAC5B;IACD,eAAe,EAAE;QACf,WAAW,EAAE;YACX,IAAI,EAAE,UAAU;YAChB,aAAa,EAAE,IAAI;YACnB,cAAc,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YAClD,IAAI,EAAE,SAAS;SAChB;QACD,eAAe,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;QACtD,aAAa,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC;QACrC,eAAe,EAAE,CAAC,SAAS,CAAC;KAC7B;IACD,WAAW,EAAE;QACX,WAAW,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE;QAClD,eAAe,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE;QACtD,wEAAwE;QACxE,2EAA2E;QAC3E,aAAa,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;QAC1C,qEAAqE;QACrE,2DAA2D;QAC3D,eAAe,EAAE,EAAE;KACpB;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;QAChC,eAAe,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;QACpC,aAAa,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;QACjC,eAAe,EAAE,CAAC,QAAQ,CAAC;KAC5B;IACD,MAAM,EAAE;QACN,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC/B,eAAe,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QACnC,wEAAwE;QACxE,6EAA6E;QAC7E,aAAa,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;QAC1C,eAAe,EAAE,EAAE;KACpB;CACF,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 { KeyPairAlgorithm } from './model';\n\n/**\n * WebCrypto parameters for a single {@link CryptoUtils.KeyPairAlgorithm}.\n * Implementations of {@link CryptoUtils.ICryptoProvider} use this table to\n * translate the small public algorithm enum into the WebCrypto algorithm\n * objects and key-usage arrays expected by `crypto.subtle`.\n * @public\n */\nexport interface IKeyPairAlgorithmParams {\n  /**\n   * Algorithm parameters for `crypto.subtle.generateKey`. Always an asymmetric\n   * variant — these algorithms produce a `CryptoKeyPair`, not a single key.\n   * The literal `{ name: 'Ed25519' }` member covers WebCrypto's Secure-Curves\n   * Ed25519 algorithm; `{ name: 'X25519' }` covers the X25519 key-agreement\n   * algorithm. Both take only a `name`; using literals rather than the base\n   * `Algorithm` keeps the union closed to the algorithms this table supports.\n   */\n  readonly generateKey:\n    | RsaHashedKeyGenParams\n    | EcKeyGenParams\n    | { readonly name: 'Ed25519' }\n    | { readonly name: 'X25519' };\n\n  /**\n   * Algorithm parameters for `crypto.subtle.importKey('jwk', ...)` when\n   * importing the public half of a keypair. The literal `{ name: 'Ed25519' }`\n   * member covers Ed25519 imports; `{ name: 'X25519' }` covers X25519 imports.\n   * Both take only a `name`; using literals rather than the base `Algorithm`\n   * keeps the union closed to the algorithms this table supports.\n   */\n  readonly importPublicKey:\n    | RsaHashedImportParams\n    | EcKeyImportParams\n    | { readonly name: 'Ed25519' }\n    | { readonly name: 'X25519' };\n\n  /**\n   * Default key usages for the generated `CryptoKeyPair`. Both halves receive\n   * the usages WebCrypto considers valid for their role; the platform filters.\n   */\n  readonly keyPairUsages: ReadonlyArray<KeyUsage>;\n\n  /**\n   * Key usages applied when re-importing only the public key.\n   */\n  readonly publicKeyUsages: ReadonlyArray<KeyUsage>;\n}\n\n/**\n * Lookup table from {@link CryptoUtils.KeyPairAlgorithm} to the WebCrypto\n * parameters needed to drive `crypto.subtle`. Shared between every\n * {@link CryptoUtils.ICryptoProvider} implementation since both Node and\n * browser providers speak the same WebCrypto API. Exposed for downstream\n * provider implementations (e.g. browser-side providers in `@fgv/ts-web-extras`).\n * @public\n */\nexport const keyPairAlgorithmParams: Readonly<Record<KeyPairAlgorithm, IKeyPairAlgorithmParams>> = {\n  'ecdsa-p256': {\n    generateKey: { name: 'ECDSA', namedCurve: 'P-256' },\n    importPublicKey: { name: 'ECDSA', namedCurve: 'P-256' },\n    keyPairUsages: ['sign', 'verify'],\n    publicKeyUsages: ['verify']\n  },\n  'rsa-oaep-2048': {\n    generateKey: {\n      name: 'RSA-OAEP',\n      modulusLength: 2048,\n      publicExponent: new Uint8Array([0x01, 0x00, 0x01]),\n      hash: 'SHA-256'\n    },\n    importPublicKey: { name: 'RSA-OAEP', hash: 'SHA-256' },\n    keyPairUsages: ['encrypt', 'decrypt'],\n    publicKeyUsages: ['encrypt']\n  },\n  'ecdh-p256': {\n    generateKey: { name: 'ECDH', namedCurve: 'P-256' },\n    importPublicKey: { name: 'ECDH', namedCurve: 'P-256' },\n    // WebCrypto filters per-role: the private key takes both derive usages,\n    // and the public key gets [] since an ECDH public key alone cannot derive.\n    keyPairUsages: ['deriveKey', 'deriveBits'],\n    // Importing only the recipient's public key — empty usages because a\n    // standalone ECDH public key has no derivation capability.\n    publicKeyUsages: []\n  },\n  ed25519: {\n    generateKey: { name: 'Ed25519' },\n    importPublicKey: { name: 'Ed25519' },\n    keyPairUsages: ['sign', 'verify'],\n    publicKeyUsages: ['verify']\n  },\n  x25519: {\n    generateKey: { name: 'X25519' },\n    importPublicKey: { name: 'X25519' },\n    // WebCrypto filters per-role: the private key takes both derive usages,\n    // the public key gets [] since a standalone X25519 public key cannot derive.\n    keyPairUsages: ['deriveKey', 'deriveBits'],\n    publicKeyUsages: []\n  }\n};\n"]}

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

@@ -17,9 +17,9 @@
 // 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 { Converters } from '@fgv/ts-utils';
-import { base64String, encryptionAlgorithm, keyDerivationParams } from '../converters';
-import { allKeyStoreSecretTypes, KEYSTORE_FORMAT } from './model';
+import { Converters, succeed, Validators } from '@fgv/ts-utils';
+import { base64String, encryptionAlgorithm, pbkdf2KeyDerivationParams } from '../converters';
+import { allKeyPairAlgorithms, allKeyStoreSecretTypes, allKeyStoreSymmetricSecretTypes, KEYSTORE_FORMAT, allKeyStoreAsymmetricSecretTypes } from './model';
 // ============================================================================
 // Key Store Format Converter
 // ============================================================================
@@ -31,31 +31,123 @@ export const keystoreFormat = Converters.enumeratedValue([
     KEYSTORE_FORMAT
 ]);
 // ============================================================================
-// Secret Type Converter
+// Secret Type Converters
 // ============================================================================
 /**
- * Converter for {@link CryptoUtils.KeyStore.KeyStoreSecretType | key store secret type} discriminator.
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSecretType | any key store secret type} discriminator.
+ * Accepts both symmetric and asymmetric type values.
  * @public
  */
 export const keystoreSecretType = Converters.enumeratedValue(allKeyStoreSecretTypes);
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSymmetricSecretType | symmetric secret type} discriminator.
+ * Accepts only `'encryption-key'` and `'api-key'`.
+ * @public
+ */
+export const keystoreSymmetricSecretType = Converters.enumeratedValue(allKeyStoreSymmetricSecretTypes);
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreAsymmetricSecretType | asymmetric secret type} discriminator.
+ * Accepts only `'asymmetric-keypair'`.
+ * @public
+ */
+export const keystoreAsymmetricSecretType = Converters.enumeratedValue(allKeyStoreAsymmetricSecretTypes);
+// ============================================================================
+// Key Pair Algorithm Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyPairAlgorithm | key pair algorithm}.
+ * @public
+ */
+export const keyPairAlgorithm = Converters.enumeratedValue(allKeyPairAlgorithms);
 // ============================================================================
-// Secret Entry Converters
+// JWK Shape Validator
 // ============================================================================
 /**
- * Converter for {@link CryptoUtils.KeyStore.IKeyStoreSecretEntryJson | key store secret entry} in JSON format.
- * The `type` field is optional for backwards compatibility — missing means `'encryption-key'`.
+ * In-place shape check for a JSON Web Key. Asserts only that the input is a
+ * non-array object whose `kty` discriminator is a string; every other JWK
+ * field passes through untouched. This is intentionally **not** a true JWK
+ * validator — per-algorithm correctness (RSA `n`/`e`, EC `crv`/`x`/`y`,
+ * key-size constraints, etc.) is delegated to `crypto.subtle.importKey` at
+ * first use, which is the authoritative checker. The "shape" suffix in the
+ * name is the warning sign for readers expecting full validation.
+ * @remarks
+ * Built with `Validators.object` (in-place, non-strict) so unknown JWK fields
+ * survive the round-trip; the cast to `FieldValidators<JsonWebKey>` is required
+ * only because TypeScript's mapped type demands an entry for every key in
+ * `JsonWebKey`. At runtime the `ObjectValidator` only inspects keys present in
+ * the field-validators map.
  * @public
  */
-export const keystoreSecretEntryJson = Converters.object({
+export const jsonWebKeyShape = Validators.object({
+    kty: Validators.string
+});
+// ============================================================================
+// Symmetric Secret Entry Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson | symmetric secret entry} in JSON form.
+ *
+ * @remarks
+ * Backwards compatibility with vaults written before asymmetric-keypair
+ * support: those entries may lack the `type` discriminator on the wire. To
+ * keep the model type honest (`type` is required on
+ * {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson}, see its docs),
+ * we declare `type` in `optionalFields` so the inner `Converters.object` will
+ * accept input without it, then `.map()` injects the default
+ * `'encryption-key'` when missing. The output therefore always carries the
+ * discriminator and downstream code never sees the legacy missing-type form.
+ *
+ * @public
+ */
+export const keystoreSymmetricEntryJson = Converters.object({
     name: Converters.string,
-    type: keystoreSecretType,
+    type: keystoreSymmetricSecretType,
     key: base64String,
     description: Converters.string,
     createdAt: Converters.string
 }, {
+    // `type` is optional at the input layer for legacy-vault compatibility;
+    // the .map() below normalizes by injecting the default.
     optionalFields: ['type', 'description']
+}).map((entry) => {
+    var _a;
+    return succeed(Object.assign(Object.assign({}, entry), { type: (_a = entry.type) !== null && _a !== void 0 ? _a : 'encryption-key' }));
 });
 // ============================================================================
+// Asymmetric Keypair Entry Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreAsymmetricEntryJson | asymmetric keypair entry} in JSON form.
+ * The `publicKeyJwk` field passes through {@link CryptoUtils.KeyStore.Converters.jsonWebKeyShape | jsonWebKeyShape}
+ * (shape check only — see its docs); cryptographic correctness is enforced by
+ * `crypto.subtle.importKey` at use.
+ * @public
+ */
+export const keystoreAsymmetricEntryJson = Converters.object({
+    name: Converters.string,
+    type: keystoreAsymmetricSecretType,
+    id: Converters.string,
+    algorithm: keyPairAlgorithm,
+    publicKeyJwk: jsonWebKeyShape,
+    description: Converters.string.optional(),
+    createdAt: Converters.string
+});
+// ============================================================================
+// Discriminated-Union Entry Converter
+// ============================================================================
+/**
+ * Discriminated-union converter for any {@link CryptoUtils.KeyStore.IKeyStoreEntryJson | key store entry} in JSON form.
+ * Routes by the `type` field: `'asymmetric-keypair'` is parsed by
+ * {@link CryptoUtils.KeyStore.Converters.keystoreAsymmetricEntryJson | keystoreAsymmetricEntryJson},
+ * anything else (including a missing `type` field for backwards compatibility) by
+ * {@link CryptoUtils.KeyStore.Converters.keystoreSymmetricEntryJson | keystoreSymmetricEntryJson}.
+ * @public
+ */
+export const keystoreSecretEntryJson = Converters.oneOf([
+    keystoreAsymmetricEntryJson,
+    keystoreSymmetricEntryJson
+]);
+// ============================================================================
 // Vault Contents Converter
 // ============================================================================
 /**
@@ -79,6 +171,6 @@ export const keystoreFile = Converters.object({
     iv: base64String,
     authTag: base64String,
     encryptedData: base64String,
-    keyDerivation: keyDerivationParams
+    keyDerivation: pbkdf2KeyDerivationParams
 });
 //# sourceMappingURL=converters.js.map

package/dist/packlets/crypto-utils/keystore/converters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"converters.js","sourceRoot":"","sources":["../../../../src/packlets/crypto-utils/keystore/converters.ts"],"names":[],"mappings":"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","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 { Converter, Converters, succeed, Validation, Validator, Validators } from '@fgv/ts-utils';\nimport { base64String, encryptionAlgorithm, pbkdf2KeyDerivationParams } from '../converters';\nimport {\n  allKeyPairAlgorithms,\n  allKeyStoreSecretTypes,\n  allKeyStoreSymmetricSecretTypes,\n  IKeyStoreAsymmetricEntryJson,\n  IKeyStoreEntryJson,\n  IKeyStoreFile,\n  IKeyStoreSymmetricEntryJson,\n  IKeyStoreVaultContents,\n  KEYSTORE_FORMAT,\n  KeyPairAlgorithm,\n  KeyStoreAsymmetricSecretType,\n  KeyStoreFormat,\n  KeyStoreSecretType,\n  KeyStoreSymmetricSecretType,\n  allKeyStoreAsymmetricSecretTypes\n} from './model';\n\n// ============================================================================\n// Key Store Format Converter\n// ============================================================================\n\n/**\n * Converter for {@link CryptoUtils.KeyStore.KeyStoreFormat | key store format} version.\n * @public\n */\nexport const keystoreFormat: Converter<KeyStoreFormat> = Converters.enumeratedValue<KeyStoreFormat>([\n  KEYSTORE_FORMAT\n]);\n\n// ============================================================================\n// Secret Type Converters\n// ============================================================================\n\n/**\n * Converter for {@link CryptoUtils.KeyStore.KeyStoreSecretType | any key store secret type} discriminator.\n * Accepts both symmetric and asymmetric type values.\n * @public\n */\nexport const keystoreSecretType: Converter<KeyStoreSecretType> =\n  Converters.enumeratedValue<KeyStoreSecretType>(allKeyStoreSecretTypes);\n\n/**\n * Converter for {@link CryptoUtils.KeyStore.KeyStoreSymmetricSecretType | symmetric secret type} discriminator.\n * Accepts only `'encryption-key'` and `'api-key'`.\n * @public\n */\nexport const keystoreSymmetricSecretType: Converter<KeyStoreSymmetricSecretType> =\n  Converters.enumeratedValue<KeyStoreSymmetricSecretType>(allKeyStoreSymmetricSecretTypes);\n\n/**\n * Converter for {@link CryptoUtils.KeyStore.KeyStoreAsymmetricSecretType | asymmetric secret type} discriminator.\n * Accepts only `'asymmetric-keypair'`.\n * @public\n */\nexport const keystoreAsymmetricSecretType: Converter<KeyStoreAsymmetricSecretType> =\n  Converters.enumeratedValue<KeyStoreAsymmetricSecretType>(allKeyStoreAsymmetricSecretTypes);\n\n// ============================================================================\n// Key Pair Algorithm Converter\n// ============================================================================\n\n/**\n * Converter for {@link CryptoUtils.KeyStore.KeyPairAlgorithm | key pair algorithm}.\n * @public\n */\nexport const keyPairAlgorithm: Converter<KeyPairAlgorithm> =\n  Converters.enumeratedValue<KeyPairAlgorithm>(allKeyPairAlgorithms);\n\n// ============================================================================\n// JWK Shape Validator\n// ============================================================================\n\n/**\n * In-place shape check for a JSON Web Key. Asserts only that the input is a\n * non-array object whose `kty` discriminator is a string; every other JWK\n * field passes through untouched. This is intentionally **not** a true JWK\n * validator — per-algorithm correctness (RSA `n`/`e`, EC `crv`/`x`/`y`,\n * key-size constraints, etc.) is delegated to `crypto.subtle.importKey` at\n * first use, which is the authoritative checker. The \"shape\" suffix in the\n * name is the warning sign for readers expecting full validation.\n * @remarks\n * Built with `Validators.object` (in-place, non-strict) so unknown JWK fields\n * survive the round-trip; the cast to `FieldValidators<JsonWebKey>` is required\n * only because TypeScript's mapped type demands an entry for every key in\n * `JsonWebKey`. At runtime the `ObjectValidator` only inspects keys present in\n * the field-validators map.\n * @public\n */\nexport const jsonWebKeyShape: Validator<JsonWebKey> = Validators.object<JsonWebKey>({\n  kty: Validators.string\n} as Validation.Classes.FieldValidators<JsonWebKey>);\n\n// ============================================================================\n// Symmetric Secret Entry Converter\n// ============================================================================\n\n/**\n * Converter for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson | symmetric secret entry} in JSON form.\n *\n * @remarks\n * Backwards compatibility with vaults written before asymmetric-keypair\n * support: those entries may lack the `type` discriminator on the wire. To\n * keep the model type honest (`type` is required on\n * {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson}, see its docs),\n * we declare `type` in `optionalFields` so the inner `Converters.object` will\n * accept input without it, then `.map()` injects the default\n * `'encryption-key'` when missing. The output therefore always carries the\n * discriminator and downstream code never sees the legacy missing-type form.\n *\n * @public\n */\nexport const keystoreSymmetricEntryJson: Converter<IKeyStoreSymmetricEntryJson> =\n  Converters.object<IKeyStoreSymmetricEntryJson>(\n    {\n      name: Converters.string,\n      type: keystoreSymmetricSecretType,\n      key: base64String,\n      description: Converters.string,\n      createdAt: Converters.string\n    },\n    {\n      // `type` is optional at the input layer for legacy-vault compatibility;\n      // the .map() below normalizes by injecting the default.\n      optionalFields: ['type', 'description']\n    }\n  ).map((entry) =>\n    succeed<IKeyStoreSymmetricEntryJson>({\n      ...entry,\n      type: entry.type ?? 'encryption-key'\n    })\n  );\n\n// ============================================================================\n// Asymmetric Keypair Entry Converter\n// ============================================================================\n\n/**\n * Converter for {@link CryptoUtils.KeyStore.IKeyStoreAsymmetricEntryJson | asymmetric keypair entry} in JSON form.\n * The `publicKeyJwk` field passes through {@link CryptoUtils.KeyStore.Converters.jsonWebKeyShape | jsonWebKeyShape}\n * (shape check only — see its docs); cryptographic correctness is enforced by\n * `crypto.subtle.importKey` at use.\n * @public\n */\nexport const keystoreAsymmetricEntryJson: Converter<IKeyStoreAsymmetricEntryJson> =\n  Converters.object<IKeyStoreAsymmetricEntryJson>({\n    name: Converters.string,\n    type: keystoreAsymmetricSecretType,\n    id: Converters.string,\n    algorithm: keyPairAlgorithm,\n    publicKeyJwk: jsonWebKeyShape,\n    description: Converters.string.optional(),\n    createdAt: Converters.string\n  });\n\n// ============================================================================\n// Discriminated-Union Entry Converter\n// ============================================================================\n\n/**\n * Discriminated-union converter for any {@link CryptoUtils.KeyStore.IKeyStoreEntryJson | key store entry} in JSON form.\n * Routes by the `type` field: `'asymmetric-keypair'` is parsed by\n * {@link CryptoUtils.KeyStore.Converters.keystoreAsymmetricEntryJson | keystoreAsymmetricEntryJson},\n * anything else (including a missing `type` field for backwards compatibility) by\n * {@link CryptoUtils.KeyStore.Converters.keystoreSymmetricEntryJson | keystoreSymmetricEntryJson}.\n * @public\n */\nexport const keystoreSecretEntryJson: Converter<IKeyStoreEntryJson> = Converters.oneOf<IKeyStoreEntryJson>([\n  keystoreAsymmetricEntryJson,\n  keystoreSymmetricEntryJson\n]);\n\n// ============================================================================\n// Vault Contents Converter\n// ============================================================================\n\n/**\n * Converter for {@link CryptoUtils.KeyStore.IKeyStoreVaultContents | key store vault contents} (decrypted state).\n * @public\n */\nexport const keystoreVaultContents: Converter<IKeyStoreVaultContents> =\n  Converters.object<IKeyStoreVaultContents>({\n    version: keystoreFormat,\n    secrets: Converters.recordOf(keystoreSecretEntryJson)\n  });\n\n// ============================================================================\n// Key Store File Converter\n// ============================================================================\n\n/**\n * Converter for {@link CryptoUtils.KeyStore.IKeyStoreFile | encrypted key store file}.\n * @public\n */\nexport const keystoreFile: Converter<IKeyStoreFile> = Converters.object<IKeyStoreFile>({\n  format: keystoreFormat,\n  algorithm: encryptionAlgorithm,\n  iv: base64String,\n  authTag: base64String,\n  encryptedData: base64String,\n  keyDerivation: pbkdf2KeyDerivationParams\n});\n"]}

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

@@ -0,0 +1,287 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// 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 * as crypto from 'crypto';
+import { captureAsyncResult, captureResult, Converters, fail, succeed } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+import { createEncryptedFile, tryDecryptFile } from '../encryptedFile';
+import { keyPairAlgorithmParams } from '../keyPairAlgorithmParams';
+import * as Constants from '../constants';
+import { jsonWebKeyShape, keyPairAlgorithm } from './converters';
+const envelopeConverter = Converters.object({
+    algorithm: keyPairAlgorithm,
+    jwk: Converters.string
+});
+// 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.
+const PUBLIC_ONLY_USAGES = ['verify', 'encrypt', 'wrapKey'];
+// Safe-filename id production. The keystore mints UUIDv4 handles, which match;
+// arbitrary consumer-supplied ids that could escape the storage directory are
+// rejected rather than silently mangled.
+const SAFE_ID = /^[A-Za-z0-9._-]+$/;
+const FILE_SUFFIX = '.json';
+/**
+ * {@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 class EncryptedFilePrivateKeyStorage {
+    constructor(directory, encryptionKey, cryptoProvider) {
+        /**
+         * `false` — disk persistence round-trips via JWK, which requires extractable
+         * keys.
+         */
+        this.supportsNonExtractable = false;
+        this._directory = directory;
+        // Clone so the instance holds an immutable snapshot — callers that later
+        // reuse or zero their buffer must not be able to mutate our key.
+        this._encryptionKey = Uint8Array.from(encryptionKey);
+        this._cryptoProvider = cryptoProvider;
+    }
+    /**
+     * 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) {
+        const { directory, encryptionKey, cryptoProvider, tree } = params;
+        if (encryptionKey.length !== Constants.AES_256_KEY_SIZE) {
+            return fail(`EncryptedFilePrivateKeyStorage: encryptionKey must be ${Constants.AES_256_KEY_SIZE} bytes, got ${encryptionKey.length}`);
+        }
+        if (tree !== undefined) {
+            return succeed(new EncryptedFilePrivateKeyStorage(tree, encryptionKey, cryptoProvider));
+        }
+        return FileTree.forFilesystem({ mutable: true })
+            .onSuccess((ft) => ft.getDirectory(directory))
+            .withErrorFormat((msg) => `EncryptedFilePrivateKeyStorage: failed to open '${directory}': ${msg}`)
+            .onSuccess((dir) => succeed(new EncryptedFilePrivateKeyStorage(dir, encryptionKey, cryptoProvider)));
+    }
+    /**
+     * 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.
+     */
+    async store(id, key) {
+        return this._validateKeyToStore(id, key).thenOnSuccess(({ fileName, algorithm }) => this._encryptAndWrite(algorithm, key, id, fileName));
+    }
+    /**
+     * Loads the private key stored under `id`, decrypting and re-importing it from
+     * JWK.
+     * @param id - Storage handle.
+     */
+    async load(id) {
+        return this._fileNameFor(id)
+            .onSuccess((fileName) => this._findFile(fileName))
+            .onSuccess((file) => file === undefined ? fail(`key not found: '${id}'`) : succeed(file))
+            .thenOnSuccess((file) => this._decryptEnvelope(file, id))
+            .thenOnSuccess((envelope) => this._importPrivateKey(envelope, id));
+    }
+    /**
+     * 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.
+     */
+    async delete(id) {
+        const fileResult = this._fileNameFor(id).onSuccess((fileName) => this._findFile(fileName).onSuccess((file) => succeed({ fileName, file })));
+        if (fileResult.isFailure()) {
+            return fail(fileResult.message);
+        }
+        if (fileResult.value.file === undefined) {
+            return fail(`key not found: '${id}'`);
+        }
+        /* c8 ignore next 3 - defensive: directory items from read-only adapters lack mutation methods */
+        if (!FileTree.isMutableDirectoryItem(this._directory)) {
+            return fail(`failed to delete private key '${id}': storage directory is not mutable`);
+        }
+        return Promise.resolve(this._directory
+            .deleteChild(fileResult.value.fileName)
+            .withErrorFormat((msg) => `failed to delete private key '${id}': ${msg}`)
+            .onSuccess(() => succeed(id)));
+    }
+    /**
+     * Lists every stored id.
+     */
+    async list() {
+        return Promise.resolve(this._directory.getChildren().onSuccess((children) => {
+            const ids = children
+                .filter((child) => child.type === 'file' && child.name.endsWith(FILE_SUFFIX))
+                .map((child) => child.name.slice(0, -FILE_SUFFIX.length));
+            return succeed(ids);
+        }));
+    }
+    _fileNameFor(id) {
+        if (id === '.' || id === '..' || !SAFE_ID.test(id)) {
+            return fail(`invalid storage id '${id}': must match ${SAFE_ID.source}`);
+        }
+        return succeed(`${id}${FILE_SUFFIX}`);
+    }
+    /**
+     * 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.
+     */
+    _validateKeyToStore(id, key) {
+        return this._fileNameFor(id).onSuccess((fileName) => {
+            if (key.type !== 'private') {
+                return fail(`failed to store private key '${id}': expected a private key, got '${key.type}'`);
+            }
+            return this._algorithmOf(key)
+                .withErrorFormat((msg) => `failed to store private key '${id}': ${msg}`)
+                .onSuccess((algorithm) => succeed({ fileName, algorithm }));
+        });
+    }
+    /**
+     * 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.
+     */
+    async _encryptAndWrite(algorithm, key, id, fileName) {
+        return captureAsyncResult(() => crypto.webcrypto.subtle.exportKey('jwk', key))
+            .withErrorFormat((msg) => `failed to export private key '${id}' to JWK: ${msg}`)
+            .onSuccess((jwk) => succeed({ algorithm, jwk: JSON.stringify(jwk) }))
+            .thenOnSuccess(async (envelope) => (await createEncryptedFile({
+            content: envelope,
+            secretName: id,
+            key: this._encryptionKey,
+            cryptoProvider: this._cryptoProvider
+        })).withErrorFormat((msg) => `failed to encrypt private key '${id}': ${msg}`))
+            .onSuccess((encrypted) => this._writeFile(fileName, JSON.stringify(encrypted)))
+            .onSuccess(() => succeed(id));
+    }
+    _algorithmOf(key) {
+        const alg = key.algorithm;
+        switch (alg.name) {
+            case 'ECDSA':
+            case 'ECDH': {
+                const curve = alg.namedCurve;
+                if (curve !== 'P-256') {
+                    return fail(`unsupported ${alg.name} curve '${curve}' (only P-256 is supported)`);
+                }
+                return succeed(alg.name === 'ECDSA' ? 'ecdsa-p256' : 'ecdh-p256');
+            }
+            case 'RSA-OAEP': {
+                // Only the hash affects the JWK re-import params, so it is the field
+                // that must match; the modulus length is recovered from the key data.
+                const hash = alg.hash.name;
+                if (hash !== 'SHA-256') {
+                    return fail(`unsupported RSA-OAEP hash '${hash}' (only SHA-256 is supported)`);
+                }
+                return succeed('rsa-oaep-2048');
+            }
+            case 'Ed25519':
+                return succeed('ed25519');
+            case 'X25519':
+                return succeed('x25519');
+            default:
+                return fail(`unsupported key algorithm '${alg.name}'`);
+        }
+    }
+    _findFile(fileName) {
+        return this._directory.getChildren().onSuccess((children) => {
+            const found = children.find((child) => child.type === 'file' && child.name === fileName);
+            return succeed(found);
+        });
+    }
+    _writeFile(fileName, text) {
+        return this._findFile(fileName).onSuccess((existing) => {
+            if (existing !== undefined) {
+                /* c8 ignore next 3 - defensive: file items from read-only adapters lack mutation methods */
+                if (!FileTree.isMutableFileItem(existing)) {
+                    return fail(`${existing.absolutePath}: not mutable`);
+                }
+                return existing.setRawContents(text);
+            }
+            /* c8 ignore next 3 - defensive: directory items from read-only adapters lack mutation methods */
+            if (!FileTree.isMutableDirectoryItem(this._directory)) {
+                return fail(`${this._directory.absolutePath}: not mutable`);
+            }
+            return this._directory.createChildFile(fileName, text).onSuccess(() => succeed(text));
+        });
+    }
+    /**
+     * 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`.
+     */
+    async _decryptEnvelope(file, id) {
+        return file
+            .getContents()
+            .thenOnSuccess((json) => tryDecryptFile(json, this._encryptionKey, this._cryptoProvider))
+            .onSuccess((decrypted) => envelopeConverter.convert(decrypted))
+            .withErrorFormat((msg) => `failed to decrypt private key '${id}': ${msg}`);
+    }
+    /**
+     * 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`.
+     */
+    async _importPrivateKey(envelope, id) {
+        const params = keyPairAlgorithmParams[envelope.algorithm];
+        return captureResult(() => JSON.parse(envelope.jwk))
+            .onSuccess((parsed) => jsonWebKeyShape.validate(parsed))
+            .withErrorFormat((msg) => `malformed JWK: ${msg}`)
+            .thenOnSuccess((jwk) => captureAsyncResult(() => crypto.webcrypto.subtle.importKey('jwk', jwk, params.importPublicKey, true, this._importUsagesFor(jwk, params))))
+            .withErrorFormat((msg) => `failed to import private key '${id}': ${msg}`);
+    }
+    /**
+     * 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.
+     */
+    _importUsagesFor(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));
+    }
+}
+//# sourceMappingURL=encryptedFilePrivateKeyStorage.js.map

package/dist/packlets/crypto-utils/keystore/encryptedFilePrivateKeyStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryptedFilePrivateKeyStorage.js","sourceRoot":"","sources":["../../../../src/packlets/crypto-utils/keystore/encryptedFilePrivateKeyStorage.ts"],"names":[],"mappings":"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","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 * as crypto from 'crypto';\nimport {\n  captureAsyncResult,\n  captureResult,\n  Converter,\n  Converters,\n  fail,\n  Result,\n  succeed\n} from '@fgv/ts-utils';\nimport { FileTree, JsonObject } from '@fgv/ts-json-base';\nimport { createEncryptedFile, tryDecryptFile } from '../encryptedFile';\nimport { IKeyPairAlgorithmParams, keyPairAlgorithmParams } from '../keyPairAlgorithmParams';\nimport { ICryptoProvider, KeyPairAlgorithm } from '../model';\nimport * as Constants from '../constants';\nimport { jsonWebKeyShape, keyPairAlgorithm } from './converters';\nimport { IPrivateKeyStorage } from './privateKeyStorage';\n\n/**\n * Parameters for {@link CryptoUtils.KeyStore.EncryptedFilePrivateKeyStorage.create}.\n * @public\n */\nexport interface IEncryptedFilePrivateKeyStorageCreateParams {\n  /**\n   * Filesystem path to the directory that holds the encrypted private-key\n   * files. Used only when {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams.tree}\n   * is omitted (the default `FsTree` backing). The directory must already\n   * exist.\n   */\n  readonly directory: string;\n\n  /**\n   * Raw AES-256-GCM key (32 bytes) used to encrypt each file's JWK content.\n   * Consumer-supplied and decoupled from the keystore's password lifecycle —\n   * derive it however the application sees fit (typically the same\n   * password-derived key material the keystore vault uses).\n   */\n  readonly encryptionKey: Uint8Array;\n\n  /**\n   * {@link CryptoUtils.ICryptoProvider | Crypto provider} used for the\n   * AES-256-GCM encrypt/decrypt of each file's contents.\n   */\n  readonly cryptoProvider: ICryptoProvider;\n\n  /**\n   * Optional {@link FileTree.IFileTreeDirectoryItem | FileTree directory}\n   * override. When supplied it is used as the storage directory directly and\n   * {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams.directory} is ignored —\n   * pass an in-memory tree for tests, or another Node-compatible backend. When\n   * omitted, a mutable `FsTree` rooted at `directory` is used. (This backend is\n   * Node-only — it round-trips keys through `node:crypto` — so a browser file\n   * tree is not a supported target.)\n   */\n  readonly tree?: FileTree.IFileTreeDirectoryItem;\n}\n\n/**\n * Decrypted on-disk envelope for a single stored private key. The JWK is held\n * as a serialized JSON string so the whole envelope is a flat record of\n * strings, which round-trips through {@link CryptoUtils.createEncryptedFile}\n * without ambiguity.\n */\ninterface IStoredPrivateKeyEnvelope {\n  readonly algorithm: KeyPairAlgorithm;\n  readonly jwk: string;\n}\n\nconst envelopeConverter: Converter<IStoredPrivateKeyEnvelope> = Converters.object<IStoredPrivateKeyEnvelope>({\n  algorithm: keyPairAlgorithm,\n  jwk: Converters.string\n});\n\n// WebCrypto key usages that only ever apply to a public key. Filtering these\n// out of the keypair usages yields the usages valid for the private half, which\n// `crypto.subtle.importKey` requires when re-importing a private JWK.\nconst PUBLIC_ONLY_USAGES: ReadonlyArray<KeyUsage> = ['verify', 'encrypt', 'wrapKey'];\n\n// Safe-filename id production. The keystore mints UUIDv4 handles, which match;\n// arbitrary consumer-supplied ids that could escape the storage directory are\n// rejected rather than silently mangled.\nconst SAFE_ID: RegExp = /^[A-Za-z0-9._-]+$/;\n\nconst FILE_SUFFIX: string = '.json';\n\n/**\n * {@link CryptoUtils.KeyStore.IPrivateKeyStorage | IPrivateKeyStorage}\n * implementation that persists each private key as its own AES-256-GCM-encrypted\n * file in a directory. The file content is the key's JWK, encrypted with a\n * consumer-supplied 32-byte key via the supplied\n * {@link CryptoUtils.ICryptoProvider | crypto provider}.\n *\n * `supportsNonExtractable` is `false`: persisting to disk requires exporting the\n * private key to JWK, which only works for `extractable: true` keys. The\n * keystore generates extractable keys when a backend reports `false` here.\n *\n * I/O goes through the {@link FileTree.FileTree | FileTree} abstraction (default\n * `FsTree`), so the same implementation works against an in-memory tree (tests)\n * or any other Node-compatible backend.\n *\n * This backend is **Node-only**: it round-trips private keys through\n * `node:crypto` (`crypto.webcrypto.subtle`), so it is intentionally excluded\n * from the browser entry point. Browser consumers should use\n * `IdbPrivateKeyStorage` from `@fgv/ts-web-extras` instead.\n *\n * Single-process assumption: there is no inter-process locking. Concurrent\n * writers to the same directory may race.\n *\n * @public\n */\nexport class EncryptedFilePrivateKeyStorage implements IPrivateKeyStorage {\n  /**\n   * `false` — disk persistence round-trips via JWK, which requires extractable\n   * keys.\n   */\n  public readonly supportsNonExtractable: false = false;\n\n  private readonly _directory: FileTree.IFileTreeDirectoryItem;\n  private readonly _encryptionKey: Uint8Array;\n  private readonly _cryptoProvider: ICryptoProvider;\n\n  private constructor(\n    directory: FileTree.IFileTreeDirectoryItem,\n    encryptionKey: Uint8Array,\n    cryptoProvider: ICryptoProvider\n  ) {\n    this._directory = directory;\n    // Clone so the instance holds an immutable snapshot — callers that later\n    // reuse or zero their buffer must not be able to mutate our key.\n    this._encryptionKey = Uint8Array.from(encryptionKey);\n    this._cryptoProvider = cryptoProvider;\n  }\n\n  /**\n   * Creates a new {@link CryptoUtils.KeyStore.EncryptedFilePrivateKeyStorage}.\n   * @param params - {@link CryptoUtils.KeyStore.IEncryptedFilePrivateKeyStorageCreateParams}.\n   * @returns `Success` with the new instance, or `Failure` if the encryption\n   * key is the wrong size or the storage directory cannot be opened.\n   */\n  public static create(\n    params: IEncryptedFilePrivateKeyStorageCreateParams\n  ): Result<EncryptedFilePrivateKeyStorage> {\n    const { directory, encryptionKey, cryptoProvider, tree } = params;\n    if (encryptionKey.length !== Constants.AES_256_KEY_SIZE) {\n      return fail(\n        `EncryptedFilePrivateKeyStorage: encryptionKey must be ${Constants.AES_256_KEY_SIZE} bytes, got ${encryptionKey.length}`\n      );\n    }\n    if (tree !== undefined) {\n      return succeed(new EncryptedFilePrivateKeyStorage(tree, encryptionKey, cryptoProvider));\n    }\n    return FileTree.forFilesystem({ mutable: true })\n      .onSuccess((ft) => ft.getDirectory(directory))\n      .withErrorFormat((msg) => `EncryptedFilePrivateKeyStorage: failed to open '${directory}': ${msg}`)\n      .onSuccess((dir) => succeed(new EncryptedFilePrivateKeyStorage(dir, encryptionKey, cryptoProvider)));\n  }\n\n  /**\n   * Stores `key` under `id` as an encrypted JWK file.\n   * @param id - Storage handle. Must be a safe filename token\n   * (`[A-Za-z0-9._-]+`, not `.`/`..`).\n   * @param key - The extractable private `CryptoKey` to persist.\n   */\n  public async store(id: string, key: CryptoKey): Promise<Result<string>> {\n    return this._validateKeyToStore(id, key).thenOnSuccess(({ fileName, algorithm }) =>\n      this._encryptAndWrite(algorithm, key, id, fileName)\n    );\n  }\n\n  /**\n   * Loads the private key stored under `id`, decrypting and re-importing it from\n   * JWK.\n   * @param id - Storage handle.\n   */\n  public async load(id: string): Promise<Result<CryptoKey>> {\n    return this._fileNameFor(id)\n      .onSuccess((fileName) => this._findFile(fileName))\n      .onSuccess((file) =>\n        file === undefined ? fail<FileTree.IFileTreeFileItem>(`key not found: '${id}'`) : succeed(file)\n      )\n      .thenOnSuccess((file) => this._decryptEnvelope(file, id))\n      .thenOnSuccess((envelope) => this._importPrivateKey(envelope, id));\n  }\n\n  /**\n   * Deletes the entry stored under `id`. Missing ids fail (the read path is\n   * keystore-driven and never asks to delete an id it did not store).\n   * @param id - Storage handle.\n   */\n  public async delete(id: string): Promise<Result<string>> {\n    const fileResult = this._fileNameFor(id).onSuccess((fileName) =>\n      this._findFile(fileName).onSuccess((file) => succeed({ fileName, file }))\n    );\n    if (fileResult.isFailure()) {\n      return fail(fileResult.message);\n    }\n    if (fileResult.value.file === undefined) {\n      return fail(`key not found: '${id}'`);\n    }\n    /* c8 ignore next 3 - defensive: directory items from read-only adapters lack mutation methods */\n    if (!FileTree.isMutableDirectoryItem(this._directory)) {\n      return fail(`failed to delete private key '${id}': storage directory is not mutable`);\n    }\n    return Promise.resolve(\n      this._directory\n        .deleteChild(fileResult.value.fileName)\n        .withErrorFormat((msg) => `failed to delete private key '${id}': ${msg}`)\n        .onSuccess(() => succeed(id))\n    );\n  }\n\n  /**\n   * Lists every stored id.\n   */\n  public async list(): Promise<Result<readonly string[]>> {\n    return Promise.resolve(\n      this._directory.getChildren().onSuccess((children) => {\n        const ids = children\n          .filter((child) => child.type === 'file' && child.name.endsWith(FILE_SUFFIX))\n          .map((child) => child.name.slice(0, -FILE_SUFFIX.length));\n        return succeed(ids);\n      })\n    );\n  }\n\n  private _fileNameFor(id: string): Result<string> {\n    if (id === '.' || id === '..' || !SAFE_ID.test(id)) {\n      return fail(`invalid storage id '${id}': must match ${SAFE_ID.source}`);\n    }\n    return succeed(`${id}${FILE_SUFFIX}`);\n  }\n\n  /**\n   * Validates the synchronous preconditions for a store: the id is filename-safe,\n   * the key is actually a private key, and its algorithm is one we support.\n   * Returns the resolved filename and algorithm so the async pipeline can run\n   * without re-deriving them.\n   */\n  private _validateKeyToStore(\n    id: string,\n    key: CryptoKey\n  ): Result<{ fileName: string; algorithm: KeyPairAlgorithm }> {\n    return this._fileNameFor(id).onSuccess((fileName) => {\n      if (key.type !== 'private') {\n        return fail(`failed to store private key '${id}': expected a private key, got '${key.type}'`);\n      }\n      return this._algorithmOf(key)\n        .withErrorFormat((msg) => `failed to store private key '${id}': ${msg}`)\n        .onSuccess((algorithm) => succeed({ fileName, algorithm }));\n    });\n  }\n\n  /**\n   * Exports `key` to JWK, wraps it in the stored envelope, encrypts it with\n   * AES-256-GCM, and writes the resulting file as serialized JSON to `fileName`.\n   * Returns the stored `id` on success.\n   */\n  private async _encryptAndWrite(\n    algorithm: KeyPairAlgorithm,\n    key: CryptoKey,\n    id: string,\n    fileName: string\n  ): Promise<Result<string>> {\n    return captureAsyncResult(() => crypto.webcrypto.subtle.exportKey('jwk', key))\n      .withErrorFormat((msg) => `failed to export private key '${id}' to JWK: ${msg}`)\n      .onSuccess<JsonObject>((jwk) => succeed({ algorithm, jwk: JSON.stringify(jwk) }))\n      .thenOnSuccess(async (envelope) =>\n        (\n          await createEncryptedFile({\n            content: envelope,\n            secretName: id,\n            key: this._encryptionKey,\n            cryptoProvider: this._cryptoProvider\n          })\n        ).withErrorFormat((msg) => `failed to encrypt private key '${id}': ${msg}`)\n      )\n      .onSuccess((encrypted) => this._writeFile(fileName, JSON.stringify(encrypted)))\n      .onSuccess(() => succeed(id));\n  }\n\n  private _algorithmOf(key: CryptoKey): Result<KeyPairAlgorithm> {\n    const alg = key.algorithm;\n    switch (alg.name) {\n      case 'ECDSA':\n      case 'ECDH': {\n        const curve = (alg as EcKeyAlgorithm).namedCurve;\n        if (curve !== 'P-256') {\n          return fail(`unsupported ${alg.name} curve '${curve}' (only P-256 is supported)`);\n        }\n        return succeed(alg.name === 'ECDSA' ? 'ecdsa-p256' : 'ecdh-p256');\n      }\n      case 'RSA-OAEP': {\n        // Only the hash affects the JWK re-import params, so it is the field\n        // that must match; the modulus length is recovered from the key data.\n        const hash = (alg as RsaHashedKeyAlgorithm).hash.name;\n        if (hash !== 'SHA-256') {\n          return fail(`unsupported RSA-OAEP hash '${hash}' (only SHA-256 is supported)`);\n        }\n        return succeed('rsa-oaep-2048');\n      }\n      case 'Ed25519':\n        return succeed('ed25519');\n      case 'X25519':\n        return succeed('x25519');\n      default:\n        return fail(`unsupported key algorithm '${alg.name}'`);\n    }\n  }\n\n  private _findFile(fileName: string): Result<FileTree.IFileTreeFileItem | undefined> {\n    return this._directory.getChildren().onSuccess((children) => {\n      const found = children.find((child) => child.type === 'file' && child.name === fileName);\n      return succeed(found as FileTree.IFileTreeFileItem | undefined);\n    });\n  }\n\n  private _writeFile(fileName: string, text: string): Result<string> {\n    return this._findFile(fileName).onSuccess((existing) => {\n      if (existing !== undefined) {\n        /* c8 ignore next 3 - defensive: file items from read-only adapters lack mutation methods */\n        if (!FileTree.isMutableFileItem(existing)) {\n          return fail(`${existing.absolutePath}: not mutable`);\n        }\n        return existing.setRawContents(text);\n      }\n      /* c8 ignore next 3 - defensive: directory items from read-only adapters lack mutation methods */\n      if (!FileTree.isMutableDirectoryItem(this._directory)) {\n        return fail(`${this._directory.absolutePath}: not mutable`);\n      }\n      return this._directory.createChildFile(fileName, text).onSuccess(() => succeed(text));\n    });\n  }\n\n  /**\n   * Reads `file`, decrypts the AES-256-GCM envelope, and validates it into the\n   * typed `IStoredPrivateKeyEnvelope`. Read, decrypt, and shape failures\n   * all surface as a decrypt failure for `id`.\n   */\n  private async _decryptEnvelope(\n    file: FileTree.IFileTreeFileItem,\n    id: string\n  ): Promise<Result<IStoredPrivateKeyEnvelope>> {\n    return file\n      .getContents()\n      .thenOnSuccess((json) => tryDecryptFile(json, this._encryptionKey, this._cryptoProvider))\n      .onSuccess((decrypted) => envelopeConverter.convert(decrypted))\n      .withErrorFormat((msg) => `failed to decrypt private key '${id}': ${msg}`);\n  }\n\n  /**\n   * Parses and shape-validates the stored JWK, then re-imports it as a private\n   * `CryptoKey` for the envelope's algorithm. The WebCrypto JWK-import algorithm\n   * descriptor is shared between public and private keys for every supported\n   * algorithm, so `IKeyPairAlgorithmParams.importPublicKey` is reused here;\n   * the public/private distinction is carried by the requested `usages`.\n   */\n  private async _importPrivateKey(\n    envelope: IStoredPrivateKeyEnvelope,\n    id: string\n  ): Promise<Result<CryptoKey>> {\n    const params = keyPairAlgorithmParams[envelope.algorithm];\n    return captureResult(() => JSON.parse(envelope.jwk) as unknown)\n      .onSuccess((parsed) => jsonWebKeyShape.validate(parsed))\n      .withErrorFormat((msg) => `malformed JWK: ${msg}`)\n      .thenOnSuccess((jwk) =>\n        captureAsyncResult(() =>\n          crypto.webcrypto.subtle.importKey(\n            'jwk',\n            jwk,\n            params.importPublicKey,\n            true,\n            this._importUsagesFor(jwk, params)\n          )\n        )\n      )\n      .withErrorFormat((msg) => `failed to import private key '${id}': ${msg}`);\n  }\n\n  /**\n   * Computes the key usages to request when re-importing a stored private key.\n   * WebCrypto rejects `importKey` if the requested usages include operations\n   * absent from the JWK's `key_ops`, so a key originally created with a narrower\n   * usage set than the algorithm default (e.g. an ECDH key with only\n   * `deriveBits`) would fail to load against the algorithm-wide defaults.\n   * Intersect the algorithm's private usages with the JWK's recorded `key_ops`\n   * so we request exactly the operations the stored key actually supports;\n   * fall back to the algorithm's private usages when `key_ops` is absent.\n   */\n  private _importUsagesFor(jwk: JsonWebKey, params: IKeyPairAlgorithmParams): KeyUsage[] {\n    const privateUsages = params.keyPairUsages.filter((usage) => !PUBLIC_ONLY_USAGES.includes(usage));\n    const keyOps = jwk.key_ops;\n    if (keyOps === undefined) {\n      return [...privateUsages];\n    }\n    return privateUsages.filter((usage) => keyOps.includes(usage));\n  }\n}\n"]}