@fgv/ts-extras 5.0.2 → 5.1.0-0

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

@@ -0,0 +1,245 @@
+import { EncryptionAlgorithm, ICryptoProvider, IKeyDerivationParams } from '../model';
+/**
+ * Format version for key store files.
+ * @public
+ */
+export type KeyStoreFormat = 'keystore-v1';
+/**
+ * Current format version constant.
+ * @public
+ */
+export declare const KEYSTORE_FORMAT: KeyStoreFormat;
+/**
+ * Default PBKDF2 iterations for key store encryption.
+ * Higher than regular files since this protects the master key vault.
+ * @public
+ */
+export declare const DEFAULT_KEYSTORE_ITERATIONS: number;
+/**
+ * Minimum salt length for key derivation.
+ * @public
+ */
+export declare const MIN_SALT_LENGTH: number;
+/**
+ * Discriminator for secret types stored in the vault.
+ * - `'encryption-key'`: A 32-byte AES-256 encryption key.
+ * - `'api-key'`: An arbitrary-length API key string (UTF-8 encoded).
+ * @public
+ */
+export type KeyStoreSecretType = 'encryption-key' | 'api-key';
+/**
+ * All valid key store secret types.
+ * @public
+ */
+export declare const allKeyStoreSecretTypes: ReadonlyArray<KeyStoreSecretType>;
+/**
+ * A secret entry stored in the vault (in-memory representation).
+ * @public
+ */
+export interface IKeyStoreSecretEntry {
+    /**
+     * Unique name for this secret (used as lookup key).
+     */
+    readonly name: string;
+    /**
+     * Secret type discriminator.
+     * Defaults to `'encryption-key'` for backwards compatibility.
+     */
+    readonly type: KeyStoreSecretType;
+    /**
+     * The secret data.
+     * - For `'encryption-key'`: 32-byte AES-256 key.
+     * - For `'api-key'`: UTF-8 encoded API key string (arbitrary length).
+     */
+    readonly key: Uint8Array;
+    /**
+     * Optional description for this secret.
+     */
+    readonly description?: string;
+    /**
+     * When this secret was added (ISO 8601).
+     */
+    readonly createdAt: string;
+}
+/**
+ * JSON-serializable version of secret entry (for storage).
+ * @public
+ */
+export interface IKeyStoreSecretEntryJson {
+    /**
+     * Unique name for this secret.
+     */
+    readonly name: string;
+    /**
+     * Secret type discriminator.
+     * Optional for backwards compatibility — missing means `'encryption-key'`.
+     */
+    readonly type?: KeyStoreSecretType;
+    /**
+     * Base64-encoded secret data.
+     */
+    readonly key: string;
+    /**
+     * Optional description.
+     */
+    readonly description?: string;
+    /**
+     * When this secret was added (ISO 8601).
+     */
+    readonly createdAt: string;
+}
+/**
+ * The decrypted vault contents - a versioned map of secrets.
+ * @public
+ */
+export interface IKeyStoreVaultContents {
+    /**
+     * Format version for vault contents.
+     */
+    readonly version: KeyStoreFormat;
+    /**
+     * Map of secret name to secret entry.
+     */
+    readonly secrets: Record<string, IKeyStoreSecretEntryJson>;
+}
+/**
+ * The encrypted key store file format.
+ * @public
+ */
+export interface IKeyStoreFile {
+    /**
+     * Format identifier.
+     */
+    readonly format: KeyStoreFormat;
+    /**
+     * Algorithm used for encryption.
+     */
+    readonly algorithm: EncryptionAlgorithm;
+    /**
+     * Base64-encoded initialization vector.
+     */
+    readonly iv: string;
+    /**
+     * Base64-encoded authentication tag.
+     */
+    readonly authTag: string;
+    /**
+     * Base64-encoded encrypted vault contents.
+     */
+    readonly encryptedData: string;
+    /**
+     * Key derivation parameters (required for key store - always password-derived).
+     */
+    readonly keyDerivation: IKeyDerivationParams;
+}
+/**
+ * Key store lock state.
+ * @public
+ */
+export type KeyStoreLockState = 'locked' | 'unlocked';
+/**
+ * Parameters for creating a new key store.
+ * @public
+ */
+export interface IKeyStoreCreateParams {
+    /**
+     * Crypto provider to use.
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * PBKDF2 iterations (defaults to DEFAULT_KEYSTORE_ITERATIONS).
+     */
+    readonly iterations?: number;
+}
+/**
+ * Parameters for opening an existing key store.
+ * @public
+ */
+export interface IKeyStoreOpenParams {
+    /**
+     * Crypto provider to use.
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * The encrypted key store file content.
+     */
+    readonly keystoreFile: IKeyStoreFile;
+}
+/**
+ * Result of adding a secret to the key store.
+ * @public
+ */
+export interface IAddSecretResult {
+    /**
+     * The secret entry that was added.
+     */
+    readonly entry: IKeyStoreSecretEntry;
+    /**
+     * Whether this replaced an existing secret.
+     */
+    readonly replaced: boolean;
+}
+/**
+ * Options for adding a secret.
+ * @public
+ */
+export interface IAddSecretOptions {
+    /**
+     * Optional description for the secret.
+     */
+    readonly description?: string;
+}
+/**
+ * Options for importing a secret.
+ * @public
+ */
+export interface IImportSecretOptions extends IAddSecretOptions {
+    /**
+     * Whether to replace an existing secret with the same name.
+     */
+    readonly replace?: boolean;
+}
+/**
+ * Options for adding a secret derived from a password.
+ * @public
+ */
+export interface IAddSecretFromPasswordOptions extends IAddSecretOptions {
+    /**
+     * Whether to replace an existing secret with the same name.
+     */
+    readonly replace?: boolean;
+    /**
+     * PBKDF2 iterations for key derivation.
+     * @defaultValue DEFAULT_SECRET_ITERATIONS (350000)
+     */
+    readonly iterations?: number;
+}
+/**
+ * Default PBKDF2 iterations for secret-level key derivation.
+ * Lower than keystore encryption since these are used more frequently.
+ * @public
+ */
+export declare const DEFAULT_SECRET_ITERATIONS: number;
+/**
+ * Result of adding a password-derived secret.
+ * Extends {@link IAddSecretResult} with key derivation parameters
+ * needed to store alongside encrypted files.
+ * @public
+ */
+export interface IAddSecretFromPasswordResult extends IAddSecretResult {
+    /**
+     * Key derivation parameters used to derive the secret key.
+     * Store these in encrypted file metadata so the password alone
+     * can re-derive the same key for decryption.
+     */
+    readonly keyDerivation: IKeyDerivationParams;
+}
+/**
+ * Checks if a JSON object appears to be a key store file.
+ * Uses the format field as a discriminator.
+ * @param json - JSON object to check
+ * @returns true if the object has the key store format field
+ * @public
+ */
+export declare function isKeyStoreFile(json: unknown): boolean;
+//# sourceMappingURL=model.d.ts.map

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

