@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/runtime/edge.js

@@ -0,0 +1,511 @@
+/**
+ * Edge Runtime Support for xBind
+ *
+ * Enables xBind to run on edge compute platforms:
+ * - Cloudflare Workers
+ * - Vercel Edge Functions
+ * - Deno Deploy
+ *
+ * Key Features:
+ * - Edge-compatible crypto operations (Web Crypto API only)
+ * - KV storage integration for nonce stores and trust registry
+ * - Size-optimized build (<1MB constraint)
+ * - No Node.js dependencies (no fs, crypto, process)
+ */
+import { ok, err } from"../_deps/shared/index.js";
+/**
+ * Detect the current edge runtime environment.
+ *
+ * Detection order:
+ * 1. Cloudflare Workers: globalThis.caches + EdgeRuntime
+ * 2. Vercel Edge: process.env.VERCEL + EdgeRuntime
+ * 3. Deno Deploy: globalThis.Deno
+ * 4. Node.js: process.versions.node
+ * 5. Unknown: fallback
+ */
+export function detectRuntime() {
+    // SAFETY: Edge runtime detection requires checking for vendor-specific globals
+    const global = globalThis;
+    // Cloudflare Workers: Has global caches API and no process
+    if (typeof global.caches !== 'undefined' &&
+        typeof global.EdgeRuntime === 'string') {
+        return 'cloudflare';
+    }
+    // Vercel Edge: Has EdgeRuntime and process.env.VERCEL
+    if (typeof global.EdgeRuntime === 'string' &&
+        typeof process !== 'undefined' &&
+        process.env?.VERCEL === '1') {
+        return 'vercel';
+    }
+    // Deno Deploy: Has global Deno object
+    if (typeof global.Deno !== 'undefined') {
+        return 'deno';
+    }
+    // Node.js: Has process.versions.node
+    if (typeof process !== 'undefined' &&
+        typeof process.versions?.node === 'string') {
+        return 'node';
+    }
+    return 'unknown';
+}
+/**
+ * Check if the current runtime is an edge environment.
+ */
+export function isEdgeRuntime() {
+    const runtime = detectRuntime();
+    return runtime === 'cloudflare' || runtime === 'vercel' || runtime === 'deno';
+}
+/**
+ * Validate that the runtime supports required Web Crypto APIs.
+ *
+ * Edge runtimes MUST provide:
+ * - crypto.subtle (Ed25519, X25519, AES-GCM, HMAC)
+ * - crypto.getRandomValues()
+ * - TextEncoder/TextDecoder
+ */
+export function validateEdgeRuntime() {
+    // Check Web Crypto API
+    if (typeof globalThis.crypto === 'undefined') {
+        return err('Missing globalThis.crypto');
+    }
+    if (typeof globalThis.crypto.subtle === 'undefined') {
+        return err('Missing crypto.subtle');
+    }
+    if (typeof globalThis.crypto.getRandomValues !== 'function') {
+        return err('Missing crypto.getRandomValues');
+    }
+    // Check required subtle crypto methods
+    const requiredMethods = [
+        'generateKey',
+        'sign',
+        'verify',
+        'encrypt',
+        'decrypt',
+        'deriveBits',
+        'importKey',
+        'exportKey',
+    ];
+    for (const method of requiredMethods) {
+        if (typeof globalThis.crypto.subtle[method] !== 'function') {
+            return err(`Missing crypto.subtle.${method}`);
+        }
+    }
+    // Check TextEncoder/TextDecoder
+    if (typeof globalThis.TextEncoder === 'undefined') {
+        return err('Missing TextEncoder');
+    }
+    if (typeof globalThis.TextDecoder === 'undefined') {
+        return err('Missing TextDecoder');
+    }
+    // Check fetch API
+    if (typeof globalThis.fetch !== 'function') {
+        return err('Missing fetch API');
+    }
+    return ok(undefined);
+}
+/**
+ * Adapter for Cloudflare Workers KV.
+ */
+export class CloudflareKVAdapter {
+    namespace;
+    constructor(namespace) {
+        this.namespace = namespace;
+    }
+    async get(key) {
+        return await this.namespace.get(key);
+    }
+    async put(key, value, ttlSeconds) {
+        const options = ttlSeconds ? { expirationTtl: ttlSeconds } : undefined;
+        await this.namespace.put(key, value, options);
+    }
+    async delete(key) {
+        await this.namespace.delete(key);
+    }
+    async list(prefix, limit) {
+        const result = await this.namespace.list({ prefix, limit });
+        return result.keys.map((k) => k.name);
+    }
+}
+/**
+ * Adapter for Vercel KV (Redis).
+ */
+export class VercelKVAdapter {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async get(key) {
+        return await this.client.get(key);
+    }
+    async put(key, value, ttlSeconds) {
+        const options = ttlSeconds ? { ex: ttlSeconds } : undefined;
+        await this.client.set(key, value, options);
+    }
+    async delete(key) {
+        await this.client.del(key);
+    }
+    async list(prefix, limit) {
+        const pattern = prefix ? `${prefix}*` : '*';
+        const allKeys = await this.client.keys(pattern);
+        return limit ? allKeys.slice(0, limit) : allKeys;
+    }
+}
+/**
+ * Adapter for Deno KV.
+ */
+export class DenoKVAdapter {
+    kv;
+    constructor(kv) {
+        this.kv = kv;
+    }
+    async get(key) {
+        const result = await this.kv.get([key]);
+        return result.value;
+    }
+    async put(key, value, ttlSeconds) {
+        const options = ttlSeconds ? { expireIn: ttlSeconds * 1000 } : undefined;
+        await this.kv.set([key], value, options);
+    }
+    async delete(key) {
+        await this.kv.delete([key]);
+    }
+    async list(prefix, limit) {
+        const selector = { prefix: prefix ? [prefix] : [] };
+        const keys = [];
+        for await (const entry of this.kv.list(selector)) {
+            keys.push(entry.key.join('/'));
+            if (limit && keys.length >= limit)
+                break;
+        }
+        return keys;
+    }
+}
+/* ── KV-Backed Nonce Store ── */
+/**
+ * Nonce store implementation using KV storage.
+ *
+ * Suitable for edge runtimes where in-memory storage
+ * is ephemeral across invocations.
+ */
+export class KVNonceStore {
+    kv;
+    ttlSeconds;
+    constructor(kv, ttlMs = 10 * 60 * 1000) {
+        this.kv = kv;
+        this.ttlSeconds = Math.floor(ttlMs / 1000);
+    }
+    /**
+     * Build composite key: xbind:nonce:{senderDid}:{nonce}:{shareGroupId}:{shareIndex}
+     */
+    buildKey(nonce, senderDid, shareContext) {
+        const base = `xbind:nonce:${senderDid}:${nonce}`;
+        if (!shareContext)
+            return base;
+        const groupId = shareContext.shareGroupId ?? '';
+        const index = shareContext.shareIndex !== undefined ? String(shareContext.shareIndex) : '';
+        return `${base}:${groupId}:${index}`;
+    }
+    async check(nonce, senderDid, shareContext) {
+        const key = this.buildKey(nonce, senderDid, shareContext);
+        const existing = await this.kv.get(key);
+        if (existing !== null) {
+            // Nonce already seen
+            return false;
+        }
+        // Record nonce with TTL
+        await this.kv.put(key, Date.now().toString(), this.ttlSeconds);
+        return true;
+    }
+    cleanup() {
+        // KV stores auto-expire via TTL, no manual cleanup needed
+    }
+    dispose() {
+        // No resources to clean up
+    }
+}
+/* ── KV-Backed Trust Registry ── */
+/**
+ * Trust registry implementation using KV storage.
+ *
+ * Stores DID registrations in edge KV for distributed lookups.
+ * Simplified version suitable for edge runtimes - stores minimal metadata.
+ */
+export class KVTrustRegistry {
+    kv;
+    constructor(kv) {
+        this.kv = kv;
+    }
+    /**
+     * Build key: xbind:trust:{did}
+     */
+    buildKey(did) {
+        return `xbind:trust:${did}`;
+    }
+    async register(did, publicKey, name, scopes, x25519PublicKey, mlKemPublicKey, mlDsaPublicKey, xchange, receiveScopes, sdkVersion, minEnvelopeVersion, maxEnvelopeVersion, ttlMs) {
+        const key = this.buildKey(did);
+        // Convert Uint8Arrays to base64 for JSON storage
+        const toBase64 = (arr) => btoa(String.fromCharCode(...Array.from(arr)));
+        const entry = {
+            did,
+            publicKey: toBase64(publicKey),
+            name,
+            scopes: scopes ?? [],
+            x25519PublicKey: x25519PublicKey ? toBase64(x25519PublicKey) : undefined,
+            mlKemPublicKey: mlKemPublicKey ? toBase64(mlKemPublicKey) : undefined,
+            mlDsaPublicKey: mlDsaPublicKey ? toBase64(mlDsaPublicKey) : undefined,
+            xchange: xchange ?? false,
+            receiveScopes: receiveScopes ?? [],
+            sdkVersion,
+            minEnvelopeVersion,
+            maxEnvelopeVersion,
+            registeredAt: Date.now(),
+            rotation_sequence: 0,
+        };
+        try {
+            const ttlSeconds = ttlMs ? Math.floor(ttlMs / 1000) : undefined;
+            await this.kv.put(key, JSON.stringify(entry), ttlSeconds);
+            return ok(undefined);
+        }
+        catch (e) {
+            return err('NETWORK_ERROR');
+        }
+    }
+    async resolve(did) {
+        const key = this.buildKey(did);
+        try {
+            const value = await this.kv.get(key);
+            if (value === null) {
+                return err('NOT_FOUND');
+            }
+            const entry = JSON.parse(value);
+            // Convert base64 back to Uint8Array
+            const fromBase64 = (b64) => Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+            return ok(fromBase64(entry.publicKey));
+        }
+        catch (e) {
+            return err('NETWORK_ERROR');
+        }
+    }
+    async hasScope(did, scope) {
+        const key = this.buildKey(did);
+        try {
+            const value = await this.kv.get(key);
+            if (value === null)
+                return false;
+            const entry = JSON.parse(value);
+            return entry.scopes?.includes(scope) ?? false;
+        }
+        catch {
+            return false;
+        }
+    }
+    async hasReceiveScope(did, scope) {
+        const key = this.buildKey(did);
+        try {
+            const value = await this.kv.get(key);
+            if (value === null)
+                return false;
+            const entry = JSON.parse(value);
+            return entry.receiveScopes?.includes(scope) ?? false;
+        }
+        catch {
+            return false;
+        }
+    }
+    async revoke(did) {
+        const key = this.buildKey(did);
+        try {
+            await this.kv.delete(key);
+            return ok(undefined);
+        }
+        catch (e) {
+            return err('NETWORK_ERROR');
+        }
+    }
+    async list() {
+        try {
+            const keys = await this.kv.list('xbind:trust:', 1000);
+            return keys.map((k) => k.replace('xbind:trust:', ''));
+        }
+        catch {
+            return [];
+        }
+    }
+    async getEntry(did) {
+        const key = this.buildKey(did);
+        try {
+            const value = await this.kv.get(key);
+            if (value === null) {
+                return err('NOT_FOUND');
+            }
+            const stored = JSON.parse(value);
+            // Convert base64 back to Uint8Array
+            const fromBase64 = (b64) => Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+            const entry = {
+                did: stored.did,
+                publicKey: fromBase64(stored.publicKey),
+                name: stored.name,
+                scopes: new Set(stored.scopes),
+                receiveScopes: stored.receiveScopes ? new Set(stored.receiveScopes) : undefined,
+                revoked: false,
+                x25519PublicKey: stored.x25519PublicKey ? fromBase64(stored.x25519PublicKey) : undefined,
+                mlKemPublicKey: stored.mlKemPublicKey ? fromBase64(stored.mlKemPublicKey) : undefined,
+                mlDsaPublicKey: stored.mlDsaPublicKey ? fromBase64(stored.mlDsaPublicKey) : undefined,
+                xchange: stored.xchange,
+                rotation_sequence: stored.rotation_sequence,
+                sdkVersion: stored.sdkVersion,
+                minEnvelopeVersion: stored.minEnvelopeVersion,
+                maxEnvelopeVersion: stored.maxEnvelopeVersion,
+            };
+            return ok(entry);
+        }
+        catch (e) {
+            return err('NETWORK_ERROR');
+        }
+    }
+    /** Additional methods for edge compatibility */
+    async getFullEntry(did) {
+        const key = this.buildKey(did);
+        try {
+            const value = await this.kv.get(key);
+            if (value === null) {
+                return err('NOT_FOUND');
+            }
+            const entry = JSON.parse(value);
+            return ok(entry);
+        }
+        catch (e) {
+            return err('NETWORK_ERROR');
+        }
+    }
+    dispose() {
+        // No resources to clean up
+    }
+}
+/* ── Edge-Compatible Transport ── */
+/**
+ * Edge-compatible HTTPS transport adapter.
+ *
+ * Uses standard fetch API (available in all edge runtimes).
+ * Optimized for edge constraints:
+ * - No Node.js http/https modules
+ * - No setTimeout (uses AbortSignal.timeout)
+ * - Minimal allocations
+ */
+export class EdgeTransportAdapter {
+    baseUrl;
+    timeoutMs;
+    handlers = [];
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/$/, '');
+        this.timeoutMs = opts.timeoutMs ?? 10_000;
+    }
+    async send(envelope, recipientDid) {
+        const url = `${this.baseUrl}/deliver/${encodeURIComponent(recipientDid)}`;
+        try {
+            // Use AbortSignal.timeout (supported in modern edge runtimes)
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+            const response = await globalThis.fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(envelope),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                return err(response.status === 404 ? 'RECIPIENT_UNREACHABLE' : 'SEND_FAILED');
+            }
+            return ok(undefined);
+        }
+        catch (e) {
+            if (e instanceof DOMException && e.name === 'AbortError') {
+                return err('TIMEOUT');
+            }
+            return err('NETWORK_ERROR');
+        }
+    }
+    onReceive(handler) {
+        this.handlers.push(handler);
+    }
+    /**
+     * Dispatch received envelope to all handlers.
+     * Called by edge function handler when processing incoming requests.
+     */
+    dispatch(envelope) {
+        for (const handler of this.handlers) {
+            handler(envelope);
+        }
+    }
+    dispose() {
+        this.handlers = [];
+    }
+}
+/**
+ * Create edge-compatible xBind components.
+ *
+ * Returns nonce store, trust registry, and transport adapter
+ * configured for the edge runtime.
+ *
+ * @example
+ * ```typescript
+ * // Cloudflare Workers
+ * const kv = new CloudflareKVAdapter(env.XBIND_KV);
+ * const { nonceStore, trustRegistry, transport } = createEdgeAgent({
+ *   kv,
+ *   baseUrl: 'https://private.me/relay',
+ * });
+ *
+ * const agent = new Agent({
+ *   identity: 'persistent',
+ *   nonceStore,
+ *   trustRegistry,
+ *   transport,
+ * });
+ * ```
+ */
+export function createEdgeAgent(opts) {
+    const nonceStore = new KVNonceStore(opts.kv, opts.nonceTtlMs);
+    const trustRegistry = new KVTrustRegistry(opts.kv);
+    const transport = new EdgeTransportAdapter({
+        baseUrl: opts.baseUrl,
+        timeoutMs: opts.timeoutMs,
+    });
+    return {
+        nonceStore,
+        trustRegistry,
+        transport,
+    };
+}
+/* ── Size Optimization Helpers ── */
+/**
+ * Check if the bundled size is within edge runtime limits.
+ *
+ * Cloudflare Workers: 1MB compressed limit
+ * Vercel Edge: 1MB limit
+ * Deno Deploy: 1MB limit
+ */
+export function checkBundleSize(bundleSizeBytes) {
+    const MAX_SIZE_BYTES = 1024 * 1024; // 1MB
+    if (bundleSizeBytes > MAX_SIZE_BYTES) {
+        const sizeMB = (bundleSizeBytes / 1024 / 1024).toFixed(2);
+        const limitMB = (MAX_SIZE_BYTES / 1024 / 1024).toFixed(2);
+        return err(`Bundle size ${sizeMB}MB exceeds edge runtime limit of ${limitMB}MB. ` +
+            `Consider using tree-shaking or dynamic imports.`);
+    }
+    return ok(undefined);
+}
+/**
+ * Get edge-optimized build recommendations.
+ */
+export function getOptimizationTips() {
+    return [
+        '1. Use tree-shaking: Import only required functions',
+        '2. Enable minification in bundler config',
+        '3. Use dynamic imports for large dependencies (mlkem, mldsa)',
+        '4. Exclude Node.js polyfills (crypto, fs, process)',
+        '5. Use Brotli compression for Cloudflare Workers',
+        '6. Consider splitting post-quantum crypto into separate bundle',
+        '7. Use KV storage instead of in-memory caches',
+    ];
+}

