@private.me/xbind 1.2.0

package/dist-standalone/discovery.js

@@ -0,0 +1,458 @@
+/**
+ * @module discovery
+ * Service discovery for zero-config XBind connections.
+ *
+ * Enables: `xbind connect payments-service`
+ *
+ * Four-tier discovery:
+ * 1. Public registry (xbind.registry.io)
+ * 2. Well-known URL (https://service.com/.well-known/xbind)
+ * 3. DNS TXT record (_xbind.service.com)
+ * 4. Direct URL/QR code
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { promises as dns } from 'dns';
+/**
+ * Discovery error codes.
+ */
+export var DiscoveryErrorCode;
+(function (DiscoveryErrorCode) {
+    DiscoveryErrorCode["SERVICE_NOT_FOUND"] = "DISCOVERY_SERVICE_NOT_FOUND";
+    DiscoveryErrorCode["REGISTRY_UNREACHABLE"] = "DISCOVERY_REGISTRY_UNREACHABLE";
+    DiscoveryErrorCode["INVALID_RESPONSE"] = "DISCOVERY_INVALID_RESPONSE";
+    DiscoveryErrorCode["NETWORK_ERROR"] = "DISCOVERY_NETWORK_ERROR";
+    DiscoveryErrorCode["INVALID_SERVICE_NAME"] = "DISCOVERY_INVALID_SERVICE_NAME";
+    DiscoveryErrorCode["DNS_ERROR"] = "DISCOVERY_DNS_ERROR";
+    DiscoveryErrorCode["INVALID_EMAIL"] = "DISCOVERY_INVALID_EMAIL";
+    DiscoveryErrorCode["PERSONAL_EMAIL_DOMAIN"] = "DISCOVERY_PERSONAL_EMAIL_DOMAIN";
+})(DiscoveryErrorCode || (DiscoveryErrorCode = {}));
+/**
+ * Personal email domains that are blacklisted from discovery.
+ * Corporate services should use their own domain, not personal email.
+ */
+const PERSONAL_EMAIL_DOMAINS = new Set([
+    'gmail.com',
+    'googlemail.com',
+    'outlook.com',
+    'hotmail.com',
+    'live.com',
+    'yahoo.com',
+    'ymail.com',
+    'icloud.com',
+    'me.com',
+    'protonmail.com',
+    'proton.me',
+    'aol.com',
+    'mail.com',
+    'zoho.com',
+    'gmx.com',
+    'tutanota.com',
+    'fastmail.com',
+]);
+/**
+ * Discovery client for finding services.
+ */
+export class ServiceDiscovery {
+    registryUrl;
+    dnsCache;
+    /**
+     * Create a discovery client.
+     *
+     * @param options - Configuration options
+     * @param options.registryUrl - Registry URL (default: https://xbind.registry.io)
+     */
+    constructor(options = {}) {
+        this.registryUrl = options.registryUrl || 'https://xbind.registry.io';
+        this.dnsCache = new Map();
+    }
+    /**
+     * Discover a service by name.
+     *
+     * Tries:
+     * 1. Email-based discovery (extracts domain from email)
+     * 2. Public registry lookup
+     * 3. Well-known URL if name is a domain
+     * 4. DNS TXT record (_xbind.domain)
+     * 5. Direct URL if name is a full URL
+     *
+     * @param nameOrUrl - Service name, email, domain, or URL
+     * @returns Service info or error
+     *
+     * @example
+     * ```ts
+     * const discovery = new ServiceDiscovery();
+     *
+     * // By name (registry lookup):
+     * const result = await discovery.discover('payments-service');
+     *
+     * // By email (domain extraction):
+     * const result = await discovery.discover('alice@company.com');
+     *
+     * // By domain (well-known):
+     * const result = await discovery.discover('payments.example.com');
+     *
+     * // By URL (direct):
+     * const result = await discovery.discover('https://api.payments.com/xbind');
+     * ```
+     */
+    async discover(nameOrUrl) {
+        // Validate input
+        if (!nameOrUrl || nameOrUrl.trim().length === 0) {
+            return err({
+                code: DiscoveryErrorCode.INVALID_SERVICE_NAME,
+                message: 'Service name cannot be empty',
+                hint: 'Provide a service name, domain, email, or URL',
+            });
+        }
+        nameOrUrl = nameOrUrl.trim();
+        // If full URL, try direct
+        if (nameOrUrl.startsWith('http://') || nameOrUrl.startsWith('https://')) {
+            return this.discoverDirect(nameOrUrl);
+        }
+        // If email address, extract domain and discover
+        if (nameOrUrl.includes('@') && !nameOrUrl.includes('/')) {
+            return this.discoverEmail(nameOrUrl);
+        }
+        // If looks like domain, try well-known first, then DNS TXT
+        if (nameOrUrl.includes('.') && !nameOrUrl.includes('/')) {
+            const wellKnownResult = await this.discoverWellKnown(nameOrUrl);
+            if (wellKnownResult.ok) {
+                return wellKnownResult;
+            }
+            // Try DNS TXT as fallback
+            const dnsTxtResult = await this.discoverDnsTxt(nameOrUrl);
+            if (dnsTxtResult.ok) {
+                return dnsTxtResult;
+            }
+            // Fall through to registry if both fail
+        }
+        // Try registry lookup
+        return this.discoverRegistry(nameOrUrl);
+    }
+    /**
+     * Look up service in public registry.
+     *
+     * GET https://xbind.registry.io/lookup/:name
+     */
+    async discoverRegistry(name) {
+        try {
+            const url = `${this.registryUrl}/lookup/${encodeURIComponent(name)}`;
+            const response = await fetch(url, {
+                headers: {
+                    'Accept': 'application/json',
+                },
+            });
+            if (response.status === 404) {
+                return err({
+                    code: DiscoveryErrorCode.SERVICE_NOT_FOUND,
+                    message: `Service "${name}" not found in registry`,
+                    hint: 'Check service name or register at xbind.registry.io',
+                });
+            }
+            if (!response.ok) {
+                return err({
+                    code: DiscoveryErrorCode.REGISTRY_UNREACHABLE,
+                    message: `Registry returned ${response.status}`,
+                    hint: 'Try again later or use direct URL',
+                });
+            }
+            const data = await response.json();
+            return ok(data);
+        }
+        catch (error) {
+            return err({
+                code: DiscoveryErrorCode.NETWORK_ERROR,
+                message: error instanceof Error ? error.message : 'Network error',
+                hint: 'Check internet connection',
+            });
+        }
+    }
+    /**
+     * Discover via .well-known/xbind.
+     *
+     * GET https://domain/.well-known/xbind
+     */
+    async discoverWellKnown(domain) {
+        try {
+            const url = `https://${domain}/.well-known/xbind`;
+            const response = await fetch(url, {
+                headers: {
+                    'Accept': 'application/json',
+                },
+            });
+            if (!response.ok) {
+                return err({
+                    code: DiscoveryErrorCode.SERVICE_NOT_FOUND,
+                    message: `No .well-known/xbind found at ${domain}`,
+                });
+            }
+            const data = await response.json();
+            return ok(data);
+        }
+        catch (error) {
+            return err({
+                code: DiscoveryErrorCode.NETWORK_ERROR,
+                message: error instanceof Error ? error.message : 'Network error',
+            });
+        }
+    }
+    /**
+     * Discover via direct URL.
+     */
+    async discoverDirect(url) {
+        try {
+            const response = await fetch(url, {
+                headers: {
+                    'Accept': 'application/json',
+                },
+            });
+            if (!response.ok) {
+                return err({
+                    code: DiscoveryErrorCode.SERVICE_NOT_FOUND,
+                    message: `Service not found at ${url}`,
+                });
+            }
+            const data = await response.json();
+            return ok(data);
+        }
+        catch (error) {
+            return err({
+                code: DiscoveryErrorCode.NETWORK_ERROR,
+                message: error instanceof Error ? error.message : 'Network error',
+            });
+        }
+    }
+    /**
+     * Discover via DNS TXT record.
+     *
+     * Looks up TXT record at _xbind.domain
+     *
+     * Supports two formats:
+     * 1. Full record: "xbind-endpoint=https://...;did=did:web:...;publicKey=..." (all fields in DNS)
+     * 2. Simple redirect: "xbind=https://api.example.com/xbind" (fetch from endpoint)
+     *
+     * Includes 5-minute caching to reduce DNS queries.
+     */
+    async discoverDnsTxt(domain) {
+        // Check cache first (5 minute TTL)
+        const cached = this.dnsCache.get(domain);
+        if (cached && cached.expiry > Date.now()) {
+            return ok(cached.info);
+        }
+        try {
+            const txtRecords = await dns.resolveTxt(`_xbind.${domain}`);
+            // Find xbind record
+            for (const record of txtRecords) {
+                const txt = record.join('');
+                // Format 1: Full record with all fields
+                if (txt.includes('xbind-endpoint=')) {
+                    const parsed = this.parseDnsTxtRecord(txt, domain);
+                    if (parsed.ok) {
+                        // Cache for 5 minutes
+                        this.dnsCache.set(domain, {
+                            info: parsed.value,
+                            expiry: Date.now() + 5 * 60 * 1000,
+                        });
+                        return parsed;
+                    }
+                }
+                // Format 2: Simple redirect to endpoint
+                if (txt.startsWith('xbind=')) {
+                    const endpoint = txt.substring(6);
+                    // Fetch service info from endpoint
+                    const result = await this.discoverDirect(endpoint);
+                    if (result.ok) {
+                        // Cache for 5 minutes
+                        this.dnsCache.set(domain, {
+                            info: result.value,
+                            expiry: Date.now() + 5 * 60 * 1000,
+                        });
+                    }
+                    return result;
+                }
+            }
+            return err({
+                code: DiscoveryErrorCode.SERVICE_NOT_FOUND,
+                message: `No _xbind TXT record found for ${domain}`,
+                hint: 'Add DNS TXT record: _xbind.example.com IN TXT "xbind-endpoint=https://...;did=did:web:...;publicKey=..."',
+            });
+        }
+        catch (error) {
+            // Handle DNS-specific errors
+            if (error && typeof error === 'object' && 'code' in error) {
+                const dnsError = error;
+                if (dnsError.code === 'ENOTFOUND' || dnsError.code === 'ENODATA') {
+                    return err({
+                        code: DiscoveryErrorCode.SERVICE_NOT_FOUND,
+                        message: `No DNS TXT record found for _xbind.${domain}`,
+                    });
+                }
+                if (dnsError.code === 'ETIMEOUT') {
+                    return err({
+                        code: DiscoveryErrorCode.DNS_ERROR,
+                        message: 'DNS query timeout',
+                        hint: 'Check network connection or try again',
+                    });
+                }
+            }
+            return err({
+                code: DiscoveryErrorCode.DNS_ERROR,
+                message: error instanceof Error ? error.message : 'DNS lookup failed',
+                hint: 'Check domain name and DNS configuration',
+            });
+        }
+    }
+    /**
+     * Parse DNS TXT record into ServiceInfo.
+     *
+     * Expected format:
+     * xbind-endpoint=https://...;did=did:web:...;publicKey=...;version=1.0
+     *
+     * Optional fields:
+     * x25519PublicKey=...;mlKemPublicKey=...;description=...;logo=...;docs=...
+     */
+    parseDnsTxtRecord(txtRecord, domain) {
+        try {
+            const fields = new Map();
+            // Split by semicolon and parse key=value pairs
+            const parts = txtRecord.split(';').map(p => p.trim()).filter(p => p.length > 0);
+            for (const part of parts) {
+                const eqIndex = part.indexOf('=');
+                if (eqIndex === -1)
+                    continue;
+                const key = part.substring(0, eqIndex).trim();
+                const value = part.substring(eqIndex + 1).trim();
+                fields.set(key, value);
+            }
+            // Validate required fields
+            const endpoint = fields.get('xbind-endpoint');
+            const did = fields.get('did');
+            const publicKey = fields.get('publicKey');
+            if (!endpoint || !did || !publicKey) {
+                return err({
+                    code: DiscoveryErrorCode.INVALID_RESPONSE,
+                    message: 'DNS TXT record missing required fields',
+                    hint: 'Required: xbind-endpoint, did, publicKey',
+                });
+            }
+            // Build ServiceInfo
+            const info = {
+                name: domain,
+                endpoint,
+                did,
+                publicKey,
+            };
+            // Add optional fields
+            if (fields.has('x25519PublicKey')) {
+                info.x25519PublicKey = fields.get('x25519PublicKey');
+            }
+            if (fields.has('mlKemPublicKey')) {
+                info.mlKemPublicKey = fields.get('mlKemPublicKey');
+            }
+            if (fields.has('description')) {
+                info.description = fields.get('description');
+            }
+            if (fields.has('logo')) {
+                info.logo = fields.get('logo');
+            }
+            if (fields.has('docs')) {
+                info.docs = fields.get('docs');
+            }
+            return ok(info);
+        }
+        catch (error) {
+            return err({
+                code: DiscoveryErrorCode.INVALID_RESPONSE,
+                message: error instanceof Error ? error.message : 'Failed to parse DNS TXT record',
+            });
+        }
+    }
+    /**
+     * Discover service via email address.
+     *
+     * Extracts domain from email and performs discovery.
+     * Personal email domains (gmail.com, outlook.com, etc.) are rejected.
+     *
+     * @param email - Email address (e.g., "alice@company.com")
+     * @returns Service info or error
+     *
+     * @example
+     * ```ts
+     * const discovery = new ServiceDiscovery();
+     * const result = await discovery.discoverEmail('alice@company.com');
+     * // Discovers service at company.com
+     * ```
+     */
+    async discoverEmail(email) {
+        // Validate email format
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        if (!emailRegex.test(email)) {
+            return err({
+                code: DiscoveryErrorCode.INVALID_EMAIL,
+                message: `Invalid email format: ${email}`,
+                hint: 'Provide a valid email address (e.g., alice@company.com)',
+            });
+        }
+        // Extract domain (everything after @)
+        const domain = this.extractDomain(email);
+        if (!domain) {
+            return err({
+                code: DiscoveryErrorCode.INVALID_EMAIL,
+                message: `Could not extract domain from email: ${email}`,
+                hint: 'Check email format',
+            });
+        }
+        // Check for personal email domains
+        if (PERSONAL_EMAIL_DOMAINS.has(domain.toLowerCase())) {
+            return err({
+                code: DiscoveryErrorCode.PERSONAL_EMAIL_DOMAIN,
+                message: `Personal email domains not supported for discovery: ${domain}`,
+                hint: 'Use a corporate email address or provide the company domain directly',
+            });
+        }
+        // Discover using the extracted domain
+        // Try well-known first, then DNS TXT, then registry
+        const wellKnownResult = await this.discoverWellKnown(domain);
+        if (wellKnownResult.ok) {
+            return wellKnownResult;
+        }
+        const dnsTxtResult = await this.discoverDnsTxt(domain);
+        if (dnsTxtResult.ok) {
+            return dnsTxtResult;
+        }
+        // Try registry with domain
+        return this.discoverRegistry(domain);
+    }
+    /**
+     * Extract domain from email address.
+     * Handles edge cases: subdomains, plus addressing, etc.
+     *
+     * @param email - Email address
+     * @returns Domain or null if extraction fails
+     *
+     * @example
+     * ```ts
+     * extractDomain('alice@company.com') // 'company.com'
+     * extractDomain('alice+label@company.com') // 'company.com'
+     * extractDomain('alice@mail.company.com') // 'mail.company.com'
+     * ```
+     */
+    extractDomain(email) {
+        const parts = email.split('@');
+        if (parts.length !== 2 || !parts[1]) {
+            return null;
+        }
+        // Domain is everything after @
+        const domain = parts[1].trim().toLowerCase();
+        // Validate domain has at least one dot and valid characters
+        if (!domain.includes('.') || domain.length < 3) {
+            return null;
+        }
+        // Basic domain validation (alphanumeric, dots, hyphens)
+        const domainRegex = /^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)+$/;
+        if (!domainRegex.test(domain)) {
+            return null;
+        }
+        return domain;
+    }
+}