@@ -0,0 +1,68 @@
+"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.DEFAULT_SECRET_ITERATIONS = exports.allKeyStoreSecretTypes = exports.MIN_SALT_LENGTH = exports.DEFAULT_KEYSTORE_ITERATIONS = exports.KEYSTORE_FORMAT = void 0;
+exports.isKeyStoreFile = isKeyStoreFile;
+/**
+ * Current format version constant.
+ * @public
+ */
+exports.KEYSTORE_FORMAT = 'keystore-v1';
+/**
+ * Default PBKDF2 iterations for key store encryption.
+ * Higher than regular files since this protects the master key vault.
+ * @public
+ */
+exports.DEFAULT_KEYSTORE_ITERATIONS = 600000;
+/**
+ * Minimum salt length for key derivation.
+ * @public
+ */
+exports.MIN_SALT_LENGTH = 16;
+/**
+ * All valid key store secret types.
+ * @public
+ */
+exports.allKeyStoreSecretTypes = ['encryption-key', 'api-key'];
+/**
+ * Default PBKDF2 iterations for secret-level key derivation.
+ * Lower than keystore encryption since these are used more frequently.
+ * @public
+ */
+exports.DEFAULT_SECRET_ITERATIONS = 350000;
+// ============================================================================
+// Detection Helper
+// ============================================================================
+/**
+ * Checks if a JSON object appears to be a key store file.
+ * Uses the format field as a discriminator.
+ * @param json - JSON object to check
+ * @returns true if the object has the key store format field
+ * @public
+ */
+function isKeyStoreFile(json) {
+    if (typeof json !== 'object' || json === null) {
+        return false;
+    }
+    const obj = json;
+    return obj.format === exports.KEYSTORE_FORMAT;
+}
+//# sourceMappingURL=model.js.map

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

