@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/connect.js

@@ -1 +1,274 @@
-import{ok,err}from"./_deps/shared/index.js";import{fromBase64,toBase64}from"./crypto-utils.js";import{Agent}from"./agent.js";import{ServiceDiscovery}from"./discovery.js";import{HttpsTransportAdapter}from"./transport.js";import{MemoryTrustRegistry}from"./trust-registry.js";import{importPublicKey}from"./identity.js";export var ConnectErrorCode;!function(e){e.DISCOVERY_FAILED="CONNECT_DISCOVERY_FAILED",e.AGENT_CREATION_FAILED="CONNECT_AGENT_CREATION_FAILED",e.TRUST_VERIFICATION_FAILED="CONNECT_TRUST_VERIFICATION_FAILED",e.INVALID_SERVICE_INFO="CONNECT_INVALID_SERVICE_INFO"}(ConnectErrorCode||(ConnectErrorCode={}));export async function connect(e,r={}){const t=r.discovery||new ServiceDiscovery,i=await t.discover(e);if(!i.ok)return err({code:ConnectErrorCode.DISCOVERY_FAILED,message:`Failed to discover service: ${i.error.message}`,hint:i.error.hint,cause:i.error});const o=i.value;if(!o.did||!o.endpoint||!o.publicKey)return err({code:ConnectErrorCode.INVALID_SERVICE_INFO,message:"Service info missing required fields (did, endpoint, publicKey)",hint:"Service must provide complete metadata"});const n=r.registry||new MemoryTrustRegistry;try{const e=fromBase64(o.publicKey),r=await importPublicKey(e);if(!r.ok)return err({code:ConnectErrorCode.TRUST_VERIFICATION_FAILED,message:"Invalid service public key",cause:r.error});await n.add({did:o.did,publicKey:r.value,x25519PublicKey:o.x25519PublicKey?await importPublicKey(fromBase64(o.x25519PublicKey)).then(e=>e.ok?e.value:void 0):void 0,mlKemPublicKey:o.mlKemPublicKey?fromBase64(o.mlKemPublicKey):void 0})}catch(e){return err({code:ConnectErrorCode.TRUST_VERIFICATION_FAILED,message:"Failed to verify service public key",cause:e})}const a=r.transport||new HttpsTransportAdapter({baseUrl:o.endpoint}),c={name:r.name||`client-${Date.now()}`,registry:n,transport:a,xchange:r.xchange,postQuantumSig:r.postQuantumSig},s=await Agent.create(c);return s.ok?ok({agent:s.value,service:o,did:o.did,endpoint:o.endpoint}):err({code:ConnectErrorCode.AGENT_CREATION_FAILED,message:"Failed to create agent",cause:s.error})}export async function acceptInvite(e,r={}){const{InviteService:t}=await import("./invite.js"),i=new t,o=await i.get(e);if(!o.ok)return err({code:ConnectErrorCode.DISCOVERY_FAILED,message:`Failed to get invite: ${o.error.message}`,cause:o.error});const n=o.value,a={name:n.from.name,did:n.from.did,endpoint:n.from.endpoint,publicKey:n.from.publicKey,x25519PublicKey:n.from.x25519PublicKey,mlKemPublicKey:n.from.mlKemPublicKey},c=r.registry||new MemoryTrustRegistry;try{const e=fromBase64(a.publicKey),r=await importPublicKey(e);if(!r.ok)return err({code:ConnectErrorCode.TRUST_VERIFICATION_FAILED,message:"Invalid service public key",cause:r.error});await c.add({did:a.did,publicKey:r.value,x25519PublicKey:a.x25519PublicKey?await importPublicKey(fromBase64(a.x25519PublicKey)).then(e=>e.ok?e.value:void 0):void 0,mlKemPublicKey:a.mlKemPublicKey?fromBase64(a.mlKemPublicKey):void 0})}catch(e){return err({code:ConnectErrorCode.TRUST_VERIFICATION_FAILED,message:"Failed to verify service public key",cause:e})}const s=r.transport||new HttpsTransportAdapter({baseUrl:a.endpoint}),d={name:r.name||`client-${Date.now()}`,registry:c,transport:s,xchange:r.xchange,postQuantumSig:r.postQuantumSig},u=await Agent.create(d);if(!u.ok)return err({code:ConnectErrorCode.AGENT_CREATION_FAILED,message:"Failed to create agent",cause:u.error});return(await i.accept({inviteUrl:e,acceptor:{name:d.name,did:u.value.did,endpoint:r.endpoint||"",publicKey:toBase64(u.value.identity.rawPublicKey),x25519PublicKey:u.value.identity.rawX25519PublicKey?toBase64(u.value.identity.rawX25519PublicKey):void 0}})).ok,ok({agent:u.value,service:a,did:a.did,endpoint:a.endpoint})}
+/**
+ * @module connect
+ * High-level connect() API for zero-config XBind connections.
+ *
+ * Enables: `const service = await connect('payments-service')`
+ *
+ * Combines:
+ * - Service discovery
+ * - Trust verification
+ * - Agent creation
+ * - Connection establishment
+ *
+ * @example
+ * ```ts
+ * import { connect } from '@private.me/xbind';
+ *
+ * // Connect by name (uses registry):
+ * const payments = await connect('payments-service');
+ *
+ * // Connect by domain (uses .well-known):
+ * const payments = await connect('payments.example.com');
+ *
+ * // Connect by URL (direct):
+ * const payments = await connect('https://api.payments.com/xbind');
+ *
+ * // Use the connection:
+ * await payments.send({
+ *   to: payments.did,
+ *   payload: { action: 'createCharge', amount: 100 },
+ *   scope: 'payments',
+ * });
+ * ```
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { fromBase64, toBase64 } from './crypto-utils.js';
+import { Agent } from './agent.js';
+import { ServiceDiscovery } from './discovery.js';
+import { HttpsTransportAdapter } from './transport.js';
+import { MemoryTrustRegistry } from './trust-registry.js';
+import { importPublicKey } from './identity.js';
+/**
+ * Connect error codes.
+ */
+export var ConnectErrorCode;
+(function (ConnectErrorCode) {
+    ConnectErrorCode["DISCOVERY_FAILED"] = "CONNECT_DISCOVERY_FAILED";
+    ConnectErrorCode["AGENT_CREATION_FAILED"] = "CONNECT_AGENT_CREATION_FAILED";
+    ConnectErrorCode["TRUST_VERIFICATION_FAILED"] = "CONNECT_TRUST_VERIFICATION_FAILED";
+    ConnectErrorCode["INVALID_SERVICE_INFO"] = "CONNECT_INVALID_SERVICE_INFO";
+})(ConnectErrorCode || (ConnectErrorCode = {}));
+/**
+ * Connect to a service with zero configuration.
+ *
+ * @param nameOrUrl - Service name, domain, or URL
+ * @param options - Connection options
+ * @returns Connection or error
+ *
+ * @example
+ * ```ts
+ * // Minimal:
+ * const connection = await connect('payments-service');
+ * if (connection.ok) {
+ *   await connection.value.agent.send({
+ *     to: connection.value.did,
+ *     payload: { action: 'test' },
+ *     scope: 'test',
+ *   });
+ * }
+ *
+ * // With options:
+ * const connection = await connect('payments-service', {
+ *   name: 'billing-service',
+ *   xchange: true, // Use faster Xchange mode
+ *   splitChannel: true, // Use split-channel by default
+ * });
+ * ```
+ */
+export async function connect(nameOrUrl, options = {}) {
+    // Step 1: Discover service
+    const discovery = options.discovery || new ServiceDiscovery();
+    const serviceResult = await discovery.discover(nameOrUrl);
+    if (!serviceResult.ok) {
+        return err({
+            code: ConnectErrorCode.DISCOVERY_FAILED,
+            message: `Failed to discover service: ${serviceResult.error.message}`,
+            hint: serviceResult.error.hint,
+            cause: serviceResult.error,
+        });
+    }
+    const service = serviceResult.value;
+    // Step 2: Validate service info
+    if (!service.did || !service.endpoint || !service.publicKey) {
+        return err({
+            code: ConnectErrorCode.INVALID_SERVICE_INFO,
+            message: 'Service info missing required fields (did, endpoint, publicKey)',
+            hint: 'Service must provide complete metadata',
+        });
+    }
+    // Step 3: Create trust registry and add service
+    const registry = options.registry || new MemoryTrustRegistry();
+    try {
+        // Import public key (convert from base64 string)
+        const publicKeyBytes = fromBase64(service.publicKey);
+        const publicKeyResult = await importPublicKey(publicKeyBytes);
+        if (!publicKeyResult.ok) {
+            return err({
+                code: ConnectErrorCode.TRUST_VERIFICATION_FAILED,
+                message: 'Invalid service public key',
+                cause: publicKeyResult.error,
+            });
+        }
+        // Add to trust registry
+        await registry.add({
+            did: service.did,
+            publicKey: publicKeyResult.value,
+            x25519PublicKey: service.x25519PublicKey
+                ? await importPublicKey(fromBase64(service.x25519PublicKey)).then(r => r.ok ? r.value : undefined)
+                : undefined,
+            mlKemPublicKey: service.mlKemPublicKey
+                ? fromBase64(service.mlKemPublicKey)
+                : undefined,
+        });
+    }
+    catch (error) {
+        return err({
+            code: ConnectErrorCode.TRUST_VERIFICATION_FAILED,
+            message: 'Failed to verify service public key',
+            cause: error,
+        });
+    }
+    // Step 4: Create transport
+    const transport = options.transport || new HttpsTransportAdapter({
+        baseUrl: service.endpoint,
+    });
+    // Step 5: Create agent
+    const agentName = options.name || `client-${Date.now()}`;
+    const agentOptions = {
+        name: agentName,
+        registry,
+        transport,
+        xchange: options.xchange,
+        postQuantumSig: options.postQuantumSig,
+    };
+    const agentResult = await Agent.create(agentOptions);
+    if (!agentResult.ok) {
+        return err({
+            code: ConnectErrorCode.AGENT_CREATION_FAILED,
+            message: 'Failed to create agent',
+            cause: agentResult.error,
+        });
+    }
+    // Step 6: Return connection
+    return ok({
+        agent: agentResult.value,
+        service,
+        did: service.did,
+        endpoint: service.endpoint,
+    });
+}
+/**
+ * Accept an invite and establish connection.
+ *
+ * @param inviteUrl - Invite URL
+ * @param options - Connection options
+ * @returns Connection or error
+ *
+ * @example
+ * ```ts
+ * const connection = await acceptInvite('https://xbind.to/invite/abc123', {
+ *   name: 'my-service',
+ * });
+ *
+ * if (connection.ok) {
+ *   console.log('Connected to:', connection.value.service.name);
+ * }
+ * ```
+ */
+export async function acceptInvite(inviteUrl, options = {}) {
+    const { InviteService } = await import('./invite.js');
+    const inviteService = new InviteService();
+    // Get invite details
+    const inviteResult = await inviteService.get(inviteUrl);
+    if (!inviteResult.ok) {
+        return err({
+            code: ConnectErrorCode.DISCOVERY_FAILED,
+            message: `Failed to get invite: ${inviteResult.error.message}`,
+            cause: inviteResult.error,
+        });
+    }
+    const invite = inviteResult.value;
+    // Convert invite.from to ServiceInfo
+    const service = {
+        name: invite.from.name,
+        did: invite.from.did,
+        endpoint: invite.from.endpoint,
+        publicKey: invite.from.publicKey,
+        x25519PublicKey: invite.from.x25519PublicKey,
+        mlKemPublicKey: invite.from.mlKemPublicKey,
+    };
+    // Connect to service (same as connect())
+    // Create trust registry and add service
+    const registry = options.registry || new MemoryTrustRegistry();
+    try {
+        // Import public key (convert from base64 string)
+        const publicKeyBytes = fromBase64(service.publicKey);
+        const publicKeyResult = await importPublicKey(publicKeyBytes);
+        if (!publicKeyResult.ok) {
+            return err({
+                code: ConnectErrorCode.TRUST_VERIFICATION_FAILED,
+                message: 'Invalid service public key',
+                cause: publicKeyResult.error,
+            });
+        }
+        await registry.add({
+            did: service.did,
+            publicKey: publicKeyResult.value,
+            x25519PublicKey: service.x25519PublicKey
+                ? await importPublicKey(fromBase64(service.x25519PublicKey)).then(r => r.ok ? r.value : undefined)
+                : undefined,
+            mlKemPublicKey: service.mlKemPublicKey
+                ? fromBase64(service.mlKemPublicKey)
+                : undefined,
+        });
+    }
+    catch (error) {
+        return err({
+            code: ConnectErrorCode.TRUST_VERIFICATION_FAILED,
+            message: 'Failed to verify service public key',
+            cause: error,
+        });
+    }
+    const transport = options.transport || new HttpsTransportAdapter({
+        baseUrl: service.endpoint,
+    });
+    const agentName = options.name || `client-${Date.now()}`;
+    const agentOptions = {
+        name: agentName,
+        registry,
+        transport,
+        xchange: options.xchange,
+        postQuantumSig: options.postQuantumSig,
+    };
+    const agentResult = await Agent.create(agentOptions);
+    if (!agentResult.ok) {
+        return err({
+            code: ConnectErrorCode.AGENT_CREATION_FAILED,
+            message: 'Failed to create agent',
+            cause: agentResult.error,
+        });
+    }
+    // Accept the invite
+    const acceptResult = await inviteService.accept({
+        inviteUrl,
+        acceptor: {
+            name: agentOptions.name,
+            did: agentResult.value.did,
+            endpoint: options.endpoint || '', // Agent's endpoint (where it can be reached), empty for client-only agents
+            publicKey: toBase64(agentResult.value.identity.rawPublicKey),
+            x25519PublicKey: agentResult.value.identity.rawX25519PublicKey
+                ? toBase64(agentResult.value.identity.rawX25519PublicKey)
+                : undefined,
+        },
+    });
+    if (!acceptResult.ok) {
+        // Connection created but invite acceptance failed - still return connection
+        // (invite acceptance is for tracking/notification, not required for connectivity)
+    }
+    return ok({
+        agent: agentResult.value,
+        service,
+        did: service.did,
+        endpoint: service.endpoint,
+    });
+}