@private.me/xbind 3.0.2 → 3.0.4

package/dist-standalone/xfetch.js

@@ -1,335 +1 @@
-/**
- * @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.
- */
-import { Agent } from './agent.js';
-import { AgentError, AgentErrorCode } from './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 AgentError(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 AgentError(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 AgentError(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 AgentError(AgentErrorCode.TIMEOUT, 'Response not available after polling', { url, correlationId, polls: maxPolls }));
-            }
-            catch (error) {
-                clearTimeout(timeout);
-                reject(error instanceof AgentError ? error : new AgentError(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,
- *   },
- * });
- * ```
- */
-export async function xfetch(url, options = {}) {
-    // Validate URL
-    let parsedURL;
-    try {
-        parsedURL = new URL(url);
-    }
-    catch (error) {
-        throw new AgentError(AgentErrorCode.INVALID_PARAMS, `Invalid URL: ${url}`, { url, error });
-    }
-    // Only support HTTP(S) protocols
-    if (!['http:', 'https:'].includes(parsedURL.protocol)) {
-        throw new AgentError(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 AgentError(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.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');
- * }
- * ```
- */
-export 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);
- * ```
- */
-export async function getXBindCapability(url) {
-    return checkXBindSupport(url);
-}
+import{Agent}from"./agent.js";import{AgentError,AgentErrorCode}from"./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{return{supported:!1}}}async function sendViaXBind(t,e,r,o){const n=Date.now();if(!e.peerDID)throw new AgentError(AgentErrorCode.NETWORK_ERROR,"Server supports xBind but did not provide X-xBind-DID header",{url:t,capability:e});const i=e.peerDID,a=e.endpoint||t,s=new Uint8Array(16);crypto.getRandomValues(s);const d=Array.from(s).map(t=>t.toString(16).padStart(2,"0")).join(""),c=`xfetch_${Date.now()}_${d}`,p={correlationId:c,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 d=setTimeout(()=>{s(new AgentError(AgentErrorCode.TIMEOUT,"xBind request timed out waiting for response",{url:t,correlationId:c,timeout:r.timeout||3e4}))},r.timeout||3e4);(async()=>{try{const u=await o.send({to:i,payload:p,scope:"xfetch",action:"http_request"});if(!u.ok)return clearTimeout(d),void s(new AgentError(AgentErrorCode.NETWORK_ERROR,`Failed to send xBind request: ${u.error}`,{url:t,error:u.error}));const l=`${a}/response/${c}`,g=100,h=(r.timeout||3e4)/g;for(let t=0;t<h;t++){await new Promise(t=>setTimeout(t,g));try{const t=await fetch(l);if(200===t.status){clearTimeout(d);const r=Date.now()-n;return void e(Object.assign(t,{usedXBind:!0,transport:{protocol:"xbind",latency:r,peerDID:i}}))}}catch{continue}}clearTimeout(d),s(new AgentError(AgentErrorCode.TIMEOUT,"Response not available after polling",{url:t,correlationId:c,polls:h}))}catch(e){clearTimeout(d),s(e instanceof AgentError?e:new AgentError(AgentErrorCode.NETWORK_ERROR,"xBind request failed",{url:t,error:String(e)}))}})()})}async function sendViaHTTP(t,e){const r=Date.now(),{forceXBind:o,disableXBind:n,agent:i,retry:a,...s}=e,d=await fetch(t,s),c=Date.now()-r;return Object.assign(d,{usedXBind:!1,transport:{protocol:t.startsWith("https")?"https":"http",latency:c}})}async function withRetry(t,e){const r=e?.maxAttempts??3,o=e?.initialDelay??1e3,n=e?.multiplier??2;let i,a=o;for(let e=1;e<=r;e++)try{return await t()}catch(t){if(i=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,a)),a*=n)}throw i}export async function xfetch(t,e={}){let r;try{r=new URL(t)}catch(e){throw new AgentError(AgentErrorCode.INVALID_PARAMS,`Invalid URL: ${t}`,{url:t,error:e})}if(!["http:","https:"].includes(r.protocol))throw new AgentError(AgentErrorCode.INVALID_PARAMS,`Unsupported protocol: ${r.protocol}`,{url:t,protocol:r.protocol});const o=e.timeout??3e4,n=new AbortController,i=setTimeout(()=>n.abort(),o);try{const r=e.signal?AbortSignal.any?.([e.signal,n.signal])??n.signal:n.signal,o={...e,signal:r};if(e.disableXBind)return await withRetry(()=>sendViaHTTP(t,o),e.retry);const i=await checkXBindSupport(t);if(e.forceXBind&&!i.supported)throw new AgentError(AgentErrorCode.NETWORK_ERROR,`xBind required but endpoint does not support it: ${t}`,{url:t,forceXBind:!0,capability:i});if(i.supported){const r=e.agent??await Agent.from({identity:"ephemeral",identityTTL:36e5});return await withRetry(()=>sendViaXBind(t,i,o,r),e.retry)}return await withRetry(()=>sendViaHTTP(t,o),e.retry)}finally{clearTimeout(i)}}export async function isXBindSupported(t){return(await checkXBindSupport(t)).supported}export async function getXBindCapability(t){return checkXBindSupport(t)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@private.me/xbind",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "Identity-based M2M authentication (Contains encryption - export restrictions apply)",
   "license": "Proprietary",
   "author": "Private.Me Contributors",