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

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

@@ -0,0 +1,74 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyPairAlgorithmParams = void 0;
+/**
+ * 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
+ */
+exports.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/lib/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;AACU,QAAA,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/lib/packlets/crypto-utils/keystore/converters.d.ts

@@ -1,21 +1,83 @@
-import { Converter } from '@fgv/ts-utils';
-import { IKeyStoreFile, IKeyStoreSecretEntryJson, IKeyStoreVaultContents, KeyStoreFormat, KeyStoreSecretType } from './model';
+import { Converter, Validator } from '@fgv/ts-utils';
+import { IKeyStoreAsymmetricEntryJson, IKeyStoreEntryJson, IKeyStoreFile, IKeyStoreSymmetricEntryJson, IKeyStoreVaultContents, KeyPairAlgorithm, KeyStoreAsymmetricSecretType, KeyStoreFormat, KeyStoreSecretType, KeyStoreSymmetricSecretType } from './model';
 /**
  * Converter for {@link CryptoUtils.KeyStore.KeyStoreFormat | key store format} version.
  * @public
  */
 export declare const keystoreFormat: Converter<KeyStoreFormat>;
 /**
- * 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 declare const keystoreSecretType: Converter<KeyStoreSecretType>;
 /**
- * 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'`.
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSymmetricSecretType | symmetric secret type} discriminator.
+ * Accepts only `'encryption-key'` and `'api-key'`.
  * @public
  */
