@fgv/ts-extras 5.1.0-3 → 5.1.0-31

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

@@ -19,8 +19,12 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SECRET_ITERATIONS = exports.allKeyStoreSecretTypes = exports.MIN_SALT_LENGTH = exports.DEFAULT_KEYSTORE_ITERATIONS = exports.KEYSTORE_FORMAT = void 0;
+exports.DEFAULT_SECRET_ITERATIONS = exports.allKeyStoreSecretTypes = exports.allKeyStoreAsymmetricSecretTypes = exports.allKeyStoreSymmetricSecretTypes = exports.MIN_SALT_LENGTH = exports.DEFAULT_KEYSTORE_ITERATIONS = exports.KEYSTORE_FORMAT = exports.allKeyPairAlgorithms = void 0;
 exports.isKeyStoreFile = isKeyStoreFile;
+// Re-export so consumers can continue to access the algorithm enum via the
+// CryptoUtils.KeyStore namespace alongside the rest of the keystore types.
+var model_1 = require("../model");
+Object.defineProperty(exports, "allKeyPairAlgorithms", { enumerable: true, get: function () { return model_1.allKeyPairAlgorithms; } });
 /**
  * Current format version constant.
  * @public
@@ -37,11 +41,29 @@ exports.DEFAULT_KEYSTORE_ITERATIONS = 600000;
  * @public
  */
 exports.MIN_SALT_LENGTH = 16;
+/**
+ * All valid symmetric secret types.
+ * @public
+ */
+exports.allKeyStoreSymmetricSecretTypes = [
+    'encryption-key',
+    'api-key'
+];
+/**
+ * All valid asymmetric secret types.
+ * @public
+ */
+exports.allKeyStoreAsymmetricSecretTypes = [
+    'asymmetric-keypair'
+];
 /**
  * All valid key store secret types.
  * @public
  */
-exports.allKeyStoreSecretTypes = ['encryption-key', 'api-key'];
+exports.allKeyStoreSecretTypes = [
+    ...exports.allKeyStoreAsymmetricSecretTypes,
+    ...exports.allKeyStoreSymmetricSecretTypes
+];
 /**
  * Default PBKDF2 iterations for secret-level key derivation.
  * Lower than keystore encryption since these are used more frequently.

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

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

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

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

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

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

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

@@ -0,0 +1,22 @@
+"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 });
+//# sourceMappingURL=privateKeyStorage.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"privateKeyStorage.js","sourceRoot":"","sources":["../../../../src/packlets/crypto-utils/keystore/privateKeyStorage.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","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 { Result } from '@fgv/ts-utils';\n\n/**\n * Pluggable backend that persists raw asymmetric private keys outside of the\n * encrypted keystore vault. Concrete implementations live in platform-specific\n * packages (e.g. an IndexedDB-backed implementation in `@fgv/ts-web-extras` or\n * an encrypted-file implementation in `@fgv/ts-chocolate`).\n *\n * The keystore writes storage-first: a private key is always stored here\n * before the corresponding public-key vault entry is committed. Conversely,\n * deletes hit the vault first and then this storage best-effort. As a result,\n * crashes or skipped saves can leave orphaned blobs here; callers are expected\n * to reconcile via {@link CryptoUtils.KeyStore.IPrivateKeyStorage.list} cross-referenced\n * against the keystore's asymmetric entries.\n *\n * @public\n */\nexport interface IPrivateKeyStorage {\n  /**\n   * Whether keys generated for this backend may be marked\n   * `extractable: false`. `true` on backends that store `CryptoKey`\n   * objects directly (e.g. IndexedDB). `false` on backends that must\n   * round-trip via JWK (e.g. encrypted-file backends).\n   */\n  readonly supportsNonExtractable: boolean;\n\n  /**\n   * Stores `key` under `id`. Returns the stored `id` on success so the\n   * call can compose into a Result chain.\n   * @param id - Storage handle to write under.\n   * @param key - The private `CryptoKey` to persist.\n   */\n  store(id: string, key: CryptoKey): Promise<Result<string>>;\n\n  /**\n   * Loads the private key previously stored under `id`.\n   * @param id - Storage handle to look up.\n   */\n  load(id: string): Promise<Result<CryptoKey>>;\n\n  /**\n   * Deletes the entry stored under `id`. Returns the deleted `id` on\n   * success so the call can compose into a Result chain.\n   * @param id - Storage handle to remove.\n   */\n  delete(id: string): Promise<Result<string>>;\n\n  /**\n   * Lists every `id` currently held by the backend. Used by consumers to\n   * garbage-collect orphans left by crashes or aborted sessions; the\n   * keystore itself does not invoke this automatically.\n   */\n  list(): Promise<Result<readonly string[]>>;\n}\n"]}

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

