@fgv/ts-extras 5.0.2 → 5.1.0-1

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

@@ -0,0 +1,91 @@
+"use strict";
+// Copyright (c) 2024 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.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryDecryptFile = exports.toBase64 = exports.fromBase64 = exports.decryptFile = exports.createEncryptedFile = exports.DirectEncryptionProvider = exports.Converters = exports.KeyStore = exports.GCM_IV_SIZE = exports.GCM_AUTH_TAG_SIZE = exports.ENCRYPTED_FILE_FORMAT = exports.DEFAULT_ALGORITHM = exports.AES_256_KEY_SIZE = void 0;
+/**
+ * Crypto utilities for encrypted file handling and key management (browser version).
+ * Note: For browser crypto provider, use \@fgv/ts-web-extras.
+ * @packageDocumentation
+ */
+// Re-export all types from model
+__exportStar(require("./model"), exports);
+// Constants
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "AES_256_KEY_SIZE", { enumerable: true, get: function () { return constants_1.AES_256_KEY_SIZE; } });
+Object.defineProperty(exports, "DEFAULT_ALGORITHM", { enumerable: true, get: function () { return constants_1.DEFAULT_ALGORITHM; } });
+Object.defineProperty(exports, "ENCRYPTED_FILE_FORMAT", { enumerable: true, get: function () { return constants_1.ENCRYPTED_FILE_FORMAT; } });
+Object.defineProperty(exports, "GCM_AUTH_TAG_SIZE", { enumerable: true, get: function () { return constants_1.GCM_AUTH_TAG_SIZE; } });
+Object.defineProperty(exports, "GCM_IV_SIZE", { enumerable: true, get: function () { return constants_1.GCM_IV_SIZE; } });
+// KeyStore namespace
+const KeyStore = __importStar(require("./keystore"));
+exports.KeyStore = KeyStore;
+// Converters namespace
+const Converters = __importStar(require("./converters"));
+exports.Converters = Converters;
+// Direct encryption provider
+var directEncryptionProvider_1 = require("./directEncryptionProvider");
+Object.defineProperty(exports, "DirectEncryptionProvider", { enumerable: true, get: function () { return directEncryptionProvider_1.DirectEncryptionProvider; } });
+// Note: NodeCryptoProvider is NOT exported in browser version
+// Use BrowserCryptoProvider from @fgv/ts-web-extras instead
+// Encrypted file helpers
+var encryptedFile_1 = require("./encryptedFile");
+Object.defineProperty(exports, "createEncryptedFile", { enumerable: true, get: function () { return encryptedFile_1.createEncryptedFile; } });
+Object.defineProperty(exports, "decryptFile", { enumerable: true, get: function () { return encryptedFile_1.decryptFile; } });
+Object.defineProperty(exports, "fromBase64", { enumerable: true, get: function () { return encryptedFile_1.fromBase64; } });
+Object.defineProperty(exports, "toBase64", { enumerable: true, get: function () { return encryptedFile_1.toBase64; } });
+Object.defineProperty(exports, "tryDecryptFile", { enumerable: true, get: function () { return encryptedFile_1.tryDecryptFile; } });
+//# sourceMappingURL=index.browser.js.map

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

