@private.me/xbind 1.2.0

package/dist-standalone/did-web.js

@@ -0,0 +1,196 @@
+/**
+ * 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.
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { fromBase64 } from"./_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.
+ */
+export 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 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 err('REVOKED');
+        return 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 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 ok(cached.entry);
+        }
+        const url = didWebToUrl(did);
+        if (!url)
+            return err('NOT_FOUND');
+        try {
+            const res = await this.fetchFn(url);
+            if (!res.ok)
+                return err('NOT_FOUND');
+            const doc = (await res.json());
+            const entry = parseDidDocument(did, doc);
+            if (!entry)
+                return err('NOT_FOUND');
+            this.cache.set(did, { entry, fetchedAt: Date.now() });
+            return ok(entry);
+        }
+        catch {
+            return err('NETWORK_ERROR');
+        }
+    }
+}
+/**
+ * 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.
+ */
+export 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 = 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/discovery.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @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 { Result } from '@private.me/shared';
+/**
+ * Service metadata returned from discovery.
+ */
+export interface ServiceInfo {
+    /** Service identifier (e.g., "payments-service") */
+    name: string;
+    /** XBind endpoint URL */
+    endpoint: string;
+    /** DID of the service */
+    did: string;
+    /** Public key (Ed25519, base64) */
+    publicKey: string;
+    /** X25519 public key for ECDH (optional, base64) */
+    x25519PublicKey?: string;
+    /** ML-KEM-768 public key for PQ KEM (optional, base64) */
+    mlKemPublicKey?: string;
+    /** Service description */
+    description?: string;
+    /** Logo URL */
+    logo?: string;
+    /** Documentation URL */
+    docs?: string;
+    /** Whether this service is verified */
+    verified?: boolean;
+}
+/**
+ * Discovery error codes.
+ */
+export declare enum DiscoveryErrorCode {
+    SERVICE_NOT_FOUND = "DISCOVERY_SERVICE_NOT_FOUND",
+    REGISTRY_UNREACHABLE = "DISCOVERY_REGISTRY_UNREACHABLE",
+    INVALID_RESPONSE = "DISCOVERY_INVALID_RESPONSE",
+    NETWORK_ERROR = "DISCOVERY_NETWORK_ERROR",
+    INVALID_SERVICE_NAME = "DISCOVERY_INVALID_SERVICE_NAME",
+    DNS_ERROR = "DISCOVERY_DNS_ERROR",
+    INVALID_EMAIL = "DISCOVERY_INVALID_EMAIL",
+    PERSONAL_EMAIL_DOMAIN = "DISCOVERY_PERSONAL_EMAIL_DOMAIN"
+}
+/**
+ * Discovery error.
+ */
+export interface DiscoveryError {
+    code: DiscoveryErrorCode;
+    message: string;
+    hint?: string;
+}
+/**
+ * Discovery client for finding services.
+ */
+export declare class ServiceDiscovery {
+    private registryUrl;
+    private dnsCache;
+    /**
+     * Create a discovery client.
+     *
+     * @param options - Configuration options
+     * @param options.registryUrl - Registry URL (default: https://xbind.registry.io)
+     */
+    constructor(options?: {
+        registryUrl?: string;
+    });
+    /**
+     * 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');
+     * ```
+     */
+    discover(nameOrUrl: string): Promise<Result<ServiceInfo, DiscoveryError>>;
+    /**
+     * Look up service in public registry.
+     *
+     * GET https://xbind.registry.io/lookup/:name
+     */
+    private discoverRegistry;
+    /**
+     * Discover via .well-known/xbind.
+     *
+     * GET https://domain/.well-known/xbind
+     */
+    private discoverWellKnown;
+    /**
+     * Discover via direct URL.
+     */
+    private discoverDirect;
+    /**
+     * 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.
+     */
+    private discoverDnsTxt;
+    /**
+     * 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=...
+     */
+    private parseDnsTxtRecord;
+    /**
+     * 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
+     * ```
+     */
+    private discoverEmail;
+    /**
+     * 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'
+     * ```
+     */
+    private extractDomain;
+}