@@ -1,5 +1,5 @@
 import { JsonValue } from '@fgv/ts-json-base';
-import { Result } from '@fgv/ts-utils';
+import { Result, Uuid } from '@fgv/ts-utils';
 import * as Constants from './constants';
 export { Constants };
 /**
@@ -45,28 +45,186 @@ export interface IEncryptionResult {
     readonly encryptedData: Uint8Array;
 }
 /**
- * Supported key derivation functions.
+ * Asymmetric keypair algorithms supported by the crypto provider.
+ * - `'ecdsa-p256'`: ECDSA over the P-256 curve, for signing.
+ * - `'rsa-oaep-2048'`: RSA-OAEP, 2048-bit modulus with SHA-256, for encryption.
+ * - `'ecdh-p256'`: ECDH over the P-256 curve, for key agreement
+ *   (e.g. as the recipient keypair in
+ *   {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes} /
+ *   {@link CryptoUtils.ICryptoProvider.unwrapBytes | unwrapBytes}).
+ * - `'ed25519'`: EdDSA over the Edwards25519 curve, for signing.
+ *   Deterministic — the per-signature nonce is derived from the private key
+ *   and message rather than sampled randomly, eliminating the random-nonce
+ *   reuse risk that ECDSA carries. Distinct from X25519 (key agreement over
+ *   the Montgomery form, Curve25519).
+ * - `'x25519'`: Diffie-Hellman key agreement over the Montgomery form of
+ *   Curve25519. Key-agreement only — use `deriveBits`/`deriveKey` to produce
+ *   a shared secret from one party's private key and the peer's public key.
+ *   Distinct from Ed25519 (which uses the twisted-Edwards form for signing).
  * @public
  */
-export type KeyDerivationFunction = 'pbkdf2';
+export type KeyPairAlgorithm = 'ecdsa-p256' | 'rsa-oaep-2048' | 'ecdh-p256' | 'ed25519' | 'x25519';
 /**
- * Key derivation parameters stored in encrypted files.
- * Allows decryption with password without needing to know the original salt/iterations.
+ * Caller-supplied HKDF parameters that domain-separate one
+ * {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes} call from another.
+ * Two wraps that share recipient but differ on `salt` or `info` derive distinct
+ * wrap keys, so callers should pick values that bind the wrap to its
+ * application context (e.g. a content hash for `salt` and a secret name for
+ * `info`).
+ *
+ * Both fields are required; pass an empty `Uint8Array` if the caller has no
+ * value to bind on a given axis. Silent defaulting would hide protocol
+ * mistakes, so the API does not pick defaults.
+ * @public
+ */
+export interface IWrapBytesOptions {
+    /**
+     * HKDF salt. Domain-separates this wrap from others in different contexts.
+     * Caller picks; common choices include a content hash, document id, channel
+     * id, etc.
+     */
+    readonly salt: Uint8Array;
+    /**
+     * HKDF info. Further binds the derived key to a specific use within the
+     * calling application. Caller picks; common choices include a secret name,
+     * message type, or version tag.
+     */
+    readonly info: Uint8Array;
+}
+/**
+ * Output of {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes}. The
+ * shape is JSON-serializable so it can travel directly over the wire or be
+ * persisted as-is.
  * @public
  */