-export declare const keystoreSecretEntryJson: Converter<IKeyStoreSecretEntryJson>;
+export declare const keystoreSymmetricSecretType: Converter<KeyStoreSymmetricSecretType>;
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreAsymmetricSecretType | asymmetric secret type} discriminator.
+ * Accepts only `'asymmetric-keypair'`.
+ * @public
+ */
+export declare const keystoreAsymmetricSecretType: Converter<KeyStoreAsymmetricSecretType>;
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyPairAlgorithm | key pair algorithm}.
+ * @public
+ */
+export declare const keyPairAlgorithm: Converter<KeyPairAlgorithm>;
+/**
+ * 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 declare const jsonWebKeyShape: Validator<JsonWebKey>;
+/**
+ * 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 declare const keystoreSymmetricEntryJson: Converter<IKeyStoreSymmetricEntryJson>;
+/**
+ * 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 declare const keystoreAsymmetricEntryJson: Converter<IKeyStoreAsymmetricEntryJson>;
+/**
+ * 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 declare const keystoreSecretEntryJson: Converter<IKeyStoreEntryJson>;
 /**
  * Converter for {@link CryptoUtils.KeyStore.IKeyStoreVaultContents | key store vault contents} (decrypted state).
  * @public

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

@@ -0,0 +1 @@
+{"version":3,"file":"converters.d.ts","sourceRoot":"","sources":["../../../../src/packlets/crypto-utils/keystore/converters.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,SAAS,EAAmC,SAAS,EAAc,MAAM,eAAe,CAAC;AAElG,OAAO,EAIL,4BAA4B,EAC5B,kBAAkB,EAClB,aAAa,EACb,2BAA2B,EAC3B,sBAAsB,EAEtB,gBAAgB,EAChB,4BAA4B,EAC5B,cAAc,EACd,kBAAkB,EAClB,2BAA2B,EAE5B,MAAM,SAAS,CAAC;AAMjB;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,CAAC,cAAc,CAEnD,CAAC;AAMH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,CAAC,kBAAkB,CACW,CAAC;AAEzE;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,CAAC,2BAA2B,CACW,CAAC;AAE3F;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,SAAS,CAAC,4BAA4B,CACW,CAAC;AAM7F;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,CAAC,gBAAgB,CACW,CAAC;AAMrE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,CAAC,UAAU,CAEE,CAAC;AAMrD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,CAAC,2BAA2B,CAmB3E,CAAC;AAMJ;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,CAAC,4BAA4B,CAS5E,CAAC;AAML;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,CAAC,kBAAkB,CAGhE,CAAC;AAMH;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,CAAC,sBAAsB,CAIhE,CAAC;AAML;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,CAAC,aAAa,CAOhD,CAAC"}

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

@@ -19,7 +19,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.keystoreFile = exports.keystoreVaultContents = exports.keystoreSecretEntryJson = exports.keystoreSecretType = exports.keystoreFormat = void 0;
+exports.keystoreFile = exports.keystoreVaultContents = exports.keystoreSecretEntryJson = exports.keystoreAsymmetricEntryJson = exports.keystoreSymmetricEntryJson = exports.jsonWebKeyShape = exports.keyPairAlgorithm = exports.keystoreAsymmetricSecretType = exports.keystoreSymmetricSecretType = exports.keystoreSecretType = exports.keystoreFormat = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 const converters_1 = require("../converters");
 const model_1 = require("./model");
@@ -34,31 +34,123 @@ exports.keystoreFormat = ts_utils_1.Converters.enumeratedValue([
     model_1.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
  */
 exports.keystoreSecretType = ts_utils_1.Converters.enumeratedValue(model_1.allKeyStoreSecretTypes);
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSymmetricSecretType | symmetric secret type} discriminator.
+ * Accepts only `'encryption-key'` and `'api-key'`.
+ * @public
+ */
+exports.keystoreSymmetricSecretType = ts_utils_1.Converters.enumeratedValue(model_1.allKeyStoreSymmetricSecretTypes);
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreAsymmetricSecretType | asymmetric secret type} discriminator.
+ * Accepts only `'asymmetric-keypair'`.
+ * @public
+ */
+exports.keystoreAsymmetricSecretType = ts_utils_1.Converters.enumeratedValue(model_1.allKeyStoreAsymmetricSecretTypes);
+// ============================================================================
+// Key Pair Algorithm Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyPairAlgorithm | key pair algorithm}.
+ * @public
+ */
+exports.keyPairAlgorithm = ts_utils_1.Converters.enumeratedValue(model_1.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
  */
-exports.keystoreSecretEntryJson = ts_utils_1.Converters.object({
+exports.jsonWebKeyShape = ts_utils_1.Validators.object({
+    kty: ts_utils_1.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
+ */
+exports.keystoreSymmetricEntryJson = ts_utils_1.Converters.object({
     name: ts_utils_1.Converters.string,
-    type: exports.keystoreSecretType,
+    type: exports.keystoreSymmetricSecretType,
     key: converters_1.base64String,
     description: ts_utils_1.Converters.string,
     createdAt: ts_utils_1.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 (0, ts_utils_1.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
+ */
+exports.keystoreAsymmetricEntryJson = ts_utils_1.Converters.object({
+    name: ts_utils_1.Converters.string,
+    type: exports.keystoreAsymmetricSecretType,
+    id: ts_utils_1.Converters.string,
+    algorithm: exports.keyPairAlgorithm,
+    publicKeyJwk: exports.jsonWebKeyShape,
+    description: ts_utils_1.Converters.string.optional(),
+    createdAt: ts_utils_1.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
+ */
+exports.keystoreSecretEntryJson = ts_utils_1.Converters.oneOf([
+    exports.keystoreAsymmetricEntryJson,
+    exports.keystoreSymmetricEntryJson
+]);
+// ============================================================================
 // Vault Contents Converter
 // ============================================================================
 /**
@@ -82,6 +174,6 @@ exports.keystoreFile = ts_utils_1.Converters.object({
     iv: converters_1.base64String,
     authTag: converters_1.base64String,
     encryptedData: converters_1.base64String,
-    keyDerivation: converters_1.keyDerivationParams
+    keyDerivation: converters_1.pbkdf2KeyDerivationParams
 });
 //# sourceMappingURL=converters.js.map

package/lib/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/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"}