@fgv/ts-extras 5.0.2 → 5.1.0-1

package/dist/packlets/crypto-utils/encryptedFile.js

@@ -0,0 +1,161 @@
+// 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.
+import { captureResult, fail, succeed } from '@fgv/ts-utils';
+import * as Constants from './constants';
+import { createEncryptedFileConverter } from './converters';
+import { isEncryptedFile } from './model';
+// ============================================================================
+// Base64 Utilities
+// ============================================================================
+/**
+ * Encodes a `Uint8Array` to a base64 string.
+ * @param bytes - Bytes to encode
+ * @returns Base64 string
+ * @public
+ */
+/* c8 ignore start - Browser-only fallback cannot be tested in Node.js environment */
+export function toBase64(bytes) {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(bytes).toString('base64');
+    }
+    // Browser fallback
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+/* c8 ignore stop */
+/**
+ * Decodes a base64 string to a `Uint8Array`.
+ * @param base64 - Base64 string to decode
+ * @returns Decoded bytes
+ * @public
+ */
+/* c8 ignore start - Browser-only fallback cannot be tested in Node.js environment */
+export function fromBase64(base64) {
+    if (typeof Buffer !== 'undefined') {
+        return new Uint8Array(Buffer.from(base64, 'base64'));
+    }
+    // Browser fallback
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+// ============================================================================
+// Encryption Functions
+// ============================================================================
+/**
+ * Creates an {@link CryptoUtils.IEncryptedFile | encrypted file} from JSON content.
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @param params - Encryption parameters
+ * @returns `Success` with encrypted file structure, or `Failure` with an error.
+ * @public
+ */
+export async function createEncryptedFile(params) {
+    const { content, secretName, key, metadata, metadataConverter, keyDerivation, cryptoProvider } = params;
+    // Validate metadata if converter provided
+    /* c8 ignore next 6 - metadata validation path exercised via higher-level tests */
+    if (metadata !== undefined && metadataConverter !== undefined) {
+        const metadataResult = metadataConverter.convert(metadata);
+        if (metadataResult.isFailure()) {
+            return fail(`Invalid metadata: ${metadataResult.message}`);
+        }
+    }
+    // Serialize content to JSON string
+    const jsonResult = captureResult(() => JSON.stringify(content));
+    if (jsonResult.isFailure()) {
+        return fail(`Failed to serialize content: ${jsonResult.message}`);
+    }
+    // Encrypt the JSON string
+    const encryptResult = await cryptoProvider.encrypt(jsonResult.value, key);
+    if (encryptResult.isFailure()) {
+        return fail(`Encryption failed: ${encryptResult.message}`);
+    }
+    const { iv, authTag, encryptedData } = encryptResult.value;
+    // Build the encrypted file structure
+    const encryptedFile = Object.assign(Object.assign({ format: Constants.ENCRYPTED_FILE_FORMAT, secretName, algorithm: Constants.DEFAULT_ALGORITHM, iv: toBase64(iv), authTag: toBase64(authTag), encryptedData: toBase64(encryptedData) }, (metadata !== undefined ? { metadata } : {})), (keyDerivation !== undefined ? { keyDerivation } : {}));
+    return succeed(encryptedFile);
+}
+// ============================================================================
+// Decryption Functions
+// ============================================================================
+/**
+ * Decrypts an {@link CryptoUtils.IEncryptedFile | encrypted file} and returns the JSON content.
+ * @typeParam TPayload - Expected type of decrypted content
+ * @param file - The encrypted file structure
+ * @param key - The decryption key (32 bytes for AES-256)
+ * @param cryptoProvider - {@link CryptoUtils.ICryptoProvider | Crypto provider} to use for decryption
+ * @param payloadConverter - Optional converter to validate and convert decrypted content
+ * @returns `Success` with decrypted content, or `Failure` with an error.
+ * @public
+ */
+export async function decryptFile(file, key, cryptoProvider, payloadConverter) {
+    // Decode base64 values
+    const iv = fromBase64(file.iv);
+    const authTag = fromBase64(file.authTag);
+    const encryptedData = fromBase64(file.encryptedData);
+    // Decrypt
+    const decryptResult = await cryptoProvider.decrypt(encryptedData, key, iv, authTag);
+    if (decryptResult.isFailure()) {
+        return fail(decryptResult.message);
+    }
+    // Parse JSON
+    const parseResult = captureResult(() => JSON.parse(decryptResult.value)).withErrorFormat((e) => `Failed to parse decrypted content as JSON: ${e}`);
+    /* c8 ignore next 3 - JSON parse failure only occurs with corrupted encrypted data */
+    if (parseResult.isFailure()) {
+        return parseResult;
+    }
+    // Validate with converter if provided
+    /* c8 ignore next 3 - payload converter path exercised via higher-level tests */
+    if (payloadConverter !== undefined) {
+        return payloadConverter.convert(parseResult.value);
+    }
+    return parseResult;
+}
+/**
+ * Attempts to parse and decrypt a JSON object as an {@link CryptoUtils.IEncryptedFile | encrypted file}.
+ * @typeParam TPayload - Expected type of decrypted content
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @param json - JSON object that may be an encrypted file
+ * @param key - The decryption key (32 bytes for AES-256)
+ * @param cryptoProvider - {@link CryptoUtils.ICryptoProvider | Crypto provider} to use for decryption
+ * @param payloadConverter - Optional converter to validate and convert decrypted content
+ * @param metadataConverter - Optional converter to validate metadata before decryption
+ * @returns `Success` with decrypted content, or `Failure` with an error (including if not encrypted)
+ * @public
+ */
+export async function tryDecryptFile(json, key, cryptoProvider, payloadConverter, metadataConverter) {
+    // Check if it's an encrypted file
+    if (!isEncryptedFile(json)) {
+        return fail('Not an encrypted file');
+    }
+    // Validate and convert to typed encrypted file
+    const fileConverter = createEncryptedFileConverter(metadataConverter);
+    const fileResult = fileConverter.convert(json);
+    if (fileResult.isFailure()) {
+        return fail(`Invalid encrypted file format: ${fileResult.message}`);
+    }
+    return decryptFile(fileResult.value, key, cryptoProvider, payloadConverter);
+}
+//# sourceMappingURL=encryptedFile.js.map

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

@@ -0,0 +1,41 @@
+// 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.
+/**
+ * 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
+export * from './model';
+// Constants
+export { AES_256_KEY_SIZE, DEFAULT_ALGORITHM, ENCRYPTED_FILE_FORMAT, GCM_AUTH_TAG_SIZE, GCM_IV_SIZE } from './constants';
+// KeyStore namespace
+import * as KeyStore from './keystore';
+export { KeyStore };
+// Converters namespace
+import * as Converters from './converters';
+export { Converters };
+// Direct encryption provider
+export { DirectEncryptionProvider } from './directEncryptionProvider';
+// Note: NodeCryptoProvider is NOT exported in browser version
+// Use BrowserCryptoProvider from @fgv/ts-web-extras instead
+// Encrypted file helpers
+export { createEncryptedFile, decryptFile, fromBase64, toBase64, tryDecryptFile } from './encryptedFile';
+//# sourceMappingURL=index.browser.js.map

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

@@ -0,0 +1,41 @@
+// 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.
+/**
+ * Crypto utilities for encrypted file handling and key management.
+ * @packageDocumentation
+ */
+// Re-export all types from model
+export * from './model';
+// Constants
+import * as Constants from './constants';
+export { Constants };
+// KeyStore namespace
+import * as KeyStore from './keystore';
+export { KeyStore };
+// Converters namespace
+import * as Converters from './converters';
+export { Converters };
+// Direct encryption provider
+export { DirectEncryptionProvider } from './directEncryptionProvider';
+// Node.js crypto provider (Node.js environment only)
+export { NodeCryptoProvider, nodeCryptoProvider } from './nodeCryptoProvider';
+// Encrypted file helpers
+export { createEncryptedFile, decryptFile, fromBase64, toBase64, tryDecryptFile } from './encryptedFile';
+//# sourceMappingURL=index.js.map

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

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

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

@@ -0,0 +1,31 @@
+// 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.
+/**
+ * Key store module for password-protected secret management.
+ * @packageDocumentation
+ */
+// Types and interfaces
+export * from './model';
+// Converters namespace
+import * as Converters from './converters';
+export { Converters };
+// Key store class
+export { KeyStore } from './keyStore';
+//# sourceMappingURL=index.js.map