@private.me/xbind 1.2.0

package/dist-standalone/cjs/did-web.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * did:web resolver — resolves DIDs hosted on developer domains.
+ *
+ * Implements the W3C did:web method:
+ *   did:web:example.com -> https://example.com/.well-known/did.json
+ *   did:web:example.com:path:to -> https://example.com/path/to/did.json
+ *
+ * Enables direct agent-to-agent communication without a centralized registry.
+ * Implements TrustRegistry interface for drop-in use with Agent class.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DidWebResolver = void 0;
+exports.didWebToUrl = didWebToUrl;
+const shared_1 = require("../_deps/shared/index.js");
+const crypto_1 = require("../_deps/crypto/index.js");
+/**
+ * Resolve did:web DIDs by fetching DID documents from the hosting domain.
+ *
+ * Implements TrustRegistry interface so it can be used as a drop-in
+ * replacement for MemoryTrustRegistry or HttpTrustRegistry.
+ */
+class DidWebResolver {
+    fetchFn;
+    cacheTtlMs;
+    cache = new Map();
+    constructor(opts) {
+        this.fetchFn = opts?.fetch ?? globalThis.fetch.bind(globalThis);
+        this.cacheTtlMs = opts?.cacheTtlMs ?? 300_000;
+    }
+    /** Registration not supported for did:web (developers host their own). */
+    async register(_did, _publicKey, _name, _scopes, _x25519PublicKey) {
+        return (0, shared_1.err)('ALREADY_REGISTERED');
+    }
+    /**
+     * Resolve a did:web DID to its raw public key bytes.
+     * @param did - A did:web DID string.
+     * @returns Public key bytes or error.
+     */
+    async resolve(did) {
+        const entry = await this.fetchEntry(did);
+        if (!entry.ok)
+            return entry;
+        if (entry.value.revoked)
+            return (0, shared_1.err)('REVOKED');
+        return (0, shared_1.ok)(entry.value.publicKey);
+    }
+    /**
+     * Check if a did:web DID has a specific scope.
+     * @param did - The DID to check.
+     * @param scope - The scope to verify.
+     * @returns True if scope is granted.
+     */
+    async hasScope(did, scope) {
+        const entry = await this.fetchEntry(did);
+        if (!entry.ok)
+            return false;
+        return entry.value.scopes.has(scope);
+    }
+    /**
+     * Check if a did:web DID has a specific receive scope.
+     * @param did - The DID to check.
+     * @param scope - The scope to verify.
+     * @returns True if receive scope is granted.
+     */
+    async hasReceiveScope(did, scope) {
+        const entry = await this.fetchEntry(did);
+        if (!entry.ok)
+            return false;
+        // Undefined = accept all scopes (backward compatibility)
+        if (!entry.value.receiveScopes)
+            return true;
+        return entry.value.receiveScopes.has(scope);
+    }
+    /** Revocation not supported for did:web (developer controls their domain). */
+    async revoke(_did) {
+        return (0, shared_1.err)('NOT_FOUND');
+    }
+    /**
+     * Get the full registry entry for a did:web DID.
+     * @param did - The DID to look up.
+     * @returns Full entry or error.
+     */
+    async getEntry(did) {
+        return this.fetchEntry(did);
+    }
+    /** Number of cached entries (for testing). */
+    get cacheSize() {
+        return this.cache.size;
+    }
+    /** Fetch and parse a DID document, with caching. */
+    async fetchEntry(did) {
+        // Check cache
+        const cached = this.cache.get(did);
+        if (cached && Date.now() - cached.fetchedAt < this.cacheTtlMs) {
+            return (0, shared_1.ok)(cached.entry);
+        }
+        const url = didWebToUrl(did);
+        if (!url)
+            return (0, shared_1.err)('NOT_FOUND');
+        try {
+            const res = await this.fetchFn(url);
+            if (!res.ok)
+                return (0, shared_1.err)('NOT_FOUND');
+            const doc = (await res.json());
+            const entry = parseDidDocument(did, doc);
+            if (!entry)
+                return (0, shared_1.err)('NOT_FOUND');
+            this.cache.set(did, { entry, fetchedAt: Date.now() });
+            return (0, shared_1.ok)(entry);
+        }
+        catch {
+            return (0, shared_1.err)('NETWORK_ERROR');
+        }
+    }
+}
+exports.DidWebResolver = DidWebResolver;
+/**
+ * Convert a did:web DID to its HTTPS URL.
+ *   did:web:example.com -> https://example.com/.well-known/did.json
+ *   did:web:example.com:path:to -> https://example.com/path/to/did.json
+ * @param did - The did:web DID string.
+ * @returns HTTPS URL or null if invalid.
+ */
+function didWebToUrl(did) {
+    if (!did.startsWith('did:web:'))
+        return null;
+    const parts = did.slice('did:web:'.length).split(':');
+    if (parts.length === 0 || !parts[0])
+        return null;
+    const domain = decodeURIComponent(parts[0]);
+    if (parts.length === 1) {
+        return `https://${domain}/.well-known/did.json`;
+    }
+    const path = parts.slice(1).map(decodeURIComponent).join('/');
+    return `https://${domain}/${path}/did.json`;
+}
+/** Parse a DID document into a RegistryEntry. */
+function parseDidDocument(did, doc) {
+    if (!doc.verificationMethod || doc.verificationMethod.length === 0) {
+        return null;
+    }
+    const vm = doc.verificationMethod[0];
+    if (!vm)
+        return null;
+    let publicKey = null;
+    if (vm.publicKeyMultibase) {
+        publicKey = decodeMultibase(vm.publicKeyMultibase);
+    }
+    else if (vm.publicKeyBase64) {
+        publicKey = (0, crypto_1.fromBase64)(vm.publicKeyBase64);
+    }
+    if (!publicKey)
+        return null;
+    return {
+        did,
+        publicKey,
+        name: doc.xailName ?? did,
+        scopes: new Set(doc.xailScopes ?? []),
+        revoked: doc.deactivated === true,
+        rotation_sequence: 1, // DID documents don't track rotation, default to 1
+    };
+}
+/** Decode z-prefixed base58btc multibase to bytes. */
+function decodeMultibase(mb) {
+    if (!mb.startsWith('z'))
+        return null;
+    return base58Decode(mb.slice(1));
+}
+/** Base58 decode (Bitcoin alphabet). */
+function base58Decode(s) {
+    const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+    const BASE = BigInt(58);
+    let num = BigInt(0);
+    for (const char of s) {
+        const idx = ALPHABET.indexOf(char);
+        if (idx < 0)
+            return new Uint8Array(0);
+        num = num * BASE + BigInt(idx);
+    }
+    const hex = num.toString(16);
+    const padded = hex.length % 2 ? '0' + hex : hex;
+    const bytes = new Uint8Array(padded.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(padded.slice(i * 2, i * 2 + 2), 16);
+    }
+    // Handle leading zeros (base58 "1" = 0x00)
+    let leadingZeros = 0;
+    for (const c of s) {
+        if (c === '1')
+            leadingZeros++;
+        else
+            break;
+    }
+    if (leadingZeros > 0) {
+        const result = new Uint8Array(leadingZeros + bytes.length);
+        result.set(bytes, leadingZeros);
+        return result;
+    }
+    return bytes;
+}