-export interface IKeyDerivationParams {
+export interface IWrappedBytes {
+    /**
+     * Sender's ephemeral ECDH P-256 public key as a JSON Web Key. The matching
+     * ephemeral private key is dropped after the shared-secret derive.
+     */
+    readonly ephemeralPublicKey: JsonWebKey;
     /**
-     * Key derivation function used.
+     * AES-GCM nonce, base64-encoded. 12 bytes (96 bits) — the standard AES-GCM
+     * nonce length.
      */
-    readonly kdf: KeyDerivationFunction;
+    readonly nonce: string;
     /**
-     * Base64-encoded salt used for key derivation.
+     * AES-GCM ciphertext concatenated with the 16-byte authentication tag,
+     * base64-encoded. Tampering with either the nonce or the ciphertext causes
+     * unwrap to fail GCM authentication.
      */
+    readonly ciphertext: string;
+}
+/**
+ * All valid key pair algorithms.
+ * @public
+ */
+export declare const allKeyPairAlgorithms: ReadonlyArray<KeyPairAlgorithm>;
+/**
+ * Supported key derivation functions.
+ * @public
+ */
+export type KeyDerivationFunction = 'pbkdf2' | 'argon2id';
+/**
+ * PBKDF2 key derivation parameters.
+ * @public
+ */
+export interface IPbkdf2KeyDerivationParams {
+    /** Key derivation function discriminator. */
+    readonly kdf: 'pbkdf2';
+    /** Base64-encoded salt used for key derivation. */
     readonly salt: string;
+    /** Number of iterations used for key derivation. */
+    readonly iterations: number;
+}
+/**
+ * Argon2id key derivation parameters (RFC 9106).
+ * @public
+ */
+export interface IArgon2idKeyDerivationParams {
+    /** Key derivation function discriminator. */
+    readonly kdf: 'argon2id';
+    /** Base64-encoded salt used for key derivation. */
+    readonly salt: string;
+    /** Memory cost in kibibytes. */
+    readonly memoryKiB: number;
+    /** Number of passes (time cost). */
+    readonly iterations: number;
+    /** Degree of parallelism. */
+    readonly parallelism: number;
+}
+/**
+ * Key derivation parameters stored in encrypted files.
+ * Discriminated union on `kdf` field: `'pbkdf2'` or `'argon2id'`.
+ * @public
+ */
+export type IKeyDerivationParams = IPbkdf2KeyDerivationParams | IArgon2idKeyDerivationParams;
+/**
+ * Parameters for Argon2id key derivation (RFC 9106).
+ * All fields are required; fgv does not pick defaults silently.
+ * @public
+ */
+export interface IArgon2idParams {
     /**
-     * Number of iterations used for key derivation.
+     * Memory cost in kibibytes (KiB).
+     * OWASP 2023 minimum: 19456 (19 MiB). Stronger: 65536 (64 MiB).
+     * Constraint: \>= 8.
+     */
+    readonly memoryKiB: number;
+    /**
+     * Number of passes (iterations / time cost).
+     * OWASP 2023 minimum: 2. Range: \>= 1.
      */
     readonly iterations: number;
+    /**
+     * Degree of parallelism (threads).
+     * Note: WASM-based implementations compute sequentially regardless of this value,
+     * but the value is wired into the algorithm and AFFECTS the output hash bytes.
+     * Callers must use the same parallelism value consistently for a given secret.
+     * Range: 1–255.
+     */
+    readonly parallelism: number;
+    /**
+     * Number of output bytes (hash length).
+     * Typical values: 16 (128-bit), 32 (256-bit, AES-256 key), 64 (512-bit).
+     * Constraint: \>= 4.
+     */
+    readonly outputBytes: number;
+}
+/**
+ * Recommended OWASP 2023 minimum Argon2id parameters.
+ * Suitable for recovery-row key derivation (high-entropy inputs).
+ * @public
+ */
+export declare const ARGON2ID_OWASP_MIN: IArgon2idParams;
+/**
+ * Stronger Argon2id parameters suitable for user-typed passphrases.
+ * @public
+ */
+export declare const ARGON2ID_PASSPHRASE: IArgon2idParams;
+/**
+ * Argon2id key derivation provider (RFC 9106).
+ *
+ * Implementations are in separate packages to avoid WASM bundle costs for
+ * consumers who don't need Argon2id:
+ * - Node: `@fgv/ts-extras-argon2` (`NodeArgon2Provider`)
+ * - Browser: `@fgv/ts-web-extras-argon2` (`BrowserArgon2Provider`)
+ *
+ * @public
+ */
+export interface IArgon2idProvider {
+    /**
+     * Derives key material from a password using Argon2id (RFC 9106 §3.1).
+     *
+     * Returns the raw derived bytes as a `Uint8Array`. Both Node and browser
+     * implementations produce bit-identical output for identical inputs.
+     *
+     * @param password - Password or passphrase. Accepts string (UTF-8) or raw bytes.
+     * @param salt - Salt bytes. Must be random and unique per credential (\>= 16 bytes recommended).
+     * @param params - Argon2id parameters. Use `ARGON2ID_OWASP_MIN` as a starting point.
+     * @returns Success with derived bytes, Failure with error context.
+     */
+    argon2id(password: Uint8Array | string, salt: Uint8Array, params: IArgon2idParams): Promise<Result<Uint8Array>>;
 }
 /**
  * Generic encrypted file format.
@@ -145,12 +303,27 @@ export interface ICryptoProvider {
      * @returns Success with derived 32-byte key, or Failure with error
      */
     deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns Success with hex-encoded hash string, or Failure with error
+     */
+    sha256(data: string): Promise<Result<string>>;
     /**
      * Generates cryptographically secure random bytes.
      * @param length - Number of bytes to generate
      * @returns Success with random bytes, or Failure with error
      */
     generateRandomBytes(length: number): Result<Uint8Array>;
+    /**
+     * Generates a cryptographically random UUIDv4 using the provider's
+     * underlying source of randomness. The default Node and browser
+     * implementations delegate to `globalThis.crypto.randomUUID`;
+     * deterministic providers (e.g. test stubs) may override to produce
+     * reproducible values.
+     * @returns Success with a canonical UUID, or Failure with error.
+     */
+    generateUuid(): Result<Uuid>;
     /**
      * Encodes binary data to base64 string.
      * @param data - Binary data to encode
@@ -163,6 +336,161 @@ export interface ICryptoProvider {
      * @returns Success with decoded bytes, or Failure if invalid base64
      */
     fromBase64(base64: string): Result<Uint8Array>;
+    /**
+     * Generates a new asymmetric keypair for the requested algorithm.
+     * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} to use.
+     * @param extractable - Whether the resulting `CryptoKey` objects may be exported.
+     * Set `false` on backends that store `CryptoKey` references directly (e.g.
+     * IndexedDB). Set `true` when the private key must round-trip through JWK or
+     * PKCS#8 (e.g. encrypted-file backends).
+     * @returns Success with the generated `CryptoKeyPair`, or Failure with error context.
+     */
+    generateKeyPair(algorithm: KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;
+    /**
+     * Exports the public half of a keypair as a JSON Web Key.
+     * @param publicKey - The public `CryptoKey` to export. Must be an `extractable`
+     * key generated for an asymmetric algorithm.
+     * @returns Success with the JWK, or Failure with error context.
+     */
+    exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>>;
+    /**
+     * Re-imports a public-key JWK as a `CryptoKey` usable for verification or
+     * encryption (depending on algorithm).
+     * @param jwk - The JSON Web Key produced by {@link CryptoUtils.ICryptoProvider.exportPublicKeyJwk | exportPublicKeyJwk}.
+     * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} the
+     * key was generated for. Determines the import parameters and key usages.
+     * @returns Success with the imported public `CryptoKey`, or Failure with error context.
+     */
+    importPublicKeyJwk(jwk: JsonWebKey, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>>;
+    /**
+     * Exports a public `CryptoKey` as a DER-encoded SPKI (SubjectPublicKeyInfo) blob.
+     * SPKI is the standard algorithm-agnostic format for public key storage and transport.
+     * @param publicKey - The `CryptoKey` to export. Must have `key.type === 'public'`.
+     * @returns `Success` with the raw SPKI bytes, or `Failure` with error context.
+     */
+    exportPublicKeySpki(publicKey: CryptoKey): Promise<Result<Uint8Array>>;
+    /**
+     * Imports a public key from a DER-encoded SPKI blob.
+     * @param spkiBytes - The raw SPKI bytes produced by {@link CryptoUtils.ICryptoProvider.exportPublicKeySpki | exportPublicKeySpki}.
+     * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} the key was generated for.
+     * @returns `Success` with the imported public `CryptoKey`, or `Failure` with error context.
+     */
+    importPublicKeySpki(spkiBytes: Uint8Array, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>>;
+    /**
+     * Wraps `plaintext` for delivery to the holder of the private key paired
+     * with `recipientPublicKey`. Uses ECIES with ECDH P-256, HKDF-SHA256, and
+     * AES-GCM-256.
+     *
+     * Generates a fresh ephemeral keypair per call; the ephemeral private key
+     * is discarded after the shared-secret derive. Only the recipient (with the
+     * matching private key) and the same HKDF parameters can recover
+     * `plaintext`.
+     *
+     * Empty `plaintext` is permitted; the resulting wrap contains only the
+     * 16-byte GCM authentication tag and round-trips back to an empty
+     * `Uint8Array`.
+     * @param plaintext - The bytes to wrap. Any length supported by AES-GCM
+     * (in practice, well below 2^39 - 256 bits).
+     * @param recipientPublicKey - The recipient's ECDH P-256 public `CryptoKey`.
+     * Must have algorithm name `'ECDH'` and named curve `'P-256'`; mismatched
+     * algorithm or curve yields a `Failure` with error context.
+     * @param options - HKDF parameters; see {@link CryptoUtils.IWrapBytesOptions | IWrapBytesOptions}.
+     * @returns `Success` with the wrapped payload, or `Failure` with error context.
+     */
+    wrapBytes(plaintext: Uint8Array, recipientPublicKey: CryptoKey, options: IWrapBytesOptions): Promise<Result<IWrappedBytes>>;
+    /**
+     * Inverse of {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes}.
+     * Recovers the original `plaintext` from a wrapped payload using the
+     * recipient's private key.
+     *
+     * Returns a `Failure` (never throws) on any of:
+     * - Tampered nonce or ciphertext (AES-GCM authentication fails)
+     * - Wrong private key (different shared secret derives a different wrap key)
+     * - Wrong HKDF parameters (different wrap key)
+     * - Malformed `ephemeralPublicKey` JWK
+     * - Malformed base64 in `nonce` or `ciphertext`
+     * @param wrapped - The wrapped payload produced by `wrapBytes`.
+     * @param recipientPrivateKey - The recipient's ECDH P-256 private
+     * `CryptoKey`. Must have algorithm name `'ECDH'` and named curve `'P-256'`,
+     * and key usages including `'deriveKey'` or `'deriveBits'`.
+     * @param options - The same HKDF parameters used at wrap time.
+     * @returns `Success` with the original `plaintext`, or `Failure` with error context.
+     */
+    unwrapBytes(wrapped: IWrappedBytes, recipientPrivateKey: CryptoKey, options: IWrapBytesOptions): Promise<Result<Uint8Array>>;
+    /**
+     * Signs `data` with `privateKey` using the algorithm inferred from the key.
+     * Delegates to `crypto.subtle.sign`; the algorithm is derived from
+     * `privateKey.algorithm.name` — ECDSA keys are augmented with
+     * `hash: 'SHA-256'` at sign time (the hash is not stored in the key);
+     * all other algorithm names are passed through as-is.
+     * Intended for Ed25519 and ECDSA-P256 asymmetric private keys; for
+     * HMAC-SHA256 authentication codes use {@link ICryptoProvider.hmacSha256} instead.
+     * @param privateKey - A `CryptoKey` with `'sign'` usage (e.g. generated by
+     * {@link CryptoUtils.ICryptoProvider.generateKeyPair | generateKeyPair} with
+     * `'ecdsa-p256'` or `'ed25519'`).
+     * @param data - The bytes to sign.
+     * @returns `Success` with the raw signature bytes, or `Failure` with error context.
+     */
+    sign(privateKey: CryptoKey, data: Uint8Array): Promise<Result<Uint8Array>>;
+    /**
+     * Verifies a signature produced by {@link ICryptoProvider.sign}.
+     * Delegates to `crypto.subtle.verify`; the algorithm is derived from
+     * `publicKey.algorithm.name` — ECDSA keys are augmented with
+     * `hash: 'SHA-256'`; all other algorithm names are passed through as-is.
+     * Intended for Ed25519 and ECDSA-P256 asymmetric public keys; for
+     * HMAC-SHA256 verification use {@link ICryptoProvider.verifyHmacSha256} instead.
+     * @param publicKey - A `CryptoKey` with `'verify'` usage (e.g. the public
+     * half of a keypair generated by
+     * {@link CryptoUtils.ICryptoProvider.generateKeyPair | generateKeyPair} with
+     * `'ecdsa-p256'` or `'ed25519'`).
+     * @param signature - The raw signature bytes produced by `sign`.
+     * @param data - The original data that was signed.
+     * @returns `Success` with `true` if the signature is valid, `false` if it is
+     * not, or `Failure` with error context if the operation itself failed.
+     */
+    verify(publicKey: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean>>;
+    /**
+     * Compares two byte arrays in constant time.
+     *
+     * The comparison visits all bytes of `a` and `b` regardless of where they
+     * diverge, accumulating XOR differences with bitwise-OR. No early-return is
+     * possible once the length check passes, making timing independent of the
+     * byte values. This prevents timing side-channels when comparing MAC outputs,
+     * signed-token bytes, or any secret-derived byte sequences.
+     *
+     * Returns `false` immediately (before the loop) when `a.length !== b.length`;
+     * the length mismatch itself is not secret in normal use.
+     * @param a - First byte array.
+     * @param b - Second byte array.
+     * @returns `true` if the arrays have the same length and identical contents,
+     * `false` otherwise.
+     */
+    timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+    /**
+     * Computes an HMAC-SHA256 authentication code for `data` using `key`.
+     *
+     * The key must be a `CryptoKey` with `'sign'` usage and algorithm name
+     * `'HMAC'` (e.g. derived via PBKDF2 or imported with
+     * `crypto.subtle.importKey`). Use {@link ICryptoProvider.verifyHmacSha256}
+     * for constant-time verification of the output.
+     * @param key - An HMAC `CryptoKey` with `'sign'` usage.
+     * @param data - The bytes to authenticate.
+     * @returns `Success` with the 32-byte MAC, or `Failure` with error context.
+     */
+    hmacSha256(key: CryptoKey, data: Uint8Array): Promise<Result<Uint8Array>>;
+    /**
+     * Verifies an HMAC-SHA256 authentication code in constant time.
+     *
+     * Computes the expected MAC over `data` with `key`, then compares it to
+     * `signature` using {@link ICryptoProvider.timingSafeEqual} so that
+     * mismatches do not leak information through timing.
+     * @param key - An HMAC `CryptoKey` with `'sign'` usage.
+     * @param signature - The MAC bytes to verify (typically 32 bytes).
+     * @param data - The original data that was authenticated.
+     * @returns `Success` with `true` if the MAC is valid, `false` if it is not,
+     * or `Failure` with error context if the MAC computation itself failed.
+     */
+    verifyHmacSha256(key: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean>>;
 }
 /**
  * High-level interface for encrypting JSON content by secret name.

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

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

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

@@ -52,10 +52,42 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Constants = void 0;
+exports.ARGON2ID_PASSPHRASE = exports.ARGON2ID_OWASP_MIN = exports.allKeyPairAlgorithms = exports.Constants = void 0;
 exports.isEncryptedFile = isEncryptedFile;
 const Constants = __importStar(require("./constants"));
 exports.Constants = Constants;
+/**
+ * All valid key pair algorithms.
+ * @public
+ */
+exports.allKeyPairAlgorithms = [
+    'ecdsa-p256',
+    'rsa-oaep-2048',
+    'ecdh-p256',
+    'ed25519',
+    'x25519'
+];
+/**
+ * Recommended OWASP 2023 minimum Argon2id parameters.
+ * Suitable for recovery-row key derivation (high-entropy inputs).
+ * @public
+ */
+exports.ARGON2ID_OWASP_MIN = {
+    memoryKiB: 19456,
+    iterations: 2,
+    parallelism: 1,
+    outputBytes: 32
+};
+/**
+ * Stronger Argon2id parameters suitable for user-typed passphrases.
+ * @public
+ */
+exports.ARGON2ID_PASSPHRASE = {
+    memoryKiB: 65536,
+    iterations: 3,
+    parallelism: 1,
+    outputBytes: 32
+};
 // ============================================================================
 // Detection Helper
 // ============================================================================