package/dist-standalone/runtime/react-native.d.ts

@@ -0,0 +1,157 @@
+/**
+ * React Native Runtime Support for xBind
+ *
+ * Provides compatibility layer for React Native environments:
+ * - Polyfills for missing Node.js APIs
+ * - AsyncStorage adapter for persistence
+ * - Native crypto module integration
+ * - Cross-platform crypto primitives
+ *
+ * @module runtime/react-native
+ */
+import type { Result } from '@private.me/shared';
+/**
+ * React Native AsyncStorage interface
+ */
+export interface AsyncStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    getAllKeys(): Promise<string[]>;
+    multiGet(keys: string[]): Promise<Array<[string, string | null]>>;
+    multiSet(keyValuePairs: Array<[string, string]>): Promise<void>;
+    multiRemove(keys: string[]): Promise<void>;
+}
+/**
+ * React Native crypto capabilities
+ */
+export interface ReactNativeCrypto {
+    getRandomValues(array: Uint8Array): void;
+    subtle?: {
+        digest(algorithm: string, data: BufferSource): Promise<ArrayBuffer>;
+        encrypt(algorithm: AlgorithmIdentifier, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>;
+        decrypt(algorithm: AlgorithmIdentifier, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>;
+        sign(algorithm: AlgorithmIdentifier, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>;
+        verify(algorithm: AlgorithmIdentifier, key: CryptoKey, signature: BufferSource, data: BufferSource): Promise<boolean>;
+        generateKey(algorithm: AlgorithmIdentifier, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKey | CryptoKeyPair>;
+        importKey(format: KeyFormat, keyData: BufferSource | JsonWebKey, algorithm: AlgorithmIdentifier, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKey>;
+        exportKey(format: KeyFormat, key: CryptoKey): Promise<ArrayBuffer | JsonWebKey>;
+    };
+}
+/**
+ * React Native runtime configuration
+ */
+export interface ReactNativeConfig {
+    /**
+     * AsyncStorage instance (required for persistence)
+     */
+    storage: AsyncStorage;
+    /**
+     * Crypto implementation (defaults to global.crypto or react-native-quick-crypto)
+     */
+    crypto?: ReactNativeCrypto;
+    /**
+     * Storage key prefix (prevents collisions)
+     */
+    storagePrefix?: string;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+}
+/**
+ * AsyncStorage adapter for xBind persistence
+ *
+ * Provides cross-platform storage for:
+ * - Agent identities (Ed25519/X25519 keys)
+ * - Nonce store (replay protection)
+ * - Trust registry cache
+ * - Connection metadata
+ */
+export declare class AsyncStorageAdapter {
+    private readonly storage;
+    private readonly prefix;
+    private readonly debug;
+    constructor(config: ReactNativeConfig);
+    /**
+     * Get value by key
+     */
+    get(key: string): Promise<Result<string | null, Error>>;
+    /**
+     * Set key-value pair
+     */
+    set(key: string, value: string): Promise<Result<void, Error>>;
+    /**
+     * Remove key
+     */
+    remove(key: string): Promise<Result<void, Error>>;
+    /**
+     * Get all keys with prefix
+     */
+    keys(): Promise<Result<string[], Error>>;
+    /**
+     * Get multiple keys (batch operation)
+     */
+    multiGet(keys: string[]): Promise<Result<Array<[string, string | null]>, Error>>;
+    /**
+     * Set multiple key-value pairs (batch operation)
+     */
+    multiSet(pairs: Array<[string, string]>): Promise<Result<void, Error>>;
+    /**
+     * Clear all xBind data
+     */
+    clear(): Promise<Result<void, Error>>;
+}
+/**
+ * Detect available crypto implementation
+ */
+export declare function detectCrypto(): ReactNativeCrypto | null;
+/**
+ * Get random bytes (cross-platform)
+ */
+export declare function getRandomBytes(length: number, crypto?: ReactNativeCrypto): Uint8Array;
+/**
+ * SHA-256 hash (cross-platform)
+ */
+export declare function sha256(data: Uint8Array, crypto?: ReactNativeCrypto): Promise<Uint8Array>;
+/**
+ * Buffer polyfill for React Native
+ *
+ * Uses global Buffer if available, otherwise provides minimal implementation
+ */
+export declare class BufferPolyfill {
+    static isBuffer(obj: any): boolean;
+    static from(data: string | Uint8Array | number[], encoding?: string): Uint8Array;
+    static toString(buffer: Uint8Array, encoding?: string): string;
+    static concat(buffers: Uint8Array[]): Uint8Array;
+    static alloc(size: number, fill?: number): Uint8Array;
+    private static fromBase64;
+    private static toBase64;
+    private static fromHex;
+    private static toHex;
+}
+/**
+ * Detect React Native runtime
+ */
+export declare function isReactNative(): boolean;
+/**
+ * Detect platform (iOS/Android)
+ */
+export declare function detectPlatform(): 'ios' | 'android' | 'unknown';
+/**
+ * Initialize React Native runtime environment
+ *
+ * Sets up polyfills and validates required dependencies
+ */
+export declare function initializeReactNative(config: ReactNativeConfig): Result<void, Error>;
+declare const _default: {
+    AsyncStorageAdapter: typeof AsyncStorageAdapter;
+    detectCrypto: typeof detectCrypto;
+    getRandomBytes: typeof getRandomBytes;
+    sha256: typeof sha256;
+    BufferPolyfill: typeof BufferPolyfill;
+    isReactNative: typeof isReactNative;
+    detectPlatform: typeof detectPlatform;
+    initializeReactNative: typeof initializeReactNative;
+};
+export default _default;