@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/discovery.js

@@ -1 +1,458 @@
-import{ok,err}from"./_deps/shared/index.js";import{promises as dns}from"dns";export var DiscoveryErrorCode;!function(e){e.SERVICE_NOT_FOUND="DISCOVERY_SERVICE_NOT_FOUND",e.REGISTRY_UNREACHABLE="DISCOVERY_REGISTRY_UNREACHABLE",e.INVALID_RESPONSE="DISCOVERY_INVALID_RESPONSE",e.NETWORK_ERROR="DISCOVERY_NETWORK_ERROR",e.INVALID_SERVICE_NAME="DISCOVERY_INVALID_SERVICE_NAME",e.DNS_ERROR="DISCOVERY_DNS_ERROR",e.INVALID_EMAIL="DISCOVERY_INVALID_EMAIL",e.PERSONAL_EMAIL_DOMAIN="DISCOVERY_PERSONAL_EMAIL_DOMAIN"}(DiscoveryErrorCode||(DiscoveryErrorCode={}));const PERSONAL_EMAIL_DOMAINS=new Set(["gmail.com","googlemail.com","outlook.com","hotmail.com","live.com","yahoo.com","ymail.com","icloud.com","me.com","secure-email-provider-1.com","secure-email-provider-2.com","aol.com","mail.com","zoho.com","gmx.com","tutanota.com","fastmail.com"]);export class ServiceDiscovery{registryUrl;dnsCache;constructor(e={}){this.registryUrl=e.registryUrl||"https://xbind.registry.io",this.dnsCache=new Map}async discover(e){if(!e||0===e.trim().length)return err({code:DiscoveryErrorCode.INVALID_SERVICE_NAME,message:"Service name cannot be empty",hint:"Provide a service name, domain, email, or URL"});if((e=e.trim()).startsWith("http://")||e.startsWith("https://"))return this.discoverDirect(e);if(e.includes("@")&&!e.includes("/"))return this.discoverEmail(e);if(e.includes(".")&&!e.includes("/")){const r=await this.discoverWellKnown(e);if(r.ok)return r;const o=await this.discoverDnsTxt(e);if(o.ok)return o}return this.discoverRegistry(e)}async discoverRegistry(e){try{const r=`${this.registryUrl}/lookup/${encodeURIComponent(e)}`,o=await fetch(r,{headers:{Accept:"application/json"}});if(404===o.status)return err({code:DiscoveryErrorCode.SERVICE_NOT_FOUND,message:`Service "${e}" not found in registry`,hint:"Check service name or register at xbind.registry.io"});if(!o.ok)return err({code:DiscoveryErrorCode.REGISTRY_UNREACHABLE,message:`Registry returned ${o.status}`,hint:"Try again later or use direct URL"});const t=await o.json();return ok(t)}catch(e){return err({code:DiscoveryErrorCode.NETWORK_ERROR,message:e instanceof Error?e.message:"Network error",hint:"Check internet connection"})}}async discoverWellKnown(e){try{const r=`https://${e}/.well-known/xbind`,o=await fetch(r,{headers:{Accept:"application/json"}});if(!o.ok)return err({code:DiscoveryErrorCode.SERVICE_NOT_FOUND,message:`No .well-known/xbind found at ${e}`});const t=await o.json();return ok(t)}catch(e){return err({code:DiscoveryErrorCode.NETWORK_ERROR,message:e instanceof Error?e.message:"Network error"})}}async discoverDirect(e){try{const r=await fetch(e,{headers:{Accept:"application/json"}});if(!r.ok)return err({code:DiscoveryErrorCode.SERVICE_NOT_FOUND,message:`Service not found at ${e}`});const o=await r.json();return ok(o)}catch(e){return err({code:DiscoveryErrorCode.NETWORK_ERROR,message:e instanceof Error?e.message:"Network error"})}}async discoverDnsTxt(e){const r=this.dnsCache.get(e);if(r&&r.expiry>Date.now())return ok(r.info);try{const r=await dns.resolveTxt(`_xbind.${e}`);for(const o of r){const r=o.join("");if(r.includes("xbind-endpoint=")){const o=this.parseDnsTxtRecord(r,e);if(o.ok)return this.dnsCache.set(e,{info:o.value,expiry:Date.now()+3e5}),o}if(r.startsWith("xbind=")){const o=r.substring(6),t=await this.discoverDirect(o);return t.ok&&this.dnsCache.set(e,{info:t.value,expiry:Date.now()+3e5}),t}}return err({code:DiscoveryErrorCode.SERVICE_NOT_FOUND,message:`No _xbind TXT record found for ${e}`,hint:'Add DNS TXT record: _xbind.example.com IN TXT "xbind-endpoint=https://...;did=did:web:...;publicKey=..."'})}catch(r){if(r&&"object"==typeof r&&"code"in r){const o=r;if("ENOTFOUND"===o.code||"ENODATA"===o.code)return err({code:DiscoveryErrorCode.SERVICE_NOT_FOUND,message:`No DNS TXT record found for _xbind.${e}`});if("ETIMEOUT"===o.code)return err({code:DiscoveryErrorCode.DNS_ERROR,message:"DNS query timeout",hint:"Check network connection or try again"})}return err({code:DiscoveryErrorCode.DNS_ERROR,message:r instanceof Error?r.message:"DNS lookup failed",hint:"Check domain name and DNS configuration"})}}parseDnsTxtRecord(e,r){try{const o=new Map,t=e.split(";").map(e=>e.trim()).filter(e=>e.length>0);for(const e of t){const r=e.indexOf("=");if(-1===r)continue;const t=e.substring(0,r).trim(),i=e.substring(r+1).trim();o.set(t,i)}const i=o.get("xbind-endpoint"),s=o.get("did"),n=o.get("publicKey");if(!i||!s||!n)return err({code:DiscoveryErrorCode.INVALID_RESPONSE,message:"DNS TXT record missing required fields",hint:"Required: xbind-endpoint, did, publicKey"});const c={name:r,endpoint:i,did:s,publicKey:n};return o.has("x25519PublicKey")&&(c.x25519PublicKey=o.get("x25519PublicKey")),o.has("mlKemPublicKey")&&(c.mlKemPublicKey=o.get("mlKemPublicKey")),o.has("description")&&(c.description=o.get("description")),o.has("logo")&&(c.logo=o.get("logo")),o.has("docs")&&(c.docs=o.get("docs")),ok(c)}catch(e){return err({code:DiscoveryErrorCode.INVALID_RESPONSE,message:e instanceof Error?e.message:"Failed to parse DNS TXT record"})}}async discoverEmail(e){if(!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(e))return err({code:DiscoveryErrorCode.INVALID_EMAIL,message:`Invalid email format: ${e}`,hint:"Provide a valid email address (e.g., alice@company.com)"});const r=this.extractDomain(e);if(!r)return err({code:DiscoveryErrorCode.INVALID_EMAIL,message:`Could not extract domain from email: ${e}`,hint:"Check email format"});if(PERSONAL_EMAIL_DOMAINS.has(r.toLowerCase()))return err({code:DiscoveryErrorCode.PERSONAL_EMAIL_DOMAIN,message:`Personal email domains not supported for discovery: ${r}`,hint:"Use a corporate email address or provide the company domain directly"});const o=await this.discoverWellKnown(r);if(o.ok)return o;const t=await this.discoverDnsTxt(r);return t.ok?t:this.discoverRegistry(r)}extractDomain(e){const r=e.split("@");if(2!==r.length||!r[1])return null;const o=r[1].trim().toLowerCase();if(!o.includes(".")||o.length<3)return null;return/^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)+$/.test(o)?o:null}}
+/**
+ * @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',
+    'secure-email-provider-1.com',
+    'secure-email-provider-2.com',
+    '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;
+    }
+}