@fgv/ts-web-extras 5.0.2 → 5.1.0-0

package/docs/ts-web-extras.md

@@ -23,23 +23,38 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
-[BrowserHashProvider](./ts-web-extras.browserhashprovider.md)
+[FileApiTreeAccessors](./ts-web-extras.fileapitreeaccessors.md)
 
 
 </td><td>
 
-Browser-compatible hash provider using the Web Crypto API. Supports common hash algorithms available in browsers.
+Helper class to create FileTree instances from various file sources. Supports File API (FileList) and File System Access API handles.
 
 
 </td></tr>
 <tr><td>
 
-[FileApiTreeAccessors](./ts-web-extras.fileapitreeaccessors.md)
+[FileSystemAccessTreeAccessors](./ts-web-extras.filesystemaccesstreeaccessors.md)
 
 
 </td><td>
 
-Helper class to create FileTree instances from various file sources. Supports File API (FileList) and File System Access API handles.
+Implementation of `FileTree.IPersistentFileTreeAccessors` that uses the File System Access API to provide persistent file editing in browsers.
+
+
+</td></tr>
+<tr><td>
+
+[LocalStorageTreeAccessors](./ts-web-extras.localstoragetreeaccessors.md)
+
+
+</td><td>
+
+Browser localStorage-backed file tree accessors with persistence support.
+
+Maps filesystem-like directory paths to localStorage keys, where each key stores multiple collections as a JSON object. This provides a general-purpose implementation for browser-based file tree persistence without requiring File System Access API.
+
+Storage format per key: `{ "collection-id": { ...collectionData }, ... }` File paths map as: `/data/ingredients/collection-id.json` → stored in key for `/data/ingredients`
 
 
 </td></tr>
@@ -380,6 +395,17 @@ Tree initializer for FileList objects (from File API).
 Interface for file metadata.
 
 
+</td></tr>
+<tr><td>
+
+[IFileSystemAccessTreeParams](./ts-web-extras.ifilesystemaccesstreeparams.md)
+
+
+</td><td>
+
+Options for creating persistent file trees.
+
+
 </td></tr>
 <tr><td>
 
@@ -391,6 +417,17 @@ Interface for file metadata.
 File System Access API methods available on Window
 
 
+</td></tr>
+<tr><td>
+
+[ILocalStorageTreeParams](./ts-web-extras.ilocalstoragetreeparams.md)
+
+
+</td><td>
+
+Configuration for LocalStorageTreeAccessors.
+
+
 </td></tr>
 <tr><td>
 
@@ -453,6 +490,15 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
+[CryptoUtils](./ts-web-extras.cryptoutils.md)
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
 [FileTreeHelpers](./ts-web-extras.filetreehelpers.md)
 
 

package/etc/ts-web-extras.api.md

