@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/runtime/browser.js

@@ -1 +1,516 @@
-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)}
+/**
+ * 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);
+}