@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/cjs/xfetch.js

@@ -1 +1,340 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.xfetch=xfetch,exports.isXBindSupported=isXBindSupported,exports.getXBindCapability=getXBindCapability;const agent_js_1=require("./agent.js"),agent_call_js_1=require("./agent-call.js");async function checkXBindSupport(t){try{const e=await fetch(t,{method:"OPTIONS",headers:{"X-Capability-Check":"xbind"}});return"true"===e.headers.get("X-xBind-Support")?{supported:!0,endpoint:e.headers.get("X-xBind-Endpoint")||void 0,peerDID:e.headers.get("X-xBind-DID")||void 0,version:e.headers.get("X-xBind-Version")||void 0}:{supported:!1}}catch(t){return{supported:!1}}}async function sendViaXBind(t,e,r,n){const o=Date.now();if(!e.peerDID)throw new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.NETWORK_ERROR,"Server supports xBind but did not provide X-xBind-DID header",{url:t,capability:e});const a=e.peerDID,i=e.endpoint||t,s=new Uint8Array(16);crypto.getRandomValues(s);const c=Array.from(s).map(t=>t.toString(16).padStart(2,"0")).join(""),d=`xfetch_${Date.now()}_${c}`,l={correlationId:d,method:r.method||"GET",url:t,headers:r.headers||{},body:r.body?"string"==typeof r.body?r.body:JSON.stringify(r.body):void 0};return new Promise((e,s)=>{const c=setTimeout(()=>{s(new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.TIMEOUT,"xBind request timed out waiting for response",{url:t,correlationId:d,timeout:r.timeout||3e4}))},r.timeout||3e4);(async()=>{try{const p=await n.send({to:a,payload:l,scope:"xfetch",action:"http_request"});if(!p.ok)return clearTimeout(c),void s(new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.NETWORK_ERROR,`Failed to send xBind request: ${p.error}`,{url:t,error:p.error}));const u=`${i}/response/${d}`,_=100,g=(r.timeout||3e4)/_;for(let t=0;t<g;t++){await new Promise(t=>setTimeout(t,_));try{const t=await fetch(u);if(200===t.status){clearTimeout(c);const r=Date.now()-o;return void e(Object.assign(t,{usedXBind:!0,transport:{protocol:"xbind",latency:r,peerDID:a}}))}}catch(t){continue}}clearTimeout(c),s(new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.TIMEOUT,"Response not available after polling",{url:t,correlationId:d,polls:g}))}catch(e){clearTimeout(c),s(e instanceof agent_call_js_1.AgentError?e:new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.NETWORK_ERROR,"xBind request failed",{url:t,error:String(e)}))}})()})}async function sendViaHTTP(t,e){const r=Date.now(),{forceXBind:n,disableXBind:o,agent:a,retry:i,...s}=e,c=await fetch(t,s),d=Date.now()-r;return Object.assign(c,{usedXBind:!1,transport:{protocol:t.startsWith("https")?"https":"http",latency:d}})}async function withRetry(t,e){const r=e?.maxAttempts??3,n=e?.initialDelay??1e3,o=e?.multiplier??2;let a,i=n;for(let e=1;e<=r;e++)try{return await t()}catch(t){if(a=t instanceof Error?t:new Error(String(t)),t instanceof Response&&t.status>=400&&t.status<500)throw t;e<r&&(await new Promise(t=>setTimeout(t,i)),i*=o)}throw a}async function xfetch(t,e={}){let r;try{r=new URL(t)}catch(e){throw new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.INVALID_PARAMS,`Invalid URL: ${t}`,{url:t,error:e})}if(!["http:","https:"].includes(r.protocol))throw new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.INVALID_PARAMS,`Unsupported protocol: ${r.protocol}`,{url:t,protocol:r.protocol});const n=e.timeout??3e4,o=new AbortController,a=setTimeout(()=>o.abort(),n);try{const r=e.signal?AbortSignal.any?.([e.signal,o.signal])??o.signal:o.signal,n={...e,signal:r};if(e.disableXBind)return await withRetry(()=>sendViaHTTP(t,n),e.retry);const a=await checkXBindSupport(t);if(e.forceXBind&&!a.supported)throw new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.NETWORK_ERROR,`xBind required but endpoint does not support it: ${t}`,{url:t,forceXBind:!0,capability:a});if(a.supported){const r=e.agent??await agent_js_1.Agent.from({identity:"ephemeral",identityTTL:36e5});return await withRetry(()=>sendViaXBind(t,a,n,r),e.retry)}return await withRetry(()=>sendViaHTTP(t,n),e.retry)}finally{clearTimeout(a)}}async function isXBindSupported(t){return(await checkXBindSupport(t)).supported}async function getXBindCapability(t){return checkXBindSupport(t)}
+"use strict";
+/**
+ * @module xfetch
+ * Drop-in fetch() replacement with auto-upgrade to xBind
+ *
+ * Provides transparent upgrade from HTTP to xBind when both parties support it.
+ * Falls back to regular HTTP fetch() when xBind is not available.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.xfetch = xfetch;
+exports.isXBindSupported = isXBindSupported;
+exports.getXBindCapability = getXBindCapability;
+const agent_js_1 = require("./agent.js");
+const agent_call_js_1 = require("./agent-call.js");
+/**
+ * Check if endpoint supports xBind
+ *
+ * Sends OPTIONS request with xBind capability header.
+ * Endpoint responds with xBind-Support header if available.
+ *
+ * @param url - Target URL
+ * @returns Capability check result
+ */
+async function checkXBindSupport(url) {
+    try {
+        const response = await fetch(url, {
+            method: 'OPTIONS',
+            headers: {
+                'X-Capability-Check': 'xbind',
+            },
+        });
+        const supported = response.headers.get('X-xBind-Support') === 'true';
+        if (!supported) {
+            return { supported: false };
+        }
+        return {
+            supported: true,
+            endpoint: response.headers.get('X-xBind-Endpoint') || undefined,
+            peerDID: response.headers.get('X-xBind-DID') || undefined,
+            version: response.headers.get('X-xBind-Version') || undefined,
+        };
+    }
+    catch (error) {
+        // Network error or CORS - assume no xBind support
+        return { supported: false };
+    }
+}
+/**
+ * Send request via xBind transport
+ *
+ * Uses synchronous request-response pattern with direct signing and encryption.
+ * This is more appropriate for HTTP semantics than async agent.send().
+ *
+ * Architecture:
+ * 1. Wrap HTTP request in payload
+ * 2. Add correlation ID for response matching
+ * 3. Send via agent.send() to server DID
+ * 4. Wait for response with matching correlation ID
+ * 5. Decrypt and verify response
+ * 6. Return as standard HTTP Response
+ *
+ * @param url - Target URL
+ * @param capability - xBind capability info
+ * @param options - Request options
+ * @param agent - Agent instance
+ * @returns xBind response
+ */
+async function sendViaXBind(url, capability, options, agent) {
+    const startTime = Date.now();
+    // Validate that server provided DID and endpoint
+    if (!capability.peerDID) {
+        throw new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.NETWORK_ERROR, 'Server supports xBind but did not provide X-xBind-DID header', { url, capability });
+    }
+    const peerDID = capability.peerDID; // Type narrowing for later use
+    const xbindEndpoint = capability.endpoint || url;
+    // Generate secure correlation ID using crypto.getRandomValues()
+    const randomBytes = new Uint8Array(16);
+    crypto.getRandomValues(randomBytes);
+    const randomHex = Array.from(randomBytes)
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+    const correlationId = `xfetch_${Date.now()}_${randomHex}`;
+    // Build HTTP request payload to wrap in envelope
+    const httpRequest = {
+        correlationId,
+        method: options.method || 'GET',
+        url,
+        headers: options.headers || {},
+        body: options.body ? (typeof options.body === 'string'
+            ? options.body
+            : JSON.stringify(options.body)) : undefined,
+    };
+    // Set up response handler BEFORE sending request
+    const responsePromise = new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            reject(new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.TIMEOUT, 'xBind request timed out waiting for response', { url, correlationId, timeout: options.timeout || 30000 }));
+        }, options.timeout || 30000);
+        // Listen for response message
+        // TODO: This requires agent to support message handlers
+        // For now, we'll use a polling approach via the server's HTTP endpoint
+        // Alternative: Send request and poll for response
+        // This is less elegant but works without modifying Agent
+        (async () => {
+            try {
+                // Send request via agent.send()
+                const sendResult = await agent.send({
+                    to: peerDID,
+                    payload: httpRequest,
+                    scope: 'xfetch',
+                    action: 'http_request',
+                });
+                if (!sendResult.ok) {
+                    clearTimeout(timeout);
+                    reject(new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.NETWORK_ERROR, `Failed to send xBind request: ${sendResult.error}`, { url, error: sendResult.error }));
+                    return;
+                }
+                // Poll server for response (synchronous HTTP endpoint)
+                // Server should provide /xfetch/response/:correlationId endpoint
+                const responseUrl = `${xbindEndpoint}/response/${correlationId}`;
+                const pollInterval = 100; // Poll every 100ms
+                const maxPolls = (options.timeout || 30000) / pollInterval;
+                for (let i = 0; i < maxPolls; i++) {
+                    await new Promise(r => setTimeout(r, pollInterval));
+                    try {
+                        const response = await fetch(responseUrl);
+                        if (response.status === 200) {
+                            // Got response
+                            clearTimeout(timeout);
+                            const latency = Date.now() - startTime;
+                            resolve(Object.assign(response, {
+                                usedXBind: true,
+                                transport: {
+                                    protocol: 'xbind',
+                                    latency,
+                                    peerDID: peerDID,
+                                },
+                            }));
+                            return;
+                        }
+                        // 404 or 202 means still processing, continue polling
+                    }
+                    catch (pollError) {
+                        // Network error during polling, continue
+                        continue;
+                    }
+                }
+                // Timeout
+                clearTimeout(timeout);
+                reject(new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.TIMEOUT, 'Response not available after polling', { url, correlationId, polls: maxPolls }));
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                reject(error instanceof agent_call_js_1.AgentError ? error : new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.NETWORK_ERROR, 'xBind request failed', { url, error: String(error) }));
+            }
+        })();
+    });
+    return responsePromise;
+}
+/**
+ * Send request via standard HTTP fetch
+ *
+ * @param url - Target URL
+ * @param options - Request options
+ * @returns HTTP response wrapped as XFetchResponse
+ */
+async function sendViaHTTP(url, options) {
+    const startTime = Date.now();
+    // Remove xFetch-specific options before passing to fetch
+    const { forceXBind, disableXBind, agent, retry, ...fetchOptions } = options;
+    const response = await fetch(url, fetchOptions);
+    const latency = Date.now() - startTime;
+    // Wrap Response with xFetch metadata
+    return Object.assign(response, {
+        usedXBind: false,
+        transport: {
+            protocol: url.startsWith('https') ? 'https' : 'http',
+            latency,
+        },
+    });
+}
+/**
+ * Retry logic with exponential backoff
+ *
+ * @param fn - Function to retry
+ * @param options - Retry configuration
+ * @returns Result of function
+ */
+async function withRetry(fn, options) {
+    const maxAttempts = options?.maxAttempts ?? 3;
+    const initialDelay = options?.initialDelay ?? 1000;
+    const multiplier = options?.multiplier ?? 2;
+    let lastError;
+    let delay = initialDelay;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Don't retry on client errors (4xx)
+            if (error instanceof Response && error.status >= 400 && error.status < 500) {
+                throw error;
+            }
+            if (attempt < maxAttempts) {
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                delay *= multiplier;
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * xFetch - Drop-in fetch() replacement with auto-upgrade to xBind
+ *
+ * @param url - Target URL
+ * @param options - Request options (extends fetch RequestInit)
+ * @returns Response with xBind metadata
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (auto-upgrades to xBind if supported)
+ * const response = await xfetch('https://api.example.com/data');
+ * console.log('Used xBind?', response.usedXBind);
+ * const data = await response.json();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Force xBind (fail if not supported)
+ * const response = await xfetch('https://api.example.com/secure', {
+ *   forceXBind: true,
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Disable xBind (HTTP only)
+ * const response = await xfetch('https://api.example.com/public', {
+ *   disableXBind: true,
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With retry and timeout
+ * const response = await xfetch('https://api.example.com/data', {
+ *   timeout: 10000,
+ *   retry: {
+ *     maxAttempts: 5,
+ *     initialDelay: 500,
+ *     multiplier: 2,
+ *   },
+ * });
+ * ```
+ */
+async function xfetch(url, options = {}) {
+    // Validate URL
+    let parsedURL;
+    try {
+        parsedURL = new URL(url);
+    }
+    catch (error) {
+        throw new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.INVALID_PARAMS, `Invalid URL: ${url}`, { url, error });
+    }
+    // Only support HTTP(S) protocols
+    if (!['http:', 'https:'].includes(parsedURL.protocol)) {
+        throw new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.INVALID_PARAMS, `Unsupported protocol: ${parsedURL.protocol}`, { url, protocol: parsedURL.protocol });
+    }
+    // Apply timeout if specified
+    const timeout = options.timeout ?? 30000;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+        // Merge abort signals if user provided one
+        const signal = options.signal
+            ? AbortSignal.any?.([options.signal, controller.signal]) ?? controller.signal
+            : controller.signal;
+        const requestOptions = {
+            ...options,
+            signal,
+        };
+        // If xBind is explicitly disabled, use HTTP directly
+        if (options.disableXBind) {
+            return await withRetry(() => sendViaHTTP(url, requestOptions), options.retry);
+        }
+        // Check if endpoint supports xBind
+        const capability = await checkXBindSupport(url);
+        // If xBind is forced but not supported, fail
+        if (options.forceXBind && !capability.supported) {
+            throw new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.NETWORK_ERROR, `xBind required but endpoint does not support it: ${url}`, { url, forceXBind: true, capability });
+        }
+        // If xBind is supported, use it
+        if (capability.supported) {
+            // Create or use provided agent
+            const agent = options.agent ?? await agent_js_1.Agent.from({ identity: 'ephemeral', identityTTL: 3600000 });
+            return await withRetry(() => sendViaXBind(url, capability, requestOptions, agent), options.retry);
+        }
+        // Fallback to HTTP
+        return await withRetry(() => sendViaHTTP(url, requestOptions), options.retry);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Check if a URL supports xBind
+ *
+ * Utility function for checking xBind support before making a request.
+ *
+ * @param url - URL to check
+ * @returns True if endpoint supports xBind
+ *
+ * @example
+ * ```typescript
+ * const supported = await isXBindSupported('https://api.example.com');
+ * if (supported) {
+ *   console.log('Endpoint supports xBind - request will be upgraded');
+ * }
+ * ```
+ */
+async function isXBindSupported(url) {
+    const capability = await checkXBindSupport(url);
+    return capability.supported;
+}
+/**
+ * Get xBind capability information for a URL
+ *
+ * @param url - URL to check
+ * @returns Capability information
+ *
+ * @example
+ * ```typescript
+ * const info = await getXBindCapability('https://api.example.com');
+ * console.log('Peer DID:', info.peerDID);
+ * console.log('xBind version:', info.version);
+ * ```
+ */
+async function getXBindCapability(url) {
+    return checkXBindSupport(url);
+}