@@ -4,18 +4,69 @@
 
 ```ts
 
+import { CryptoUtils as CryptoUtils_2 } from '@fgv/ts-extras';
+import { DetailedResult } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-json-base';
 import { Result } from '@fgv/ts-utils';
 
+// Warning: (ae-forgotten-export) The symbol "ICryptoProvider" needs to be exported by the entry point index.d.ts
+//
+// @public
+class BrowserCryptoProvider implements ICryptoProvider {
+    // Warning: (ae-unresolved-link) The @link reference could not be resolved: This type of declaration is not supported yet by the resolver
+    constructor(cryptoApi?: Crypto);
+    decrypt(encryptedData: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array): Promise<Result<string>>;
+    deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    // Warning: (ae-forgotten-export) The symbol "IEncryptionResult" needs to be exported by the entry point index.d.ts
+    encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>>;
+    fromBase64(base64: string): Result<Uint8Array>;
+    generateKey(): Promise<Result<Uint8Array>>;
+    generateRandomBytes(length: number): Result<Uint8Array>;
+    toBase64(data: Uint8Array): string;
+}
+
 // @public
-export class BrowserHashProvider {
+class BrowserHashProvider {
     static hashParts(parts: string[], algorithm?: string, separator?: string): Promise<Result<string>>;
     static hashString(data: string, algorithm?: string): Promise<Result<string>>;
 }
 
+// Warning: (ae-unresolved-link) The @link reference could not be resolved: This type of declaration is not supported yet by the resolver
+//
+// @public
+function createBrowserCryptoProvider(): Result<BrowserCryptoProvider>;
+
+declare namespace CryptoUtils {
+    export {
+        BrowserHashProvider,
+        createBrowserCryptoProvider,
+        BrowserCryptoProvider
+    }
+}
+export { CryptoUtils }
+
+// @public
+export const DEFAULT_DIRECTORY_HANDLE_DB = "chocolate-lab-storage";
+
+// @public
+export const DEFAULT_DIRECTORY_HANDLE_STORE = "directory-handles";
+
 // @public
 const defaultFileApiTreeInitParams: FileTree.IFileTreeInitParams<string>;
 
+// @public
+export class DirectoryHandleStore {
+    constructor(dbName?: string, storeName?: string);
+    getAll(): Promise<Result<Array<{
+        label: string;
+        handle: FileSystemDirectoryHandle_2;
+    }>>>;
+    getAllLabels(): Promise<Result<string[]>>;
+    load(label: string): Promise<Result<FileSystemDirectoryHandle_2 | undefined>>;
+    remove(label: string): Promise<Result<void>>;
+    save(label: string, handle: FileSystemDirectoryHandle_2): Promise<Result<void>>;
+}
+
 // @public
 export function exportAsJson(data: unknown, filename: string): void;
 
@@ -34,6 +85,9 @@ function extractFileMetadata(file: File): IFileMetadata;
 // @public
 export class FileApiTreeAccessors<TCT extends string = string> {
     static create<TCT extends string = string>(initializers: TreeInitializer[], params?: FileTree.IFileTreeInitParams<TCT>): Promise<Result<FileTree.FileTree<TCT>>>;
+    static createFromLocalStorage<TCT extends string = string>(params: ILocalStorageTreeParams<TCT>): Result<FileTree.FileTree<TCT>>;
+    static createPersistent<TCT extends string = string>(dirHandle: FileSystemDirectoryHandle_2, params?: IFileSystemAccessTreeParams<TCT>): Promise<Result<FileTree.FileTree<TCT>>>;
+    static createPersistentFromFile<TCT extends string = string>(fileHandle: FileSystemFileHandle_2, params?: IFileSystemAccessTreeParams<TCT>): Promise<Result<FileTree.FileTree<TCT>>>;
     static extractFileMetadata(file: File): IFileMetadata;
     static fromDirectoryUpload<TCT extends string = string>(fileList: FileList, params?: FileTree.IFileTreeInitParams<TCT>): Promise<Result<FileTree.FileTree<TCT>>>;
     static fromFileList<TCT extends string = string>(fileList: FileList, params?: FileTree.IFileTreeInitParams<TCT>): Promise<Result<FileTree.FileTree<TCT>>>;
@@ -48,6 +102,18 @@ export interface FilePickerAcceptType {
     description?: string;
 }
 
+// @public
+export class FileSystemAccessTreeAccessors<TCT extends string = string> extends FileTree.InMemoryTreeAccessors<TCT> implements FileTree.IPersistentFileTreeAccessors<TCT> {
+    protected constructor(files: FileTree.IInMemoryFile<TCT>[], rootDir: FileSystemDirectoryHandle_2, handles: Map<string, FileSystemFileHandle_2>, params: IFileSystemAccessTreeParams<TCT> | undefined, hasWritePermission: boolean);
+    fileIsMutable(path: string): DetailedResult<boolean, FileTree.SaveDetail>;
+    static fromDirectoryHandle<TCT extends string = string>(dirHandle: FileSystemDirectoryHandle_2, params?: IFileSystemAccessTreeParams<TCT>): Promise<Result<FileSystemAccessTreeAccessors<TCT>>>;
+    static fromFileHandle<TCT extends string = string>(fileHandle: FileSystemFileHandle_2, params?: IFileSystemAccessTreeParams<TCT>): Promise<Result<FileSystemAccessTreeAccessors<TCT>>>;
+    getDirtyPaths(): string[];
+    isDirty(): boolean;
+    saveFileContents(path: string, contents: string): Result<string>;
+    syncToDisk(): Promise<Result<void>>;
+}
+
 // @public
 interface FileSystemCreateWritableOptions_2 {
     // (undocumented)
@@ -200,6 +266,13 @@ export interface IFileMetadata {
     type: string;
 }
 
+// @public
+export interface IFileSystemAccessTreeParams<TCT extends string = string> extends FileTree.IFileTreeInitParams<TCT> {
+    autoSync?: boolean;
+    filePath?: string;
+    requireWritePermission?: boolean;
+}
+
 // @public
 export interface IFsAccessApis {
     // (undocumented)
@@ -210,6 +283,13 @@ export interface IFsAccessApis {
     showSaveFilePicker(options?: ShowSaveFilePickerOptions): Promise<FileSystemFileHandle_2>;
 }
 
+// @public
+export interface ILocalStorageTreeParams<TCT extends string = string> extends FileTree.IFileTreeInitParams<TCT> {
+    autoSync?: boolean;
+    pathToKeyMap: Record<string, string>;
+    storage?: Storage;
+}
+
 // @public
 export function isDirectoryHandle(handle: FileSystemHandle_2): handle is FileSystemDirectoryHandle_2;
 
@@ -236,6 +316,16 @@ export interface IUrlConfigOptions {
     zipPath?: string;
 }
 
+// @public
+export class LocalStorageTreeAccessors<TCT extends string = string> extends FileTree.InMemoryTreeAccessors<TCT> implements FileTree.IPersistentFileTreeAccessors<TCT> {
+    fileIsMutable(path: string): DetailedResult<boolean, FileTree.SaveDetail>;
+    static fromStorage<TCT extends string = string>(params: ILocalStorageTreeParams<TCT>): Result<LocalStorageTreeAccessors<TCT>>;
+    getDirtyPaths(): string[];
+    isDirty(): boolean;
+    saveFileContents(path: string, contents: string): Result<string>;
+    syncToDisk(): Promise<Result<void>>;
+}
+
 // @public
 export function parseContextFilter(contextFilter: string): Record<string, string>;
 

package/lib/index.d.ts

@@ -8,7 +8,8 @@
  *
  * @packageDocumentation
  */
-export * from './packlets/crypto';
+import * as CryptoUtils from './packlets/crypto-utils';
+export { CryptoUtils };
 export * from './packlets/file-tree';
 export * from './packlets/helpers';
 export * from './packlets/file-api-types';

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;GASG;AAGH,cAAc,mBAAmB,CAAC;AAGlC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;GASG;AAEH,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,CAAC;AAGvB,cAAc,sBAAsB,CAAC;AAGrC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,sBAAsB,CAAC"}

package/lib/index.js

@@ -31,10 +31,33 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
     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;
+    };
+})();
 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);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CryptoUtils = void 0;
 /**
  * Browser-compatible utilities and FileTree implementations.
  *
@@ -45,8 +68,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
  *
  * @packageDocumentation
  */
-// Export crypto functionality
-__exportStar(require("./packlets/crypto"), exports);
+const CryptoUtils = __importStar(require("./packlets/crypto-utils"));
+exports.CryptoUtils = CryptoUtils;
 // Export file tree functionality
 __exportStar(require("./packlets/file-tree"), exports);
 // Export helper functions

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;AAEH;;;;;;;;;GASG;AAEH,8BAA8B;AAC9B,oDAAkC;AAElC,iCAAiC;AACjC,uDAAqC;AAErC,0BAA0B;AAC1B,qDAAmC;AAEnC,sCAAsC;AACtC,4DAA0C;AAE1C,uBAAuB;AACvB,uDAAqC","sourcesContent":["/*\n * Copyright (c) 2025 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 */\n\n/**\n * Browser-compatible utilities and FileTree implementations.\n *\n * This library provides browser-compatible alternatives to Node.js-specific functionality,\n * including Web Crypto API-based hashing, File API-based file tree implementations,\n * and URL parameter parsing utilities.\n * All exports are designed to be tree-shakeable for optimal bundle size.\n *\n * @packageDocumentation\n */\n\n// Export crypto functionality\nexport * from './packlets/crypto';\n\n// Export file tree functionality\nexport * from './packlets/file-tree';\n\n// Export helper functions\nexport * from './packlets/helpers';\n\n// Export File System Access API types\nexport * from './packlets/file-api-types';\n\n// Export URL utilities\nexport * from './packlets/url-utils';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH;;;;;;;;;GASG;AAEH,qEAAuD;AAC9C,kCAAW;AAEpB,iCAAiC;AACjC,uDAAqC;AAErC,0BAA0B;AAC1B,qDAAmC;AAEnC,sCAAsC;AACtC,4DAA0C;AAE1C,uBAAuB;AACvB,uDAAqC","sourcesContent":["/*\n * Copyright (c) 2025 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 */\n\n/**\n * Browser-compatible utilities and FileTree implementations.\n *\n * This library provides browser-compatible alternatives to Node.js-specific functionality,\n * including Web Crypto API-based hashing, File API-based file tree implementations,\n * and URL parameter parsing utilities.\n * All exports are designed to be tree-shakeable for optimal bundle size.\n *\n * @packageDocumentation\n */\n\nimport * as CryptoUtils from './packlets/crypto-utils';\nexport { CryptoUtils };\n\n// Export file tree functionality\nexport * from './packlets/file-tree';\n\n// Export helper functions\nexport * from './packlets/helpers';\n\n// Export File System Access API types\nexport * from './packlets/file-api-types';\n\n// Export URL utilities\nexport * from './packlets/url-utils';\n"]}

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

@@ -0,0 +1,77 @@
+import { Result } from '@fgv/ts-utils';
+import { CryptoUtils } from '@fgv/ts-extras';
+type ICryptoProvider = CryptoUtils.ICryptoProvider;
+type IEncryptionResult = CryptoUtils.IEncryptionResult;
+/**
+ * Browser implementation of `ICryptoProvider` using the Web Crypto API.
+ * Uses AES-256-GCM for authenticated encryption.
+ *
+ * Note: This provider requires a browser environment with Web Crypto API support.
+ * In Node.js 15+, Web Crypto is available via globalThis.crypto or require('crypto').webcrypto.
+ *
+ * @public
+ */
+export declare class BrowserCryptoProvider implements ICryptoProvider {
+    private readonly _crypto;
+    /**
+     * Creates a new {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider}.
+     * @param cryptoApi - Optional Crypto instance (defaults to globalThis.crypto)
+     */
+    constructor(cryptoApi?: Crypto);
+    /**
+     * 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 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>;
+}
+/**
+ * Creates a {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider} if Web
+ * Crypto API is available.
+ * @returns `Success` with provider, or `Failure` if not available
+ * @public
+ */
+export declare function createBrowserCryptoProvider(): Result<BrowserCryptoProvider>;
+export {};
+//# sourceMappingURL=browserCryptoProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"browserCryptoProvider.d.ts","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/browserCryptoProvider.ts"],"names":[],"mappings":"AAqBA,OAAO,EAA0B,MAAM,EAAW,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,KAAK,eAAe,GAAG,WAAW,CAAC,eAAe,CAAC;AACnD,KAAK,iBAAiB,GAAG,WAAW,CAAC,iBAAiB,CAAC;AAevD;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;OAGG;gBACgB,SAAS,CAAC,EAAE,MAAM;IAYrC;;;;;OAKG;IACU,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAmD5F;;;;;;;OAOG;IACU,OAAO,CAClB,aAAa,EAAE,UAAU,EACzB,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,UAAU,EACd,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAgD1B;;;OAGG;IACU,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IASvD;;;;;;OAMG;IACU,SAAS,CACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAyC9B;;;;OAIG;IACI,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC;IAY9D;;;;OAIG;IACI,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM;IASzC;;;;OAIG;IACI,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC;CAYtD;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,CAAC,qBAAqB,CAAC,CAE3E"}

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

@@ -0,0 +1,259 @@
+"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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserCryptoProvider = void 0;
+exports.createBrowserCryptoProvider = createBrowserCryptoProvider;
+/* c8 ignore start - Browser-only implementation cannot be tested in Node.js environment */
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_extras_1 = require("@fgv/ts-extras");
+const CryptoConstants = ts_extras_1.CryptoUtils.Constants;
+/**
+ * Extracts an `ArrayBuffer` from a Uint8Array, handling the potential SharedArrayBuffer case.
+ * @param arr - The Uint8Array to extract from
+ * @returns An `ArrayBuffer` containing a copy of the data.
+ */
+function toArrayBuffer(arr) {
+    // Create a new ArrayBuffer and copy the data - this handles both ArrayBuffer and SharedArrayBuffer
+    const buffer = new ArrayBuffer(arr.byteLength);
+    new Uint8Array(buffer).set(arr);
+    return buffer;
+}
+/**
+ * Browser implementation of `ICryptoProvider` using the Web Crypto API.
+ * Uses AES-256-GCM for authenticated encryption.
+ *
+ * Note: This provider requires a browser environment with Web Crypto API support.
+ * In Node.js 15+, Web Crypto is available via globalThis.crypto or require('crypto').webcrypto.
+ *
+ * @public
+ */
+class BrowserCryptoProvider {
+    /**
+     * Creates a new {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider}.
+     * @param cryptoApi - Optional Crypto instance (defaults to globalThis.crypto)
+     */
+    constructor(cryptoApi) {
+        if (cryptoApi) {
+            this._crypto = cryptoApi;
+        }
+        else if (typeof globalThis !== 'undefined' && globalThis.crypto) {
+            this._crypto = globalThis.crypto;
+        }
+        else if (typeof window !== 'undefined' && window.crypto) {
+            this._crypto = window.crypto;
+        }
+        else {
+            throw new Error('Web Crypto API not available');
+        }
+    }
+    /**
+     * 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.
+     */
+    async encrypt(plaintext, key) {
+        if (key.length !== CryptoConstants.AES_256_KEY_SIZE) {
+            return ts_utils_1.Failure.with(`Key must be ${CryptoConstants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+        }
+        try {
+            // Generate random IV
+            const iv = this._crypto.getRandomValues(new Uint8Array(CryptoConstants.GCM_IV_SIZE));
+            // Import the key
+            const cryptoKey = await this._crypto.subtle.importKey('raw', toArrayBuffer(key), { name: 'AES-GCM' }, false, ['encrypt']);
+            // Encode plaintext to bytes
+            const encoder = new TextEncoder();
+            const plaintextBytes = encoder.encode(plaintext);
+            // Encrypt (Web Crypto appends auth tag to ciphertext)
+            const encryptedWithTag = await this._crypto.subtle.encrypt({
+                name: 'AES-GCM',
+                iv: iv,
+                tagLength: CryptoConstants.GCM_AUTH_TAG_SIZE * 8 // bits
+            }, cryptoKey, plaintextBytes);
+            // Split ciphertext and auth tag (auth tag is last 16 bytes)
+            const encryptedArray = new Uint8Array(encryptedWithTag);
+            const encryptedData = encryptedArray.slice(0, encryptedArray.length - CryptoConstants.GCM_AUTH_TAG_SIZE);
+            const authTag = encryptedArray.slice(encryptedArray.length - CryptoConstants.GCM_AUTH_TAG_SIZE);
+            return ts_utils_1.Success.with({
+                iv,
+                authTag,
+                encryptedData
+            });
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return ts_utils_1.Failure.with(`Encryption failed: ${message}`);
+        }
+    }
+    /**
+     * 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.
+     */
+    async decrypt(encryptedData, key, iv, authTag) {
+        if (key.length !== CryptoConstants.AES_256_KEY_SIZE) {
+            return ts_utils_1.Failure.with(`Key must be ${CryptoConstants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+        }
+        if (iv.length !== CryptoConstants.GCM_IV_SIZE) {
+            return ts_utils_1.Failure.with(`IV must be ${CryptoConstants.GCM_IV_SIZE} bytes, got ${iv.length}`);
+        }
+        if (authTag.length !== CryptoConstants.GCM_AUTH_TAG_SIZE) {
+            return ts_utils_1.Failure.with(`Auth tag must be ${CryptoConstants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`);
+        }
+        try {
+            // Import the key
+            const cryptoKey = await this._crypto.subtle.importKey('raw', toArrayBuffer(key), { name: 'AES-GCM' }, false, ['decrypt']);
+            // Web Crypto expects ciphertext + auth tag concatenated
+            const encryptedWithTag = new Uint8Array(encryptedData.length + authTag.length);
+            encryptedWithTag.set(encryptedData);
+            encryptedWithTag.set(authTag, encryptedData.length);
+            // Decrypt
+            const decrypted = await this._crypto.subtle.decrypt({
+                name: 'AES-GCM',
+                iv: toArrayBuffer(iv),
+                tagLength: CryptoConstants.GCM_AUTH_TAG_SIZE * 8 // bits
+            }, cryptoKey, encryptedWithTag);
+            // Decode to string
+            const decoder = new TextDecoder();
+            return ts_utils_1.Success.with(decoder.decode(decrypted));
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return ts_utils_1.Failure.with(`Decryption failed: ${message}`);
+        }
+    }
+    /**
+     * Generates a random 32-byte key suitable for AES-256.
+     * @returns Success with generated key, or Failure with error
+     */
+    async generateKey() {
+        try {
+            return ts_utils_1.Success.with(this._crypto.getRandomValues(new Uint8Array(CryptoConstants.AES_256_KEY_SIZE)));
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return ts_utils_1.Failure.with(`Key generation failed: ${message}`);
+        }
+    }
+    /**
+     * 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
+     */
+    async deriveKey(password, salt, iterations) {
+        if (iterations < 1) {
+            return ts_utils_1.Failure.with('Iterations must be at least 1');
+        }
+        if (salt.length < 8) {
+            return ts_utils_1.Failure.with('Salt should be at least 8 bytes');
+        }
+        try {
+            // Encode password
+            const encoder = new TextEncoder();
+            const passwordBytes = encoder.encode(password);
+            // Import password as key material
+            const keyMaterial = await this._crypto.subtle.importKey('raw', passwordBytes, 'PBKDF2', false, [
+                'deriveBits'
+            ]);
+            // Derive key bits
+            const derivedBits = await this._crypto.subtle.deriveBits({
+                name: 'PBKDF2',
+                salt: toArrayBuffer(salt),
+                iterations: iterations,
+                hash: 'SHA-256'
+            }, keyMaterial, CryptoConstants.AES_256_KEY_SIZE * 8 // bits
+            );
+            return ts_utils_1.Success.with(new Uint8Array(derivedBits));
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return ts_utils_1.Failure.with(`Key derivation failed: ${message}`);
+        }
+    }
+    // ============================================================================
+    // Platform Utility Methods
+    // ============================================================================
+    /**
+     * Generates cryptographically secure random bytes.
+     * @param length - Number of bytes to generate
+     * @returns Success with random bytes, or Failure with error
+     */
+    generateRandomBytes(length) {
+        if (length < 1) {
+            return ts_utils_1.Failure.with('Length must be at least 1');
+        }
+        try {
+            return ts_utils_1.Success.with(this._crypto.getRandomValues(new Uint8Array(length)));
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return ts_utils_1.Failure.with(`Random bytes generation failed: ${message}`);
+        }
+    }
+    /**
+     * Encodes binary data to base64 string.
+     * @param data - Binary data to encode
+     * @returns Base64-encoded string
+     */
+    toBase64(data) {
+        // Convert Uint8Array to binary string, then to base64
+        let binary = '';
+        for (let i = 0; i < data.length; i++) {
+            binary += String.fromCharCode(data[i]);
+        }
+        return btoa(binary);
+    }
+    /**
+     * Decodes base64 string to binary data.
+     * @param base64 - Base64-encoded string
+     * @returns Success with decoded bytes, or Failure if invalid base64
+     */
+    fromBase64(base64) {
+        try {
+            const binary = atob(base64);
+            const bytes = new Uint8Array(binary.length);
+            for (let i = 0; i < binary.length; i++) {
+                bytes[i] = binary.charCodeAt(i);
+            }
+            return ts_utils_1.Success.with(bytes);
+        }
+        catch (e) {
+            return ts_utils_1.Failure.with('Invalid base64 string');
+        }
+    }
+}
+exports.BrowserCryptoProvider = BrowserCryptoProvider;
+/**
+ * Creates a {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider} if Web
+ * Crypto API is available.
+ * @returns `Success` with provider, or `Failure` if not available
+ * @public
+ */
+function createBrowserCryptoProvider() {
+    return (0, ts_utils_1.captureResult)(() => new BrowserCryptoProvider());
+}
+/* c8 ignore stop */
+//# sourceMappingURL=browserCryptoProvider.js.map