package/dist-standalone/dual-mode.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @module dual-mode
+ * Dual-mode adapter: XBind + API key fallback.
+ *
+ * Enables zero-downtime migration:
+ * - Try XBind first
+ * - Fall back to API key if unavailable
+ * - Track usage metrics
+ *
+ * @example
+ * ```ts
+ * const adapter = new DualModeAdapter({
+ *   xbind: xbindAgent,
+ *   fallback: {
+ *     type: 'api-key',
+ *     key: process.env.API_KEY,
+ *     url: 'https://api.example.com',
+ *   },
+ * });
+ *
+ * // Will try xBind, fall back to API key
+ * const result = await adapter.call('createCharge', { amount: 100 });
+ * ```
+ */
+import { Result } from '@private.me/shared';
+import type { Agent } from './agent.js';
+/**
+ * Fallback configuration.
+ */
+export interface FallbackConfig {
+    /** Fallback type */
+    type: 'api-key' | 'oauth' | 'custom';
+    /** API key (for type: 'api-key') */
+    key?: string;
+    /** Base URL */
+    url: string;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** HTTP method (default: POST) */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+}
+/**
+ * Usage metrics.
+ */
+export interface UsageMetrics {
+    /** Total calls */
+    totalCalls: number;
+    /** Calls via XBind */
+    xbindCalls: number;
+    /** Calls via fallback */
+    fallbackCalls: number;
+    /** XBind usage percentage */
+    xbindPercentage: number;
+    /** Last call timestamp */
+    lastCall: string;
+    /** Last call method */
+    lastCallMethod: 'xbind' | 'fallback';
+}
+/**
+ * Dual-mode error codes.
+ */
+export declare enum DualModeErrorCode {
+    BOTH_FAILED = "DUAL_MODE_BOTH_FAILED",
+    XBIND_FAILED = "DUAL_MODE_XBIND_FAILED",
+    FALLBACK_FAILED = "DUAL_MODE_FALLBACK_FAILED",
+    INVALID_CONFIG = "DUAL_MODE_INVALID_CONFIG"
+}
+/**
+ * Dual-mode error.
+ */
+export interface DualModeError {
+    code: DualModeErrorCode;
+    message: string;
+    xbindError?: unknown;
+    fallbackError?: unknown;
+}
+/**
+ * Dual-mode adapter.
+ *
+ * Tries XBind first, falls back to API key if unavailable.
+ */
+export declare class DualModeAdapter {
+    private xbind;
+    private fallback;
+    private metrics;
+    /**
+     * Create dual-mode adapter.
+     *
+     * @param options - Configuration
+     * @param options.xbind - xBind agent (optional, can be added later)
+     * @param options.fallback - Fallback config (optional, can be removed later)
+     */
+    constructor(options?: {
+        xbind?: Agent;
+        fallback?: FallbackConfig;
+    });
+    /**
+     * Set xBind agent (for gradual rollout).
+     *
+     * @param agent - xBind agent
+     */
+    setXBind(agent: Agent): void;
+    /**
+     * Remove fallback (complete migration).
+     */
+    removeFallback(): void;
+    /**
+     * Call an action (tries XBind first, falls back if needed).
+     *
+     * @param action - Action name
+     * @param params - Action parameters
+     * @returns Result or error
+     *
+     * @example
+     * ```ts
+     * const result = await adapter.call('createCharge', {
+     *   amount: 100,
+     *   currency: 'USD',
+     * });
+     * ```
+     */
+    call<T = unknown>(action: string, params?: Record<string, unknown>): Promise<Result<T, DualModeError>>;
+    /**
+     * Get usage metrics.
+     *
+     * @returns Current metrics
+     */
+    getMetrics(): UsageMetrics;
+    /**
+     * Reset metrics.
+     */
+    resetMetrics(): void;
+    /**
+     * Call via XBind.
+     */
+    private callViaXBind;
+    /**
+     * Call via fallback (API key, OAuth, etc.).
+     */
+    private callViaFallback;
+    /**
+     * Update metrics after a call.
+     */
+    private updateMetrics;
+}