@private.me/xbind 3.0.2 → 3.0.3

package/dist-standalone/discovery.js

@@ -1,458 +1 @@
-/**
- * @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;
-    }
-}
+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}}