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

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

@@ -4,18 +4,70 @@
 
 ```ts
 
+import { CryptoUtils as CryptoUtils_2 } from '@fgv/ts-extras';
+import { DetailedResult } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-json-base';
+import { Logging } from '@fgv/ts-utils';
 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 +86,10 @@ 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 createFromHttp<TCT extends string = string>(params: IHttpTreeParams<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 +104,19 @@ 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);
+    deleteFile(path: string): Result<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)
@@ -162,6 +231,18 @@ function fromFileList(fileList: FileList, params?: FileTree.IFileTreeInitParams<
 // @public
 function getOriginalFile(fileList: FileList, path: string): Result<File>;
 
+// @public
+export class HttpTreeAccessors<TCT extends string = string> extends FileTree.InMemoryTreeAccessors<TCT> implements FileTree.IPersistentFileTreeAccessors<TCT> {
+    // (undocumented)
+    deleteFile(path: string): Result<boolean>;
+    fileIsMutable(path: string): DetailedResult<boolean, FileTree.SaveDetail>;
+    static fromHttp<TCT extends string = string>(params: IHttpTreeParams<TCT>): Promise<Result<HttpTreeAccessors<TCT>>>;
+    getDirtyPaths(): string[];
+    isDirty(): boolean;
+    saveFileContents(path: string, contents: string): Result<string>;
+    syncToDisk(): Promise<Result<void>>;
+}
+
 // @public
 export interface IDirectoryHandleTreeInitializer {
     // (undocumented)
@@ -200,6 +281,14 @@ export interface IFileMetadata {
     type: string;
 }
 
+// @public
+export interface IFileSystemAccessTreeParams<TCT extends string = string> extends FileTree.IFileTreeInitParams<TCT> {
+    autoSync?: boolean;
+    filePath?: string;
+    logger?: Logging.LogReporter<unknown>;
+    requireWritePermission?: boolean;
+}
+
 // @public
 export interface IFsAccessApis {
     // (undocumented)
@@ -210,6 +299,29 @@ export interface IFsAccessApis {
     showSaveFilePicker(options?: ShowSaveFilePickerOptions): Promise<FileSystemFileHandle_2>;
 }
 
+// @public
+export interface IHttpTreeParams<TCT extends string = string> extends FileTree.IFileTreeInitParams<TCT> {
+    // (undocumented)
+    readonly autoSync?: boolean;
+    // (undocumented)
+    readonly baseUrl: string;
+    // (undocumented)
+    readonly fetchImpl?: typeof fetch;
+    // (undocumented)
+    readonly logger?: Logging.LogReporter<unknown>;
+    // (undocumented)
+    readonly namespace?: string;
+    // (undocumented)
+    readonly userId?: string;
+}
+
+// @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 +348,17 @@ export interface IUrlConfigOptions {
     zipPath?: string;
 }
 
+// @public
+export class LocalStorageTreeAccessors<TCT extends string = string> extends FileTree.InMemoryTreeAccessors<TCT> implements FileTree.IPersistentFileTreeAccessors<TCT> {
+    deleteFile(path: string): Result<boolean>;
+    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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"browserHashProvider.d.ts","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/browserHashProvider.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,MAAM,EAAiB,MAAM,eAAe,CAAC;AAEtD;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B;;;;;OAKG;WACiB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAqBpG;;;;;;OAMG;WACiB,SAAS,CAC3B,KAAK,EAAE,MAAM,EAAE,EACf,SAAS,GAAE,MAAkB,EAC7B,SAAS,GAAE,MAAY,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;CAI3B"}

package/lib/packlets/crypto-utils/browserHashProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserHashProvider.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/browserHashProvider.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,4CAAsD;AAEtD;;;;GAIG;AACH,MAAa,mBAAmB;IAC9B;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,IAAY,EAAE,YAAoB,SAAS;QACxE,IAAI,CAAC;YACH,yCAAyC;YACzC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;gBACnB,OAAO,IAAA,eAAI,EAAC,kDAAkD,CAAC,CAAC;YAClE,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;YAClC,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACxC,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;YACrE,MAAM,SAAS,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;YAC7C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;iBAClC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;iBAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;YAEZ,OAAO,IAAA,kBAAO,EAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,IAAA,eAAI,EAAC,4BAA4B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACpG,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,CAAC,SAAS,CAC3B,KAAe,EACf,YAAoB,SAAS,EAC7B,YAAoB,GAAG;QAEvB,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;CACF;AA3CD,kDA2CC","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\nimport { Result, succeed, fail } from '@fgv/ts-utils';\n\n/**\n * Browser-compatible hash provider using the Web Crypto API.\n * Supports common hash algorithms available in browsers.\n * @public\n */\nexport class BrowserHashProvider {\n  /**\n   * Hash a string using the specified algorithm.\n   * @param data - The string to hash\n   * @param algorithm - The hash algorithm to use\n   * @returns Promise resolving to the hex-encoded hash\n   */\n  public static async hashString(data: string, algorithm: string = 'SHA-256'): Promise<Result<string>> {\n    try {\n      /* c8 ignore next 3 - defense in depth */\n      if (!crypto.subtle) {\n        return fail('Web Crypto API not available in this environment');\n      }\n\n      const encoder = new TextEncoder();\n      const dataBuffer = encoder.encode(data);\n      const hashBuffer = await crypto.subtle.digest(algorithm, dataBuffer);\n      const hashArray = new Uint8Array(hashBuffer);\n      const hashHex = Array.from(hashArray)\n        .map((b) => b.toString(16).padStart(2, '0'))\n        .join('');\n\n      return succeed(hashHex);\n    } catch (error) {\n      return fail(`Hash computation failed: ${error instanceof Error ? error.message : String(error)}`);\n    }\n  }\n\n  /**\n   * Hash multiple strings concatenated with a separator.\n   * @param parts - Array of strings to concatenate and hash\n   * @param algorithm - The hash algorithm to use\n   * @param separator - Separator to use between parts (default: '|')\n   * @returns Promise resolving to the hex-encoded hash\n   */\n  public static async hashParts(\n    parts: string[],\n    algorithm: string = 'SHA-256',\n    separator: string = '|'\n  ): Promise<Result<string>> {\n    const combined = parts.join(separator);\n    return this.hashString(combined, algorithm);\n  }\n}\n"]}