@private.me/xbind 3.0.2 → 3.0.3

package/dist-standalone/runtime/browser.js

@@ -1,516 +1 @@
-/**
- * Browser Runtime Compatibility Layer
- *
- * Provides polyfills and runtime detection for browser environments.
- * Ensures xBind works seamlessly in Chrome, Firefox, Safari, and service workers.
- *
- * @module runtime/browser
- * @packageDocumentation
- */
-import { ok, err } from"../_deps/shared/index.js";
-/**
- * Detect the current runtime environment.
- *
- * @returns The detected runtime environment type
- *
- * @example
- * ```typescript
- * import { detectRuntime } from '@private.me/xbind/runtime/browser';
- *
- * const runtime = detectRuntime();
- * console.log('Running in:', runtime);
- * // => 'browser' | 'node' | 'service-worker' | 'web-worker' | 'unknown'
- * ```
- */
-export function detectRuntime() {
-    // Service Worker context
-    if (typeof self !== 'undefined' && 'ServiceWorkerGlobalScope' in self) {
-        return 'service-worker';
-    }
-    // Web Worker context
-    if (typeof self !== 'undefined' && 'WorkerGlobalScope' in self && 'importScripts' in self) {
-        return 'web-worker';
-    }
-    // Browser context (window and document available)
-    if (typeof window !== 'undefined' && typeof document !== 'undefined') {
-        return 'browser';
-    }
-    // Node.js context (process and global available)
-    if (typeof process !== 'undefined' && process.versions && process.versions.node) {
-        return 'node';
-    }
-    return 'unknown';
-}
-/**
- * Check if running in a browser environment.
- *
- * @returns True if running in browser, service worker, or web worker
- */
-export function isBrowser() {
-    const runtime = detectRuntime();
-    return runtime === 'browser' || runtime === 'service-worker' || runtime === 'web-worker';
-}
-/**
- * Check if running in Node.js environment.
- *
- * @returns True if running in Node.js
- */
-export function isNode() {
-    return detectRuntime() === 'node';
-}
-/**
- * Check if running in a service worker.
- *
- * @returns True if running in service worker context
- */
-export function isServiceWorker() {
-    return detectRuntime() === 'service-worker';
-}
-/* ── Crypto Compatibility ── */
-/**
- * Browser-compatible random bytes generator.
- * Uses Web Crypto API's getRandomValues.
- *
- * @param length - Number of random bytes to generate
- * @returns Uint8Array of cryptographically secure random bytes
- *
- * @throws {Error} If Web Crypto API is not available
- *
- * @example
- * ```typescript
- * import { getRandomBytes } from '@private.me/xbind/runtime/browser';
- *
- * const nonce = getRandomBytes(16);
- * console.log('Random nonce:', nonce);
- * ```
- */
-export function getRandomBytes(length) {
-    if (typeof crypto === 'undefined' || !crypto.getRandomValues) {
-        throw new Error('Web Crypto API not available - secure random generation impossible');
-    }
-    const bytes = new Uint8Array(length);
-    crypto.getRandomValues(bytes);
-    return bytes;
-}
-/**
- * Generate a cryptographically secure random UUID.
- * Uses Web Crypto API's randomUUID if available, falls back to manual generation.
- *
- * @returns UUID v4 string (e.g., "550e8400-e29b-41d4-a716-446655440000")
- *
- * @example
- * ```typescript
- * import { generateUUID } from '@private.me/xbind/runtime/browser';
- *
- * const id = generateUUID();
- * console.log('Generated UUID:', id);
- * ```
- */
-export function generateUUID() {
-    // Use native randomUUID if available (modern browsers)
-    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
-        return crypto.randomUUID();
-    }
-    // Fallback: manual UUID v4 generation
-    const bytes = getRandomBytes(16);
-    // Set version (4) and variant (RFC 4122)
-    const byte6 = bytes[6];
-    const byte8 = bytes[8];
-    if (byte6 !== undefined)
-        bytes[6] = (byte6 & 0x0f) | 0x40; // Version 4
-    if (byte8 !== undefined)
-        bytes[8] = (byte8 & 0x3f) | 0x80; // Variant 10
-    // Format as UUID string
-    const hex = Array.from(bytes)
-        .map(b => b.toString(16).padStart(2, '0'))
-        .join('');
-    return [
-        hex.slice(0, 8),
-        hex.slice(8, 12),
-        hex.slice(12, 16),
-        hex.slice(16, 20),
-        hex.slice(20, 32),
-    ].join('-');
-}
-/**
- * LocalStorage-based implementation of BrowserStorage.
- * Suitable for browser environments with persistent storage needs.
- */
-export class LocalStorageAdapter {
-    prefix;
-    /**
-     * Create a new LocalStorage adapter.
-     *
-     * @param prefix - Key prefix to avoid collisions (default: 'xbind:')
-     */
-    constructor(prefix = 'xbind:') {
-        this.prefix = prefix;
-        if (typeof localStorage === 'undefined') {
-            throw new Error('localStorage not available in this environment');
-        }
-    }
-    async setItem(key, value) {
-        const fullKey = this.prefix + key;
-        const serialized = JSON.stringify(value);
-        localStorage.setItem(fullKey, serialized);
-    }
-    async getItem(key) {
-        const fullKey = this.prefix + key;
-        const raw = localStorage.getItem(fullKey);
-        if (raw === null) {
-            return null;
-        }
-        try {
-            return JSON.parse(raw);
-        }
-        catch {
-            return null;
-        }
-    }
-    async removeItem(key) {
-        const fullKey = this.prefix + key;
-        localStorage.removeItem(fullKey);
-    }
-    async clear() {
-        const keys = Object.keys(localStorage).filter(k => k.startsWith(this.prefix));
-        keys.forEach(k => localStorage.removeItem(k));
-    }
-}
-/**
- * IndexedDB-based implementation of BrowserStorage.
- * Suitable for larger datasets and service workers.
- */
-export class IndexedDBAdapter {
-    dbName;
-    storeName;
-    version;
-    db = null;
-    /**
-     * Create a new IndexedDB adapter.
-     *
-     * @param dbName - Database name (default: 'xbind-storage')
-     * @param storeName - Object store name (default: 'keyval')
-     * @param version - Database version (default: 1)
-     */
-    constructor(dbName = 'xbind-storage', storeName = 'keyval', version = 1) {
-        this.dbName = dbName;
-        this.storeName = storeName;
-        this.version = version;
-    }
-    /**
-     * Initialize the database connection.
-     * Called automatically by storage operations.
-     */
-    async ensureDB() {
-        if (this.db) {
-            return this.db;
-        }
-        return new Promise((resolve, reject) => {
-            const request = indexedDB.open(this.dbName, this.version);
-            request.onerror = () => reject(request.error);
-            request.onsuccess = () => {
-                this.db = request.result;
-                resolve(request.result);
-            };
-            request.onupgradeneeded = (event) => {
-                const db = event.target.result;
-                if (!db.objectStoreNames.contains(this.storeName)) {
-                    db.createObjectStore(this.storeName);
-                }
-            };
-        });
-    }
-    async setItem(key, value) {
-        const db = await this.ensureDB();
-        const tx = db.transaction(this.storeName, 'readwrite');
-        const store = tx.objectStore(this.storeName);
-        return new Promise((resolve, reject) => {
-            const request = store.put(value, key);
-            request.onerror = () => reject(request.error);
-            request.onsuccess = () => resolve();
-        });
-    }
-    async getItem(key) {
-        const db = await this.ensureDB();
-        const tx = db.transaction(this.storeName, 'readonly');
-        const store = tx.objectStore(this.storeName);
-        return new Promise((resolve, reject) => {
-            const request = store.get(key);
-            request.onerror = () => reject(request.error);
-            request.onsuccess = () => {
-                const value = request.result;
-                resolve(value === undefined ? null : value);
-            };
-        });
-    }
-    async removeItem(key) {
-        const db = await this.ensureDB();
-        const tx = db.transaction(this.storeName, 'readwrite');
-        const store = tx.objectStore(this.storeName);
-        return new Promise((resolve, reject) => {
-            const request = store.delete(key);
-            request.onerror = () => reject(request.error);
-            request.onsuccess = () => resolve();
-        });
-    }
-    async clear() {
-        const db = await this.ensureDB();
-        const tx = db.transaction(this.storeName, 'readwrite');
-        const store = tx.objectStore(this.storeName);
-        return new Promise((resolve, reject) => {
-            const request = store.clear();
-            request.onerror = () => reject(request.error);
-            request.onsuccess = () => resolve();
-        });
-    }
-    /**
-     * Close the database connection.
-     * Should be called when storage is no longer needed.
-     */
-    close() {
-        if (this.db) {
-            this.db.close();
-            this.db = null;
-        }
-    }
-}
-/**
- * In-memory storage implementation for testing and ephemeral use cases.
- */
-export class MemoryStorageAdapter {
-    store = new Map();
-    async setItem(key, value) {
-        this.store.set(key, value);
-    }
-    async getItem(key) {
-        const value = this.store.get(key);
-        return value === undefined ? null : value;
-    }
-    async removeItem(key) {
-        this.store.delete(key);
-    }
-    async clear() {
-        this.store.clear();
-    }
-}
-/**
- * Check if WebAssembly is supported in the current environment.
- *
- * @returns True if WebAssembly is supported
- *
- * @example
- * ```typescript
- * import { isWasmSupported } from '@private.me/xbind/runtime/browser';
- *
- * if (isWasmSupported()) {
- *   console.log('WASM is supported - using post-quantum crypto');
- * } else {
- *   console.log('WASM not supported - falling back to classical crypto');
- * }
- * ```
- */
-export function isWasmSupported() {
-    try {
-        if (typeof WebAssembly === 'undefined') {
-            return false;
-        }
-        // Test instantiation with minimal WASM module
-        const module = new WebAssembly.Module(new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]));
-        if (!(module instanceof WebAssembly.Module)) {
-            return false;
-        }
-        const instance = new WebAssembly.Instance(module);
-        return instance instanceof WebAssembly.Instance;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Load and instantiate a WebAssembly module from a URL.
- *
- * @param url - URL to WASM module
- * @param importObject - Optional imports for WASM module
- * @returns Result containing the WASM instance or error
- *
- * @example
- * ```typescript
- * import { loadWasmModule } from '@private.me/xbind/runtime/browser';
- *
- * const result = await loadWasmModule('/mldsa.wasm');
- * if (!result.ok) {
- *   console.error('Failed to load WASM:', result.error);
- *   return;
- * }
- *
- * const instance = result.value;
- * // Use WASM exports...
- * ```
- */
-export async function loadWasmModule(url, importObject) {
-    if (!isWasmSupported()) {
-        return err('WASM_NOT_SUPPORTED');
-    }
-    try {
-        // Use streaming compilation if available (faster)
-        if (typeof WebAssembly.instantiateStreaming !== 'undefined') {
-            const response = await fetch(url);
-            const result = await WebAssembly.instantiateStreaming(response, importObject);
-            return ok(result.instance);
-        }
-        // Fallback: fetch as ArrayBuffer then compile
-        const response = await fetch(url);
-        const buffer = await response.arrayBuffer();
-        const result = await WebAssembly.instantiate(buffer, importObject);
-        return ok(result.instance);
-    }
-    catch (error) {
-        console.error('WASM load failed:', error);
-        return err('WASM_LOAD_FAILED');
-    }
-}
-/**
- * Detect browser capabilities and feature support.
- *
- * @returns Object describing available browser features
- *
- * @example
- * ```typescript
- * import { detectCapabilities } from '@private.me/xbind/runtime/browser';
- *
- * const caps = await detectCapabilities();
- *
- * if (!caps.webCrypto) {
- *   throw new Error('WebCrypto required for xBind');
- * }
- *
- * if (!caps.ed25519) {
- *   console.warn('Ed25519 not supported - using polyfill');
- * }
- *
- * if (caps.serviceWorker) {
- *   console.log('Service workers supported - can run in background');
- * }
- * ```
- */
-export async function detectCapabilities() {
-    // Basic feature detection
-    const capabilities = {
-        webCrypto: typeof crypto !== 'undefined' && !!crypto.subtle,
-        subtleCrypto: typeof crypto !== 'undefined' && !!crypto.subtle,
-        ed25519: false,
-        x25519: false,
-        wasm: isWasmSupported(),
-        indexedDB: typeof indexedDB !== 'undefined',
-        localStorage: typeof localStorage !== 'undefined',
-        serviceWorker: typeof navigator !== 'undefined' && 'serviceWorker' in navigator,
-        webWorker: typeof Worker !== 'undefined',
-        fetch: typeof fetch !== 'undefined',
-        textEncoding: typeof TextEncoder !== 'undefined' && typeof TextDecoder !== 'undefined',
-    };
-    // Test Ed25519 support (async)
-    if (capabilities.subtleCrypto) {
-        try {
-            await crypto.subtle.generateKey({ name: 'Ed25519' }, true, ['sign', 'verify']);
-            capabilities.ed25519 = true;
-        }
-        catch {
-            capabilities.ed25519 = false;
-        }
-    }
-    // Test X25519 support (async)
-    if (capabilities.subtleCrypto) {
-        try {
-            await crypto.subtle.generateKey({ name: 'X25519' }, true, ['deriveBits']);
-            capabilities.x25519 = true;
-        }
-        catch {
-            capabilities.x25519 = false;
-        }
-    }
-    return capabilities;
-}
-/* ── Polyfills ── */
-/**
- * Install Node.js compatibility shims for browser environments.
- * Only installs missing APIs - does not override existing implementations.
- *
- * @example
- * ```typescript
- * import { installNodePolyfills } from '@private.me/xbind/runtime/browser';
- *
- * // Install polyfills at application startup
- * installNodePolyfills();
- *
- * // Now Node.js-style code works in browser
- * import { randomBytes } from 'crypto'; // Works!
- * ```
- */
-export function installNodePolyfills() {
-    // Only install in browser environments
-    if (!isBrowser()) {
-        return;
-    }
-    // Polyfill process.env
-    if (typeof globalThis.process === 'undefined') {
-        globalThis.process = {
-            env: {},
-            versions: {},
-            nextTick: (fn) => Promise.resolve().then(fn),
-        };
-    }
-    // Polyfill Buffer (minimal implementation)
-    if (typeof globalThis.Buffer === 'undefined') {
-        globalThis.Buffer = {
-            from: (data, encoding) => {
-                if (data instanceof Uint8Array)
-                    return data;
-                if (encoding === 'base64') {
-                    const binary = atob(data);
-                    return new Uint8Array(binary.split('').map(c => c.charCodeAt(0)));
-                }
-                return new TextEncoder().encode(data);
-            },
-            alloc: (size) => new Uint8Array(size),
-        };
-    }
-    // Polyfill global
-    if (typeof globalThis.global === 'undefined') {
-        globalThis.global = globalThis;
-    }
-}
-/**
- * Default service worker configuration.
- */
-export const DEFAULT_SERVICE_WORKER_CONFIG = {
-    wasmCacheStrategy: 'cache-first',
-    wasmCacheMaxAge: 24 * 60 * 60 * 1000, // 24 hours
-    enableBackgroundSync: true,
-};
-/**
- * Initialize xBind for service worker environment.
- * Sets up caching strategies and background sync handlers.
- *
- * @param config - Service worker configuration
- *
- * @example
- * ```typescript
- * // In your service worker (sw.js):
- * import { initServiceWorker } from '@private.me/xbind/runtime/browser';
- *
- * initServiceWorker({
- *   wasmCacheStrategy: 'cache-first',
- *   wasmCacheMaxAge: 24 * 60 * 60 * 1000,
- *   enableBackgroundSync: true,
- * });
- * ```
- */
-export function initServiceWorker(config = {}) {
-    const fullConfig = { ...DEFAULT_SERVICE_WORKER_CONFIG, ...config };
-    if (!isServiceWorker()) {
-        throw new Error('initServiceWorker() must be called from service worker context');
-    }
-    // Store config for use by other service worker handlers
-    self.__xbind_sw_config = fullConfig;
-    console.log('[xBind] Service worker initialized with config:', fullConfig);
-}
+import{ok,err}from"../_deps/shared/index.js";export function detectRuntime(){return"undefined"!=typeof self&&"ServiceWorkerGlobalScope"in self?"service-worker":"undefined"!=typeof self&&"WorkerGlobalScope"in self&&"importScripts"in self?"web-worker":"undefined"!=typeof window&&"undefined"!=typeof document?"browser":"undefined"!=typeof process&&process.versions&&process.versions.node?"node":"unknown"}export function isBrowser(){const e=detectRuntime();return"browser"===e||"service-worker"===e||"web-worker"===e}export function isNode(){return"node"===detectRuntime()}export function isServiceWorker(){return"service-worker"===detectRuntime()}export function getRandomBytes(e){if("undefined"==typeof crypto||!crypto.getRandomValues)throw new Error("Web Crypto API not available - secure random generation impossible");const t=new Uint8Array(e);return crypto.getRandomValues(t),t}export function generateUUID(){if("undefined"!=typeof crypto&&crypto.randomUUID)return crypto.randomUUID();const e=getRandomBytes(16),t=e[6],r=e[8];void 0!==t&&(e[6]=15&t|64),void 0!==r&&(e[8]=63&r|128);const o=Array.from(e).map(e=>e.toString(16).padStart(2,"0")).join("");return[o.slice(0,8),o.slice(8,12),o.slice(12,16),o.slice(16,20),o.slice(20,32)].join("-")}export class LocalStorageAdapter{prefix;constructor(e="xbind:"){if(this.prefix=e,"undefined"==typeof localStorage)throw new Error("localStorage not available in this environment")}async setItem(e,t){const r=this.prefix+e,o=JSON.stringify(t);localStorage.setItem(r,o)}async getItem(e){const t=this.prefix+e,r=localStorage.getItem(t);if(null===r)return null;try{return JSON.parse(r)}catch{return null}}async removeItem(e){const t=this.prefix+e;localStorage.removeItem(t)}async clear(){Object.keys(localStorage).filter(e=>e.startsWith(this.prefix)).forEach(e=>localStorage.removeItem(e))}}export class IndexedDBAdapter{dbName;storeName;version;db=null;constructor(e="xbind-storage",t="keyval",r=1){this.dbName=e,this.storeName=t,this.version=r}async ensureDB(){return this.db?this.db:new Promise((e,t)=>{const r=indexedDB.open(this.dbName,this.version);r.onerror=()=>t(r.error),r.onsuccess=()=>{this.db=r.result,e(r.result)},r.onupgradeneeded=e=>{const t=e.target.result;t.objectStoreNames.contains(this.storeName)||t.createObjectStore(this.storeName)}})}async setItem(e,t){const r=(await this.ensureDB()).transaction(this.storeName,"readwrite").objectStore(this.storeName);return new Promise((o,n)=>{const s=r.put(t,e);s.onerror=()=>n(s.error),s.onsuccess=()=>o()})}async getItem(e){const t=(await this.ensureDB()).transaction(this.storeName,"readonly").objectStore(this.storeName);return new Promise((r,o)=>{const n=t.get(e);n.onerror=()=>o(n.error),n.onsuccess=()=>{const e=n.result;r(void 0===e?null:e)}})}async removeItem(e){const t=(await this.ensureDB()).transaction(this.storeName,"readwrite").objectStore(this.storeName);return new Promise((r,o)=>{const n=t.delete(e);n.onerror=()=>o(n.error),n.onsuccess=()=>r()})}async clear(){const e=(await this.ensureDB()).transaction(this.storeName,"readwrite").objectStore(this.storeName);return new Promise((t,r)=>{const o=e.clear();o.onerror=()=>r(o.error),o.onsuccess=()=>t()})}close(){this.db&&(this.db.close(),this.db=null)}}export class MemoryStorageAdapter{store=new Map;async setItem(e,t){this.store.set(e,t)}async getItem(e){const t=this.store.get(e);return void 0===t?null:t}async removeItem(e){this.store.delete(e)}async clear(){this.store.clear()}}export function isWasmSupported(){try{if("undefined"==typeof WebAssembly)return!1;const e=new WebAssembly.Module(new Uint8Array([0,97,115,109,1,0,0,0]));if(!(e instanceof WebAssembly.Module))return!1;return new WebAssembly.Instance(e)instanceof WebAssembly.Instance}catch{return!1}}export async function loadWasmModule(e,t){if(!isWasmSupported())return err("WASM_NOT_SUPPORTED");try{if(void 0!==WebAssembly.instantiateStreaming){const r=await fetch(e),o=await WebAssembly.instantiateStreaming(r,t);return ok(o.instance)}const r=await fetch(e),o=await r.arrayBuffer(),n=await WebAssembly.instantiate(o,t);return ok(n.instance)}catch(e){return console.error("WASM load failed:",e),err("WASM_LOAD_FAILED")}}export async function detectCapabilities(){const e={webCrypto:"undefined"!=typeof crypto&&!!crypto.subtle,subtleCrypto:"undefined"!=typeof crypto&&!!crypto.subtle,ed25519:!1,x25519:!1,wasm:isWasmSupported(),indexedDB:"undefined"!=typeof indexedDB,localStorage:"undefined"!=typeof localStorage,serviceWorker:"undefined"!=typeof navigator&&"serviceWorker"in navigator,webWorker:"undefined"!=typeof Worker,fetch:"undefined"!=typeof fetch,textEncoding:"undefined"!=typeof TextEncoder&&"undefined"!=typeof TextDecoder};if(e.subtleCrypto)try{await crypto.subtle.generateKey({name:"Ed25519"},!0,["sign","verify"]),e.ed25519=!0}catch{e.ed25519=!1}if(e.subtleCrypto)try{await crypto.subtle.generateKey({name:"X25519"},!0,["deriveBits"]),e.x25519=!0}catch{e.x25519=!1}return e}export function installNodePolyfills(){isBrowser()&&(void 0===globalThis.process&&(globalThis.process={env:{},versions:{},nextTick:e=>Promise.resolve().then(e)}),void 0===globalThis.Buffer&&(globalThis.Buffer={from:(e,t)=>{if(e instanceof Uint8Array)return e;if("base64"===t){const t=atob(e);return new Uint8Array(t.split("").map(e=>e.charCodeAt(0)))}return(new TextEncoder).encode(e)},alloc:e=>new Uint8Array(e)}),void 0===globalThis.global&&(globalThis.global=globalThis))}export const DEFAULT_SERVICE_WORKER_CONFIG={wasmCacheStrategy:"cache-first",wasmCacheMaxAge:864e5,enableBackgroundSync:!0};export function initServiceWorker(e={}){const t={...DEFAULT_SERVICE_WORKER_CONFIG,...e};if(!isServiceWorker())throw new Error("initServiceWorker() must be called from service worker context");self.__xbind_sw_config=t,console.log("[xBind] Service worker initialized with config:",t)}