@@ -0,0 +1,236 @@
+import { JsonValue } from '@fgv/ts-json-base';
+import { Result } from '@fgv/ts-utils';
+import * as Constants from './constants';
+export { Constants };
+/**
+ * Supported encryption algorithms.
+ * @public
+ */
+export type EncryptionAlgorithm = typeof Constants.DEFAULT_ALGORITHM;
+/**
+ * Format version for encrypted files.
+ * @public
+ */
+export type EncryptedFileFormat = typeof Constants.ENCRYPTED_FILE_FORMAT;
+/**
+ * Named secret for encryption/decryption.
+ * @public
+ */
+export interface INamedSecret {
+    /**
+     * Unique name for this secret (referenced in encrypted files).
+     */
+    readonly name: string;
+    /**
+     * The actual secret key (32 bytes for AES-256).
+     */
+    readonly key: Uint8Array;
+}
+/**
+ * Result of an encryption operation.
+ * @public
+ */
+export interface IEncryptionResult {
+    /**
+     * Initialization vector used for encryption (12 bytes for GCM).
+     */
+    readonly iv: Uint8Array;
+    /**
+     * Authentication tag from GCM mode (16 bytes).
+     */
+    readonly authTag: Uint8Array;
+    /**
+     * The encrypted data.
+     */
+    readonly encryptedData: Uint8Array;
+}
+/**
+ * Supported key derivation functions.
+ * @public
+ */
+export type KeyDerivationFunction = 'pbkdf2';
+/**
+ * Key derivation parameters stored in encrypted files.
+ * Allows decryption with password without needing to know the original salt/iterations.
+ * @public
+ */
+export interface IKeyDerivationParams {
+    /**
+     * Key derivation function used.
+     */
+    readonly kdf: KeyDerivationFunction;
+    /**
+     * Base64-encoded salt used for key derivation.
+     */
+    readonly salt: string;
+    /**
+     * Number of iterations used for key derivation.
+     */
+    readonly iterations: number;
+}
+/**
+ * Generic encrypted file format.
+ * This is the JSON structure stored in encrypted files.
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @public
+ */
+export interface IEncryptedFile<TMetadata = JsonValue> {
+    /**
+     * Format identifier for versioning.
+     */
+    readonly format: EncryptedFileFormat;
+    /**
+     * Name of the secret required to decrypt (references INamedSecret.name).
+     */
+    readonly secretName: string;
+    /**
+     * Algorithm used for encryption.
+     */
+    readonly algorithm: EncryptionAlgorithm;
+    /**
+     * Base64-encoded initialization vector.
+     */
+    readonly iv: string;
+    /**
+     * Base64-encoded authentication tag (for GCM mode).
+     */
+    readonly authTag: string;
+    /**
+     * Base64-encoded encrypted data (JSON string when decrypted).
+     */
+    readonly encryptedData: string;
+    /**
+     * Optional unencrypted metadata for display/filtering.
+     */
+    readonly metadata?: TMetadata;
+    /**
+     * Optional key derivation parameters.
+     * If present, allows decryption using a password with these parameters.
+     * If absent, a pre-derived key must be provided.
+     */
+    readonly keyDerivation?: IKeyDerivationParams;
+}
+/**
+ * Crypto provider interface for cross-platform encryption.
+ * Implementations provided for Node.js (crypto module) and browser (Web Crypto API).
+ * @public
+ */
+export interface ICryptoProvider {
+    /**
+     * Encrypts plaintext using AES-256-GCM.
+     * @param plaintext - UTF-8 string to encrypt
+     * @param key - 32-byte encryption key
+     * @returns Success with encryption result, or Failure with error
+     */
+    encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>>;
+    /**
+     * Decrypts ciphertext using AES-256-GCM.
+     * @param encryptedData - Encrypted bytes
+     * @param key - 32-byte decryption key
+     * @param iv - Initialization vector (12 bytes)
+     * @param authTag - GCM authentication tag (16 bytes)
+     * @returns Success with decrypted UTF-8 string, or Failure with error
+     */
+    decrypt(encryptedData: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array): Promise<Result<string>>;
+    /**
+     * Generates a random 32-byte key suitable for AES-256.
+     * @returns Success with generated key, or Failure with error
+     */
+    generateKey(): Promise<Result<Uint8Array>>;
+    /**
+     * Derives a key from a password using PBKDF2.
+     * @param password - Password string
+     * @param salt - Salt bytes (should be at least 16 bytes)
+     * @param iterations - Number of iterations (recommend 100000+)
+     * @returns Success with derived 32-byte key, or Failure with error
+     */
+    deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * 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>;
+    /**
+     * Encodes binary data to base64 string.
+     * @param data - Binary data to encode
+     * @returns Base64-encoded string
+     */
+    toBase64(data: Uint8Array): string;
+    /**
+     * Decodes base64 string to binary data.
+     * @param base64 - Base64-encoded string
+     * @returns Success with decoded bytes, or Failure if invalid base64
+     */
+    fromBase64(base64: string): Result<Uint8Array>;
+}
+/**
+ * High-level interface for encrypting JSON content by secret name.
+ *
+ * This abstraction unifies two common encryption workflows:
+ * - **KeyStore**: looks up the named secret and crypto provider from the vault
+ * - **DirectEncryptionProvider**: uses a pre-supplied key and crypto provider,
+ *   optionally bound to a specific secret name for safety
+ *
+ * Callers that need to encrypt (e.g. `EditableCollection.save()`) depend on
+ * this interface rather than on `KeyStore` directly, allowing mix-and-match.
+ *
+ * @public
+ */
+export interface IEncryptionProvider {
+    /**
+     * Encrypts JSON content under a named secret.
+     *
+     * @param secretName - Name of the secret to encrypt with
+     * @param content - JSON-safe content to encrypt
+     * @param metadata - Optional unencrypted metadata to include in the encrypted file
+     * @returns Success with encrypted file structure, or Failure with error context
+     */
+    encryptByName<TMetadata = JsonValue>(secretName: string, content: JsonValue, metadata?: TMetadata): Promise<Result<IEncryptedFile<TMetadata>>>;
+}
+/**
+ * Behavior when an encrypted file cannot be decrypted.
+ * @public
+ */
+export type EncryptedFileErrorMode = 'fail' | 'skip' | 'warn';
+/**
+ * Function type for dynamic secret retrieval.
+ * @public
+ */
+export type SecretProvider = (secretName: string) => Promise<Result<Uint8Array>>;
+/**
+ * Configuration for encrypted file handling during loading.
+ * @public
+ */
+export interface IEncryptionConfig {
+    /**
+     * Named secrets available for decryption.
+     */
+    readonly secrets?: ReadonlyArray<INamedSecret>;
+    /**
+     * Alternative: dynamic secret provider function.
+     * Called when a secret is not found in the secrets array.
+     */
+    readonly secretProvider?: SecretProvider;
+    /**
+     * Crypto provider implementation (Node.js or browser).
+     */
+    readonly cryptoProvider: ICryptoProvider;
+    /**
+     * Behavior when decryption key is missing (default: 'fail').
+     */
+    readonly onMissingKey?: EncryptedFileErrorMode;
+    /**
+     * Behavior when decryption fails (default: 'fail').
+     */
+    readonly onDecryptionError?: EncryptedFileErrorMode;
+}
+/**
+ * Checks if a JSON object appears to be an encrypted file.
+ * Uses the format field as a discriminator.
+ * @param json - JSON object to check
+ * @returns true if the object has the encrypted file format field
+ * @public
+ */
+export declare function isEncryptedFile(json: unknown): boolean;
+//# sourceMappingURL=model.d.ts.map

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

