@giancarl021/cli-core-vault-extension/lib/src/services/SecretStorage.d.ts

Plain and secure storage extension for the @giancarl021/cli-core npm package

/**
 * Type of the SecretStorage instance.
 */
export type SecretStorageInstance = ReturnType<typeof SecretStorage>;
/**
 * Options for fallback storage using the filesystem.
 */
export interface FallbackStorageOptions {
    /**
     * Whether to use filesystem fallback storage.
     */
    useFilesystem: true;
    /**
     * Encryption key to use for encrypting the secrets in the filesystem.
     * It is recommended to use a strong, random key.
     */
    encryptionKey: string;
    /**
     * Path to the file where secrets will be stored if using filesystem fallback.
     * If the file or its parent directories do not exist, they will be created.
     * Default is `<home-dir>/.<app-name>/secrets.enc`, where `<app-name>` is the name of the application
     * and `<home-dir>` is the user's home directory.
     */
    filePath: string;
    /**
     * Whether to enable lazy initialization of the storage engine.
     * If `true`, the storage engine will only be initialized when it is first accessed.
     * If `false`, the storage engine will be initialized immediately when the SecretStorage is created.
     * Default is `true`.
     *
     * This is useful for applications that may not always need to access the secret storage,
     * allowing them to avoid unnecessary setup and resource usage if the storage is never used.
     * However, if the application always needs to access the secret storage, setting this to `false`
     * can help catch configuration errors early during startup.
     */
    lazyInitialization: boolean;
}
/**
 * Secret storage service.
 * @param appName The name of the application using the secret storage.
 * @returns An object with methods to get, set, and remove secrets.
 */
export default function SecretStorage(appName: string, fallbackStorageOptions?: FallbackStorageOptions): {
    /**
     * Get a secret value by its key.
     * @param key The key of the secret to retrieve.
     * @returns The secret value, or undefined if not found.
     */
    get: (key: string) => Promise<string | undefined>;
    /**
     * Set a secret value by its key.
     * @param key The key of the secret to set.
     * @param value The secret value to store.
     */
    set: (key: string, value: string) => Promise<void>;
    /**
     * Remove a secret by its key.
     * @param key The key of the secret to remove.
     */
    remove: (key: string) => Promise<void>;
};