@@ -0,0 +1,15 @@
+/**
+ * Crypto utilities for encrypted file handling and key management.
+ * @packageDocumentation
+ */
+export * from './model';
+import * as Constants from './constants';
+export { Constants };
+import * as KeyStore from './keystore';
+export { KeyStore };
+import * as Converters from './converters';
+export { Converters };
+export { DirectEncryptionProvider, IDirectEncryptionProviderParams } from './directEncryptionProvider';
+export { NodeCryptoProvider, nodeCryptoProvider } from './nodeCryptoProvider';
+export { createEncryptedFile, decryptFile, fromBase64, ICreateEncryptedFileParams, toBase64, tryDecryptFile } from './encryptedFile';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,88 @@
+"use strict";
+// Copyright (c) 2024 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.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryDecryptFile = exports.toBase64 = exports.fromBase64 = exports.decryptFile = exports.createEncryptedFile = exports.nodeCryptoProvider = exports.NodeCryptoProvider = exports.DirectEncryptionProvider = exports.Converters = exports.KeyStore = exports.Constants = void 0;
+/**
+ * Crypto utilities for encrypted file handling and key management.
+ * @packageDocumentation
+ */
+// Re-export all types from model
+__exportStar(require("./model"), exports);
+// Constants
+const Constants = __importStar(require("./constants"));
+exports.Constants = Constants;
+// KeyStore namespace
+const KeyStore = __importStar(require("./keystore"));
+exports.KeyStore = KeyStore;
+// Converters namespace
+const Converters = __importStar(require("./converters"));
+exports.Converters = Converters;
+// Direct encryption provider
+var directEncryptionProvider_1 = require("./directEncryptionProvider");
+Object.defineProperty(exports, "DirectEncryptionProvider", { enumerable: true, get: function () { return directEncryptionProvider_1.DirectEncryptionProvider; } });
+// Node.js crypto provider (Node.js environment only)
+var nodeCryptoProvider_1 = require("./nodeCryptoProvider");
+Object.defineProperty(exports, "NodeCryptoProvider", { enumerable: true, get: function () { return nodeCryptoProvider_1.NodeCryptoProvider; } });
+Object.defineProperty(exports, "nodeCryptoProvider", { enumerable: true, get: function () { return nodeCryptoProvider_1.nodeCryptoProvider; } });
+// Encrypted file helpers
+var encryptedFile_1 = require("./encryptedFile");
+Object.defineProperty(exports, "createEncryptedFile", { enumerable: true, get: function () { return encryptedFile_1.createEncryptedFile; } });
+Object.defineProperty(exports, "decryptFile", { enumerable: true, get: function () { return encryptedFile_1.decryptFile; } });
+Object.defineProperty(exports, "fromBase64", { enumerable: true, get: function () { return encryptedFile_1.fromBase64; } });
+Object.defineProperty(exports, "toBase64", { enumerable: true, get: function () { return encryptedFile_1.toBase64; } });
+Object.defineProperty(exports, "tryDecryptFile", { enumerable: true, get: function () { return encryptedFile_1.tryDecryptFile; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,29 @@
+import { Converter } from '@fgv/ts-utils';
+import { IKeyStoreFile, IKeyStoreSecretEntryJson, IKeyStoreVaultContents, KeyStoreFormat, KeyStoreSecretType } 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.
+ * @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'`.
+ * @public
+ */
+export declare const keystoreSecretEntryJson: Converter<IKeyStoreSecretEntryJson>;
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreVaultContents | key store vault contents} (decrypted state).
+ * @public
+ */
+export declare const keystoreVaultContents: Converter<IKeyStoreVaultContents>;
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreFile | encrypted key store file}.
+ * @public
+ */
+export declare const keystoreFile: Converter<IKeyStoreFile>;
+//# sourceMappingURL=converters.d.ts.map

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

@@ -0,0 +1,87 @@
+"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.keystoreFile = exports.keystoreVaultContents = exports.keystoreSecretEntryJson = exports.keystoreSecretType = exports.keystoreFormat = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const converters_1 = require("../converters");
+const model_1 = require("./model");
+// ============================================================================
+// Key Store Format Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreFormat | key store format} version.
+ * @public
+ */
+exports.keystoreFormat = ts_utils_1.Converters.enumeratedValue([
+    model_1.KEYSTORE_FORMAT
+]);
+// ============================================================================
+// Secret Type Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSecretType | key store secret type} discriminator.
+ * @public
+ */
+exports.keystoreSecretType = ts_utils_1.Converters.enumeratedValue(model_1.allKeyStoreSecretTypes);
+// ============================================================================
+// Secret Entry Converters
+// ============================================================================
+/**
+ * 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'`.
+ * @public
+ */
+exports.keystoreSecretEntryJson = ts_utils_1.Converters.object({
+    name: ts_utils_1.Converters.string,
+    type: exports.keystoreSecretType,
+    key: converters_1.base64String,
+    description: ts_utils_1.Converters.string,
+    createdAt: ts_utils_1.Converters.string
+}, {
+    optionalFields: ['type', 'description']
+});
+// ============================================================================
+// Vault Contents Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreVaultContents | key store vault contents} (decrypted state).
+ * @public
+ */
+exports.keystoreVaultContents = ts_utils_1.Converters.object({
+    version: exports.keystoreFormat,
+    secrets: ts_utils_1.Converters.recordOf(exports.keystoreSecretEntryJson)
+});
+// ============================================================================
+// Key Store File Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreFile | encrypted key store file}.
+ * @public
+ */
+exports.keystoreFile = ts_utils_1.Converters.object({
+    format: exports.keystoreFormat,
+    algorithm: converters_1.encryptionAlgorithm,
+    iv: converters_1.base64String,
+    authTag: converters_1.base64String,
+    encryptedData: converters_1.base64String,
+    keyDerivation: converters_1.keyDerivationParams
+});
+//# sourceMappingURL=converters.js.map

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

@@ -0,0 +1,9 @@
+/**
+ * Key store module for password-protected secret management.
+ * @packageDocumentation
+ */
+export * from './model';
+import * as Converters from './converters';
+export { Converters };
+export { KeyStore } from './keyStore';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,71 @@
+"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.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyStore = exports.Converters = void 0;
+/**
+ * Key store module for password-protected secret management.
+ * @packageDocumentation
+ */
+// Types and interfaces
+__exportStar(require("./model"), exports);
+// Converters namespace
+const Converters = __importStar(require("./converters"));
+exports.Converters = Converters;
+// Key store class
+var keyStore_1 = require("./keyStore");
+Object.defineProperty(exports, "KeyStore", { enumerable: true, get: function () { return keyStore_1.KeyStore; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,239 @@
+import { JsonValue } from '@fgv/ts-json-base';
+import { Result } from '@fgv/ts-utils';
+import { ICryptoProvider, IEncryptedFile, IEncryptionConfig, IEncryptionProvider, SecretProvider } from '../model';
+import { IAddSecretFromPasswordOptions, IAddSecretFromPasswordResult, IAddSecretOptions, IAddSecretResult, IImportSecretOptions, IKeyStoreCreateParams, IKeyStoreFile, IKeyStoreOpenParams, IKeyStoreSecretEntry, KeyStoreLockState, KeyStoreSecretType } from './model';
+/**
+ * Password-protected key store for managing encryption secrets.
+ *
+ * The KeyStore provides a secure vault for storing named encryption keys.
+ * The vault is encrypted at rest using a master password via PBKDF2 key derivation.
+ *
+ * @example
+ * ```typescript
+ * // Create new key store
+ * const keystore = KeyStore.create({ cryptoProvider: nodeCryptoProvider }).orThrow();
+ * await keystore.initialize('master-password');
+ *
+ * // Add secrets
+ * await keystore.addSecret('my-key', { description: 'Production key' });
+ *
+ * // Save to file
+ * const fileContent = await keystore.save();
+ *
+ * // Later: Open existing key store
+ * const keystore2 = KeyStore.open({
+ *   cryptoProvider: nodeCryptoProvider,
+ *   keystoreFile: fileContent.value
+ * }).orThrow();
+ * await keystore2.unlock('master-password');
+ *
+ * // Use as secret provider for encrypted file loading
+ * const encryptionConfig = keystore2.getEncryptionConfig().orThrow();
+ * ```
+ *
+ * @public
+ */
+export declare class KeyStore implements IEncryptionProvider {
+    private readonly _cryptoProvider;
+    private readonly _iterations;
+    private _keystoreFile;
+    private _salt;
+    private _secrets;
+    private _state;
+    private _dirty;
+    private _isNew;
+    private constructor();
+    /**
+     * Creates a new, empty key store.
+     * Call `initialize(password)` to set the master password.
+     * @param params - Creation parameters
+     * @returns Success with new KeyStore instance, or Failure if parameters invalid
+     * @public
+     */
+    static create(params: IKeyStoreCreateParams): Result<KeyStore>;
+    /**
+     * Opens an existing encrypted key store.
+     * Call `unlock(password)` to decrypt and access secrets.
+     * @param params - Open parameters including the encrypted file
+     * @returns Success with KeyStore instance, or Failure if file format invalid
+     * @public
+     */
+    static open(params: IKeyStoreOpenParams): Result<KeyStore>;
+    /**
+     * Initializes a new key store with the master password.
+     * Generates a random salt for key derivation.
+     * Only valid for newly created (not opened) key stores.
+     * @param password - The master password
+     * @returns Success with this instance when initialized, Failure if already initialized or opened
+     * @public
+     */
+    initialize(password: string): Promise<Result<KeyStore>>;
+    /**
+     * Unlocks an existing key store with the master password.
+     * Decrypts the vault and loads secrets into memory.
+     * @param password - The master password
+     * @returns Success with this instance when unlocked, Failure if password incorrect
+     * @public
+     */
+    unlock(password: string): Promise<Result<KeyStore>>;
+    /**
+     * Locks the key store, clearing all secrets from memory.
+     * @param force - If true, discards unsaved changes
+     * @returns Success when locked, Failure if unsaved changes and !force
+     * @public
+     */
+    lock(force?: boolean): Result<KeyStore>;
+    /**
+     * Checks if the key store is unlocked.
+     * @public
+     */
+    get isUnlocked(): boolean;
+    /**
+     * Checks if there are unsaved changes.
+     * @public
+     */
+    get isDirty(): boolean;
+    /**
+     * Whether this is a newly created key store (not opened from a file).
+     * A new key store must be initialized with a password before use.
+     * An opened key store must be unlocked with the existing password.
+     * @public
+     */
+    get isNew(): boolean;
+    /**
+     * Gets the current lock state.
+     * @public
+     */
+    get state(): KeyStoreLockState;
+    /**
+     * Gets the crypto provider used by this key store.
+     * Available regardless of lock state.
+     * @public
+     */
+    get cryptoProvider(): ICryptoProvider;
+    /**
+     * Lists all secret names in the key store.
+     * @returns Success with array of secret names, Failure if locked
+     * @public
+     */
+    listSecrets(): Result<readonly string[]>;
+    /**
+     * Gets a secret by name.
+     * @param name - Name of the secret
+     * @returns Success with secret entry, Failure if not found or locked
+     * @public
+     */
+    getSecret(name: string): Result<IKeyStoreSecretEntry>;
+    /**
+     * Checks if a secret exists.
+     * @param name - Name of the secret
+     * @returns Success with boolean, Failure if locked
+     * @public
+     */
+    hasSecret(name: string): Result<boolean>;
+    /**
+     * Adds a new secret with a randomly generated key.
+     * @param name - Unique name for the secret
+     * @param options - Optional description
+     * @returns Success with the generated entry, Failure if locked or name invalid
+     * @public
+     */
+    addSecret(name: string, options?: IAddSecretOptions): Promise<Result<IAddSecretResult>>;
+    /**
+     * Imports an existing secret key.
+     * @param name - Unique name for the secret
+     * @param key - The 32-byte AES-256 key
+     * @param options - Optional description, whether to replace existing
+     * @returns Success with entry, Failure if locked, key invalid, or exists and !replace
+     * @public
+     */
+    importSecret(name: string, key: Uint8Array, options?: IImportSecretOptions): Result<IAddSecretResult>;
+    /**
+     * Adds a secret derived from a password using PBKDF2.
+     *
+     * Generates a random salt, derives a 32-byte AES-256 key from the password,
+     * and stores it in the vault. Returns the key derivation parameters so they
+     * can be stored alongside encrypted files, enabling decryption with just the
+     * password (without unlocking the keystore).
+     *
+     * @param name - Unique name for the secret
+     * @param password - Password to derive the key from
+     * @param options - Optional description, iterations, replace flag
+     * @returns Success with entry and keyDerivation params, Failure if locked or invalid
+     * @public
+     */
+    addSecretFromPassword(name: string, password: string, options?: IAddSecretFromPasswordOptions): Promise<Result<IAddSecretFromPasswordResult>>;
+    /**
+     * Removes a secret by name.
+     * @param name - Name of the secret to remove
+     * @returns Success with removed entry, Failure if not found or locked
+     * @public
+     */
+    removeSecret(name: string): Result<IKeyStoreSecretEntry>;
+    /**
+     * Imports an API key string into the vault.
+     * The string is UTF-8 encoded and stored with type `'api-key'`.
+     * @param name - Unique name for the secret
+     * @param apiKey - The API key string
+     * @param options - Optional description, whether to replace existing
+     * @returns Success with entry, Failure if locked, empty, or exists and !replace
+     * @public
+     */
+    importApiKey(name: string, apiKey: string, options?: IImportSecretOptions): Result<IAddSecretResult>;
+    /**
+     * Retrieves an API key string by name.
+     * Only works for secrets with type `'api-key'`.
+     * @param name - Name of the secret
+     * @returns Success with the API key string, Failure if not found, locked, or wrong type
+     * @public
+     */
+    getApiKey(name: string): Result<string>;
+    /**
+     * Lists secret names filtered by type.
+     * @param type - The secret type to filter by
+     * @returns Success with array of matching secret names, Failure if locked
+     * @public
+     */
+    listSecretsByType(type: KeyStoreSecretType): Result<readonly string[]>;
+    /**
+     * Renames a secret.
+     * @param oldName - Current name
+     * @param newName - New name
+     * @returns Success with updated entry, Failure if source not found, target exists, or locked
+     * @public
+     */
+    renameSecret(oldName: string, newName: string): Result<IKeyStoreSecretEntry>;
+    /**
+     * Saves the key store, returning the encrypted file content.
+     * Requires the master password to encrypt.
+     * @param password - The master password
+     * @returns Success with IKeyStoreFile, Failure if locked
+     * @public
+     */
+    save(password: string): Promise<Result<IKeyStoreFile>>;
+    /**
+     * Changes the master password.
+     * Re-encrypts the vault with the new password-derived key.
+     * @param currentPassword - Current master password (for verification)
+     * @param newPassword - New master password
+     * @returns Success when password changed, Failure if locked or current password incorrect
+     * @public
+     */
+    changePassword(currentPassword: string, newPassword: string): Promise<Result<KeyStore>>;
+    /** {@inheritDoc IEncryptionProvider.encryptByName} */
+    encryptByName<TMetadata = JsonValue>(secretName: string, content: JsonValue, metadata?: TMetadata): Promise<Result<IEncryptedFile<TMetadata>>>;
+    /**
+     * Creates a SecretProvider function for use with IEncryptionConfig.
+     * The returned function looks up secrets from this key store.
+     * @returns Success with SecretProvider, Failure if locked
+     * @public
+     */
+    getSecretProvider(): Result<SecretProvider>;
+    /**
+     * Creates a partial IEncryptionConfig using this key store as the secret source.
+     * @returns Partial config that can be spread into a full IEncryptionConfig
+     * @public
+     */
+    getEncryptionConfig(): Result<Pick<IEncryptionConfig, 'secretProvider' | 'cryptoProvider'>>;
+}
+//# sourceMappingURL=keyStore.d.ts.map