@@ -0,0 +1,76 @@
+"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 __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.Constants = void 0;
+exports.isEncryptedFile = isEncryptedFile;
+const Constants = __importStar(require("./constants"));
+exports.Constants = Constants;
+// ============================================================================
+// Detection Helper
+// ============================================================================
+/**
+ * Checks if a JSON object appears to be an encrypted file.
+ * Uses the format field as a discriminator.
+ * @param json - JSON object to check
+ * @returns true if the object has the encrypted file format field
+ * @public
+ */
+function isEncryptedFile(json) {
+    if (typeof json !== 'object' || json === null) {
+        return false;
+    }
+    const obj = json;
+    return obj.format === Constants.ENCRYPTED_FILE_FORMAT;
+}
+//# sourceMappingURL=model.js.map

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

@@ -0,0 +1,62 @@
+import { Result } from '@fgv/ts-utils';
+import { ICryptoProvider, IEncryptionResult } from './model';
+/**
+ * Node.js implementation of {@link CryptoUtils.ICryptoProvider} using the built-in crypto module.
+ * Uses AES-256-GCM for authenticated encryption.
+ * @public
+ */
+export declare class NodeCryptoProvider implements ICryptoProvider {
+    /**
+     * Encrypts plaintext using AES-256-GCM.
+     * @param plaintext - UTF-8 string to encrypt
+     * @param key - 32-byte encryption key
+     * @returns `Success` with encryption result, or `Failure` with an error.
+     */
+    encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>>;
+    /**
+     * Decrypts ciphertext using AES-256-GCM.
+     * @param encryptedData - Encrypted bytes
+     * @param key - 32-byte decryption key
+     * @param iv - Initialization vector (12 bytes)
+     * @param authTag - GCM authentication tag (16 bytes)
+     * @returns `Success` with decrypted UTF-8 string, or `Failure` with an error.
+     */
+    decrypt(encryptedData: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array): Promise<Result<string>>;
+    /**
+     * Generates a random 32-byte key suitable for AES-256.
+     * @returns `Success` with generated key, or `Failure` with an error.
+     */
+    generateKey(): Promise<Result<Uint8Array>>;
+    /**
+     * Derives a key from a password using PBKDF2.
+     * @param password - Password string
+     * @param salt - Salt bytes (should be at least 16 bytes)
+     * @param iterations - Number of iterations (recommend 100000+)
+     * @returns `Success` with derived 32-byte key, or `Failure` with an error.
+     */
+    deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * 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>;
+    /**
+     * Encodes binary data to base64 string.
+     * @param data - Binary data to encode
+     * @returns Base64-encoded string
+     */
+    toBase64(data: Uint8Array): string;
+    /**
+     * Decodes base64 string to binary data.
+     * @param base64 - Base64-encoded string
+     * @returns Success with decoded bytes, or Failure if invalid base64
+     */
+    fromBase64(base64: string): Result<Uint8Array>;
+}
+/**
+ * Singleton instance of {@link CryptoUtils.NodeCryptoProvider}.
+ * @public
+ */
+export declare const nodeCryptoProvider: NodeCryptoProvider;
+//# sourceMappingURL=nodeCryptoProvider.d.ts.map