@private.me/xbind 1.2.0

package/dist-standalone/cjs/verify.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * @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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openSignedEnvelope = exports.deserializeEnvelope = exports.validateEnvelope = exports.didToPublicKeyBytes = exports.importPublicKey = exports.verify = void 0;
+// Identity — verify + key import only
+var identity_js_1 = require("./identity.js");
+Object.defineProperty(exports, "verify", { enumerable: true, get: function () { return identity_js_1.verify; } });
+Object.defineProperty(exports, "importPublicKey", { enumerable: true, get: function () { return identity_js_1.importPublicKey; } });
+Object.defineProperty(exports, "didToPublicKeyBytes", { enumerable: true, get: function () { return identity_js_1.didToPublicKeyBytes; } });
+// Envelope — validation + signed envelope verification
+var envelope_js_1 = require("./envelope.js");
+Object.defineProperty(exports, "validateEnvelope", { enumerable: true, get: function () { return envelope_js_1.validateEnvelope; } });
+Object.defineProperty(exports, "deserializeEnvelope", { enumerable: true, get: function () { return envelope_js_1.deserializeEnvelope; } });
+Object.defineProperty(exports, "openSignedEnvelope", { enumerable: true, get: function () { return envelope_js_1.openSignedEnvelope; } });

package/dist-standalone/cjs/xfetch.js

@@ -0,0 +1,252 @@
+"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
+ *
+ * @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 agent_call_js_1.AgentError(agent_call_js_1.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,
+ *   },
+ * });
+ * ```
+ */
+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);
+}

package/dist-standalone/cli/init.d.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * @module cli/init
+ * One-line CLI setup for XBind connections.
+ *
+ * Enables: npx xbind-init --invite <code>
+ *
+ * Flow:
+ * 1. Parse invite URL or code
+ * 2. Fetch invite details from registry server
+ * 3. Interactive prompts for: project name, runtime, TypeScript vs JavaScript
+ * 4. Generate project directory with template files
+ * 5. Install dependencies
+ * 6. Write .env file with XBIND_INVITE_CODE
+ * 7. Register with XBind registry (auto-accept flow)
+ * 8. Print success message with next steps
+ *
+ * @example
+ * ```bash
+ * npx xbind-init --invite https://xbind.to/invite/XBD-abc123
+ *
+ * # Prompts:
+ * # → Project name: my-xbind-app
+ * # → Runtime: node-typescript
+ * # Creating project...
+ * # Installing dependencies...
+ * # Registering with XBind...
+ * # ✅ Ready! Run: cd my-xbind-app && npm start
+ * ```
+ */
+/**
+ * Runtime template types.
+ */
+export type RuntimeTemplate = 'node-typescript' | 'node-javascript' | 'deno' | 'cloudflare-worker' | 'vercel-function';
+/**
+ * Init command options.
+ */
+export interface InitOptions {
+    /** Invite URL or code */
+    invite?: string;
+    /** Project name */
+    name?: string;
+    /** Runtime template */
+    runtime?: RuntimeTemplate;
+    /** Skip interactive prompts */
+    yes?: boolean;
+    /** Registry URL (default: https://xbind.to) */
+    registryUrl?: string;
+    /** Registry URL (kebab-case for CLI parsing) - same as registryUrl */
+    'registry-url'?: string;
+}
+/**
+ * Main init command.
+ *
+ * @param options - Init options
+ */
+export declare function initCommand(options?: InitOptions): Promise<void>;
+/**
+ * CLI entry point.
+ *
+ * @param argv - Command-line arguments
+ */
+export declare function main(argv?: string[]): Promise<void>;