package/dist-standalone/cjs/discovery.js

@@ -0,0 +1,462 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceDiscovery = exports.DiscoveryErrorCode = void 0;
+const shared_1 = require("../_deps/shared/index.js");
+const dns_1 = require("dns");
+/**
+ * Discovery error codes.
+ */
+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 || (exports.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.
+ */
+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 (0, shared_1.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 (0, shared_1.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 (0, shared_1.err)({
+                    code: DiscoveryErrorCode.REGISTRY_UNREACHABLE,
+                    message: `Registry returned ${response.status}`,
+                    hint: 'Try again later or use direct URL',
+                });
+            }
+            const data = await response.json();
+            return (0, shared_1.ok)(data);
+        }
+        catch (error) {
+            return (0, shared_1.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 (0, shared_1.err)({
+                    code: DiscoveryErrorCode.SERVICE_NOT_FOUND,
+                    message: `No .well-known/xbind found at ${domain}`,
+                });
+            }
+            const data = await response.json();
+            return (0, shared_1.ok)(data);
+        }
+        catch (error) {
+            return (0, shared_1.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 (0, shared_1.err)({
+                    code: DiscoveryErrorCode.SERVICE_NOT_FOUND,
+                    message: `Service not found at ${url}`,
+                });
+            }
+            const data = await response.json();
+            return (0, shared_1.ok)(data);
+        }
+        catch (error) {
+            return (0, shared_1.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 (0, shared_1.ok)(cached.info);
+        }
+        try {
+            const txtRecords = await dns_1.promises.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 (0, shared_1.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 (0, shared_1.err)({
+                        code: DiscoveryErrorCode.SERVICE_NOT_FOUND,
+                        message: `No DNS TXT record found for _xbind.${domain}`,
+                    });
+                }
+                if (dnsError.code === 'ETIMEOUT') {
+                    return (0, shared_1.err)({
+                        code: DiscoveryErrorCode.DNS_ERROR,
+                        message: 'DNS query timeout',
+                        hint: 'Check network connection or try again',
+                    });
+                }
+            }
+            return (0, shared_1.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 (0, shared_1.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 (0, shared_1.ok)(info);
+        }
+        catch (error) {
+            return (0, shared_1.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 (0, shared_1.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 (0, shared_1.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 (0, shared_1.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;
+    }
+}
+exports.ServiceDiscovery = ServiceDiscovery;