@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/runtime/browser.d.ts

@@ -0,0 +1,311 @@
+/**
+ * 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 type { Result } from '@private.me/shared';
+/**
+ * Runtime environment type.
+ */
+export type RuntimeEnvironment = 'browser' | 'node' | 'service-worker' | 'web-worker' | 'unknown';
+/**
+ * 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 declare function detectRuntime(): RuntimeEnvironment;
+/**
+ * Check if running in a browser environment.
+ *
+ * @returns True if running in browser, service worker, or web worker
+ */
+export declare function isBrowser(): boolean;
+/**
+ * Check if running in Node.js environment.
+ *
+ * @returns True if running in Node.js
+ */
+export declare function isNode(): boolean;
+/**
+ * Check if running in a service worker.
+ *
+ * @returns True if running in service worker context
+ */
+export declare function isServiceWorker(): boolean;
+/**
+ * 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 declare function getRandomBytes(length: number): Uint8Array;
+/**
+ * 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 declare function generateUUID(): string;
+/**
+ * Browser storage interface for persisting agent identity and state.
+ */
+export interface BrowserStorage {
+    /**
+     * Store a value.
+     * @param key - Storage key
+     * @param value - Value to store (will be JSON serialized)
+     */
+    setItem(key: string, value: unknown): Promise<void>;
+    /**
+     * Retrieve a value.
+     * @param key - Storage key
+     * @returns Stored value or null if not found
+     */
+    getItem<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Remove a value.
+     * @param key - Storage key
+     */
+    removeItem(key: string): Promise<void>;
+    /**
+     * Clear all stored values.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * LocalStorage-based implementation of BrowserStorage.
+ * Suitable for browser environments with persistent storage needs.
+ */
+export declare class LocalStorageAdapter implements BrowserStorage {
+    private prefix;
+    /**
+     * Create a new LocalStorage adapter.
+     *
+     * @param prefix - Key prefix to avoid collisions (default: 'xbind:')
+     */
+    constructor(prefix?: string);
+    setItem(key: string, value: unknown): Promise<void>;
+    getItem<T = unknown>(key: string): Promise<T | null>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * IndexedDB-based implementation of BrowserStorage.
+ * Suitable for larger datasets and service workers.
+ */
+export declare class IndexedDBAdapter implements BrowserStorage {
+    private dbName;
+    private storeName;
+    private version;
+    private db;
+    /**
+     * 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?: string, storeName?: string, version?: number);
+    /**
+     * Initialize the database connection.
+     * Called automatically by storage operations.
+     */
+    private ensureDB;
+    setItem(key: string, value: unknown): Promise<void>;
+    getItem<T = unknown>(key: string): Promise<T | null>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Close the database connection.
+     * Should be called when storage is no longer needed.
+     */
+    close(): void;
+}
+/**
+ * In-memory storage implementation for testing and ephemeral use cases.
+ */
+export declare class MemoryStorageAdapter implements BrowserStorage {
+    private store;
+    setItem(key: string, value: unknown): Promise<void>;
+    getItem<T = unknown>(key: string): Promise<T | null>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Error codes for WASM operations.
+ */
+export type WasmError = 'WASM_NOT_SUPPORTED' | 'WASM_LOAD_FAILED' | 'WASM_INIT_FAILED';
+/**
+ * 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 declare function isWasmSupported(): boolean;
+/**
+ * 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 declare function loadWasmModule(url: string, importObject?: WebAssembly.Imports): Promise<Result<WebAssembly.Instance, WasmError>>;
+/**
+ * Browser capabilities and feature support.
+ */
+export interface BrowserCapabilities {
+    /** WebCrypto API available */
+    webCrypto: boolean;
+    /** SubtleCrypto API available */
+    subtleCrypto: boolean;
+    /** Ed25519 support in WebCrypto */
+    ed25519: boolean;
+    /** X25519 support in WebCrypto */
+    x25519: boolean;
+    /** WebAssembly support */
+    wasm: boolean;
+    /** IndexedDB support */
+    indexedDB: boolean;
+    /** LocalStorage support */
+    localStorage: boolean;
+    /** Service Worker support */
+    serviceWorker: boolean;
+    /** Web Worker support */
+    webWorker: boolean;
+    /** Fetch API support */
+    fetch: boolean;
+    /** TextEncoder/TextDecoder support */
+    textEncoding: boolean;
+}
+/**
+ * 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 declare function detectCapabilities(): Promise<BrowserCapabilities>;
+/**
+ * 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 declare function installNodePolyfills(): void;
+/**
+ * Configuration for service worker compatibility mode.
+ */
+export interface ServiceWorkerConfig {
+    /** Cache strategy for WASM modules */
+    wasmCacheStrategy: 'cache-first' | 'network-first' | 'no-cache';
+    /** Maximum age for cached WASM modules (milliseconds) */
+    wasmCacheMaxAge: number;
+    /** Enable background sync for pending messages */
+    enableBackgroundSync: boolean;
+}
+/**
+ * Default service worker configuration.
+ */
+export declare const DEFAULT_SERVICE_WORKER_CONFIG: ServiceWorkerConfig;
+/**
+ * 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 declare function initServiceWorker(config?: Partial<ServiceWorkerConfig>): void;
+export type { Result, };