@private.me/xbind 1.2.0

package/dist-standalone/verify.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @module verify
+ * Lightweight sub-path export for verification-only use cases.
+ *
+ * Import as `@private.me/xbind/verify` for tree-shaking on edge/serverless:
+ * ```ts
+ * import { verify, importPublicKey, validateEnvelope } from '@private.me/xbind/verify';
+ * ```
+ *
+ * This module re-exports only the functions needed to verify signatures
+ * and validate envelopes — no key generation, no encryption, no transport.
+ */
+export { verify, importPublicKey, didToPublicKeyBytes } from './identity.js';
+export type { IdentityError } from './identity.js';
+export { validateEnvelope, deserializeEnvelope, openSignedEnvelope, } from './envelope.js';
+export type { TransportEnvelope, EnvelopeError } from './envelope.js';

package/dist-standalone/verify.js

@@ -0,0 +1,16 @@
+/**
+ * @module verify
+ * Lightweight sub-path export for verification-only use cases.
+ *
+ * Import as `@private.me/xbind/verify` for tree-shaking on edge/serverless:
+ * ```ts
+ * import { verify, importPublicKey, validateEnvelope } from '@private.me/xbind/verify';
+ * ```
+ *
+ * This module re-exports only the functions needed to verify signatures
+ * and validate envelopes — no key generation, no encryption, no transport.
+ */
+// Identity — verify + key import only
+export { verify, importPublicKey, didToPublicKeyBytes } from './identity.js';
+// Envelope — validation + signed envelope verification
+export { validateEnvelope, deserializeEnvelope, openSignedEnvelope, } from './envelope.js';

package/dist-standalone/xfetch.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @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';
+/**
+ * xFetch options extending standard fetch RequestInit
+ */
+export interface XFetchOptions extends RequestInit {
+    /** Force xBind transport (fail if unavailable) */
+    forceXBind?: boolean;
+    /** Disable auto-upgrade to xBind (use HTTP only) */
+    disableXBind?: boolean;
+    /** Agent instance to use (creates ephemeral if not provided) */
+    agent?: Agent;
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Retry configuration */
+    retry?: {
+        /** Maximum retry attempts (default: 3) */
+        maxAttempts?: number;
+        /** Initial backoff delay in ms (default: 1000) */
+        initialDelay?: number;
+        /** Backoff multiplier (default: 2) */
+        multiplier?: number;
+    };
+}
+/**
+ * xFetch response extending standard Response
+ */
+export interface XFetchResponse extends Response {
+    /** True if request was upgraded to xBind */
+    usedXBind: boolean;
+    /** Transport metadata */
+    transport: {
+        protocol: 'xbind' | 'http' | 'https';
+        latency?: number;
+        peerDID?: string;
+    };
+}
+/**
+ * xBind capability detection result
+ */
+interface CapabilityCheck {
+    supported: boolean;
+    endpoint?: string;
+    peerDID?: string;
+    version?: string;
+}
+/**
+ * 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 declare function xfetch(url: string, options?: XFetchOptions): Promise<XFetchResponse>;
+/**
+ * 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 declare function isXBindSupported(url: string): Promise<boolean>;
+/**
+ * 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 declare function getXBindCapability(url: string): Promise<CapabilityCheck>;
+export {};

package/dist-standalone/xfetch.js

@@ -0,0 +1,247 @@
+/**
+ * @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
+ *
+ * @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();
+    // TODO: Integrate with Agent.send() when transport layer is ready
+    // For now, placeholder that will be completed by transport layer work
+    throw new AgentError(AgentErrorCode.NETWORK_ERROR, 'xBind transport not yet implemented - requires transport layer (xchange/xfetch integration)', {
+        url,
+        peerDID: capability.peerDID,
+        nextSteps: [
+            'Complete Agent.send() integration',
+            'Implement xBind message envelope',
+            'Add DID-based authentication',
+        ],
+    });
+}
+/**
+ * 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);
+}