@private.me/xbind 1.2.0

package/dist-standalone/invite.d.ts

@@ -0,0 +1,192 @@
+/**
+ * @module invite
+ * Viral invite system for XBind connections.
+ *
+ * Enables one-click invites:
+ * - Generate: `xbind invite payments-service`
+ * - Accept: Click link or `xbind accept https://xbind.to/invite/abc123`
+ *
+ * The viral loop:
+ * 1. Service A invites Service B
+ * 2. Service B clicks link (< 60 sec setup)
+ * 3. Connection established
+ * 4. Service B invites Service C
+ */
+import { Result } from '@private.me/shared';
+import type { ServiceInfo } from './discovery.js';
+/**
+ * Invite data structure.
+ */
+export interface Invite {
+    /** Unique invite ID */
+    id: string;
+    /** Service that sent the invite */
+    from: {
+        name: string;
+        did: string;
+        endpoint: string;
+        publicKey: string;
+        x25519PublicKey?: string;
+        mlKemPublicKey?: string;
+    };
+    /** Target service (optional, can be open invite) */
+    to?: {
+        name?: string;
+        email?: string;
+    };
+    /** Suggested permissions/template */
+    template?: string;
+    /** Custom permissions */
+    permissions?: string[];
+    /** Invite expiration (ISO timestamp) */
+    expires: string;
+    /** Invite URL */
+    url: string;
+    /** QR code data URL (for airgapped) */
+    qr?: string;
+}
+/**
+ * Invite error codes.
+ */
+export declare enum InviteErrorCode {
+    INVALID_INVITE = "INVITE_INVALID",
+    EXPIRED_INVITE = "INVITE_EXPIRED",
+    INVITE_NOT_FOUND = "INVITE_NOT_FOUND",
+    NETWORK_ERROR = "INVITE_NETWORK_ERROR",
+    ALREADY_CONNECTED = "INVITE_ALREADY_CONNECTED"
+}
+/**
+ * Invite error.
+ */
+export interface InviteError {
+    code: InviteErrorCode;
+    message: string;
+    hint?: string;
+}
+/**
+ * Invite service for creating and accepting invites.
+ */
+export declare class InviteService {
+    private inviteApiUrl;
+    /**
+     * Create invite service.
+     *
+     * @param options - Configuration
+     * @param options.inviteApiUrl - Invite API URL (default: https://xbind.to)
+     */
+    constructor(options?: {
+        inviteApiUrl?: string;
+    });
+    /**
+     * Create an invite.
+     *
+     * @param options - Invite options
+     * @param options.from - Sender service info
+     * @param options.target - Target service (optional)
+     * @param options.template - Suggested template (e.g., "payment-processing")
+     * @param options.permissions - Custom permissions
+     * @param options.expiresIn - Expiration in seconds (default: 7 days)
+     * @returns Invite or error
+     *
+     * @example
+     * ```ts
+     * const inviteService = new InviteService();
+     * const invite = await inviteService.create({
+     *   from: {
+     *     name: 'billing-service',
+     *     did: 'did:key:z6Mk...',
+     *     endpoint: 'https://billing.example.com',
+     *     publicKey: '...',
+     *   },
+     *   target: {
+     *     name: 'payments-service',
+     *   },
+     *   template: 'payment-processing',
+     * });
+     *
+     * // Share invite.value.url or invite.value.qr
+     * ```
+     */
+    create(options: {
+        from: ServiceInfo;
+        target?: {
+            name?: string;
+            email?: string;
+        };
+        template?: string;
+        permissions?: string[];
+        expiresIn?: number;
+    }): Promise<Result<Invite, InviteError>>;
+    /**
+     * Accept an invite.
+     *
+     * @param options - Accept options
+     * @param options.inviteUrl - Invite URL (e.g., https://xbind.to/invite/abc123)
+     * @param options.acceptor - Acceptor service info
+     * @returns Connection info or error
+     *
+     * @example
+     * ```ts
+     * const inviteService = new InviteService();
+     * const result = await inviteService.accept({
+     *   inviteUrl: 'https://xbind.to/invite/abc123',
+     *   acceptor: {
+     *     name: 'payments-service',
+     *     did: 'did:key:z6Mk...',
+     *     endpoint: 'https://payments.example.com',
+     *     publicKey: '...',
+     *   }
+     * });
+     *
+     * if (result.ok) {
+     *   console.log('Connected!');
+     * }
+     * ```
+     */
+    accept(options: {
+        inviteUrl: string;
+        acceptor: ServiceInfo;
+    }): Promise<Result<{
+        success: boolean;
+        connection: ServiceInfo;
+    }, InviteError>>;
+    /**
+     * Get invite details without accepting.
+     *
+     * @param inviteUrl - Invite URL
+     * @returns Invite details or error
+     */
+    get(inviteUrl: string): Promise<Result<Invite, InviteError>>;
+    /**
+     * Revoke an invite.
+     *
+     * @param inviteId - Invite ID to revoke
+     * @returns Success or error
+     *
+     * @example
+     * ```ts
+     * const inviteService = new InviteService();
+     * const result = await inviteService.revoke('inv_abc123');
+     *
+     * if (result.ok) {
+     *   console.log('Invite revoked');
+     * }
+     * ```
+     */
+    revoke(inviteId: string): Promise<Result<{
+        success: boolean;
+    }, InviteError>>;
+    /**
+     * Extract invite ID from URL.
+     *
+     * @param url - Invite URL
+     * @returns Invite ID or null
+     *
+     * @example
+     * ```ts
+     * extractInviteId('https://xbind.to/invite/abc123') // 'abc123'
+     * extractInviteId('https://xbind.to/billing/invite/xyz') // 'xyz'
+     * ```
+     */
+    private extractInviteId;
+}

package/dist-standalone/invite.js

@@ -0,0 +1,324 @@
+/**
+ * @module invite
+ * Viral invite system for XBind connections.
+ *
+ * Enables one-click invites:
+ * - Generate: `xbind invite payments-service`
+ * - Accept: Click link or `xbind accept https://xbind.to/invite/abc123`
+ *
+ * The viral loop:
+ * 1. Service A invites Service B
+ * 2. Service B clicks link (< 60 sec setup)
+ * 3. Connection established
+ * 4. Service B invites Service C
+ */
+import { ok, err } from"./_deps/shared/index.js";
+/**
+ * Invite error codes.
+ */
+export var InviteErrorCode;
+(function (InviteErrorCode) {
+    InviteErrorCode["INVALID_INVITE"] = "INVITE_INVALID";
+    InviteErrorCode["EXPIRED_INVITE"] = "INVITE_EXPIRED";
+    InviteErrorCode["INVITE_NOT_FOUND"] = "INVITE_NOT_FOUND";
+    InviteErrorCode["NETWORK_ERROR"] = "INVITE_NETWORK_ERROR";
+    InviteErrorCode["ALREADY_CONNECTED"] = "INVITE_ALREADY_CONNECTED";
+})(InviteErrorCode || (InviteErrorCode = {}));
+/**
+ * Invite service for creating and accepting invites.
+ */
+export class InviteService {
+    inviteApiUrl;
+    /**
+     * Create invite service.
+     *
+     * @param options - Configuration
+     * @param options.inviteApiUrl - Invite API URL (default: https://xbind.to)
+     */
+    constructor(options = {}) {
+        this.inviteApiUrl = options.inviteApiUrl || 'https://xbind.to';
+    }
+    /**
+     * Create an invite.
+     *
+     * @param options - Invite options
+     * @param options.from - Sender service info
+     * @param options.target - Target service (optional)
+     * @param options.template - Suggested template (e.g., "payment-processing")
+     * @param options.permissions - Custom permissions
+     * @param options.expiresIn - Expiration in seconds (default: 7 days)
+     * @returns Invite or error
+     *
+     * @example
+     * ```ts
+     * const inviteService = new InviteService();
+     * const invite = await inviteService.create({
+     *   from: {
+     *     name: 'billing-service',
+     *     did: 'did:key:z6Mk...',
+     *     endpoint: 'https://billing.example.com',
+     *     publicKey: '...',
+     *   },
+     *   target: {
+     *     name: 'payments-service',
+     *   },
+     *   template: 'payment-processing',
+     * });
+     *
+     * // Share invite.value.url or invite.value.qr
+     * ```
+     */
+    async create(options) {
+        const expiresIn = options.expiresIn || 7 * 24 * 60 * 60; // 7 days
+        const expires = new Date(Date.now() + expiresIn * 1000).toISOString();
+        try {
+            const response = await fetch(`${this.inviteApiUrl}/invites/create`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    from: {
+                        name: options.from.name,
+                        did: options.from.did,
+                        endpoint: options.from.endpoint,
+                        publicKey: options.from.publicKey,
+                        x25519PublicKey: options.from.x25519PublicKey,
+                        mlKemPublicKey: options.from.mlKemPublicKey,
+                    },
+                    to: options.target,
+                    template: options.template,
+                    permissions: options.permissions,
+                    expires,
+                }),
+            });
+            if (!response.ok) {
+                return err({
+                    code: InviteErrorCode.NETWORK_ERROR,
+                    message: `Failed to create invite: ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            return ok(data);
+        }
+        catch (error) {
+            return err({
+                code: InviteErrorCode.NETWORK_ERROR,
+                message: error instanceof Error ? error.message : 'Network error',
+            });
+        }
+    }
+    /**
+     * Accept an invite.
+     *
+     * @param options - Accept options
+     * @param options.inviteUrl - Invite URL (e.g., https://xbind.to/invite/abc123)
+     * @param options.acceptor - Acceptor service info
+     * @returns Connection info or error
+     *
+     * @example
+     * ```ts
+     * const inviteService = new InviteService();
+     * const result = await inviteService.accept({
+     *   inviteUrl: 'https://xbind.to/invite/abc123',
+     *   acceptor: {
+     *     name: 'payments-service',
+     *     did: 'did:key:z6Mk...',
+     *     endpoint: 'https://payments.example.com',
+     *     publicKey: '...',
+     *   }
+     * });
+     *
+     * if (result.ok) {
+     *   console.log('Connected!');
+     * }
+     * ```
+     */
+    async accept(options) {
+        try {
+            // Extract invite ID from URL
+            const inviteId = this.extractInviteId(options.inviteUrl);
+            if (!inviteId) {
+                return err({
+                    code: InviteErrorCode.INVALID_INVITE,
+                    message: 'Invalid invite URL',
+                    hint: 'URL should be like: https://xbind.to/invite/abc123',
+                });
+            }
+            // Accept invite
+            const response = await fetch(`${this.inviteApiUrl}/invites/${inviteId}/accept`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    acceptor: {
+                        name: options.acceptor.name,
+                        did: options.acceptor.did,
+                        endpoint: options.acceptor.endpoint,
+                        publicKey: options.acceptor.publicKey,
+                        x25519PublicKey: options.acceptor.x25519PublicKey,
+                        mlKemPublicKey: options.acceptor.mlKemPublicKey,
+                    },
+                }),
+            });
+            if (response.status === 404) {
+                return err({
+                    code: InviteErrorCode.INVITE_NOT_FOUND,
+                    message: 'Invite not found or expired',
+                    hint: 'The invite may have been revoked or expired',
+                });
+            }
+            if (response.status === 410) {
+                const errorData = await response.json().catch(() => ({}));
+                return err({
+                    code: InviteErrorCode.EXPIRED_INVITE,
+                    message: errorData.message || 'Invite has expired',
+                    hint: errorData.hint || 'Ask the sender to create a new invite',
+                });
+            }
+            if (response.status === 409) {
+                return err({
+                    code: InviteErrorCode.ALREADY_CONNECTED,
+                    message: 'Services are already connected',
+                    hint: 'You are already connected to this service',
+                });
+            }
+            if (!response.ok) {
+                return err({
+                    code: InviteErrorCode.NETWORK_ERROR,
+                    message: `Failed to accept invite: ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            return ok(data);
+        }
+        catch (error) {
+            return err({
+                code: InviteErrorCode.NETWORK_ERROR,
+                message: error instanceof Error ? error.message : 'Network error',
+                hint: 'Check your network connection and try again',
+            });
+        }
+    }
+    /**
+     * Get invite details without accepting.
+     *
+     * @param inviteUrl - Invite URL
+     * @returns Invite details or error
+     */
+    async get(inviteUrl) {
+        try {
+            const inviteId = this.extractInviteId(inviteUrl);
+            if (!inviteId) {
+                return err({
+                    code: InviteErrorCode.INVALID_INVITE,
+                    message: 'Invalid invite URL',
+                });
+            }
+            const response = await fetch(`${this.inviteApiUrl}/invites/${inviteId}`, {
+                headers: {
+                    'Accept': 'application/json',
+                },
+            });
+            if (response.status === 404) {
+                return err({
+                    code: InviteErrorCode.INVITE_NOT_FOUND,
+                    message: 'Invite not found',
+                });
+            }
+            if (!response.ok) {
+                return err({
+                    code: InviteErrorCode.NETWORK_ERROR,
+                    message: `Failed to get invite: ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            return ok(data);
+        }
+        catch (error) {
+            return err({
+                code: InviteErrorCode.NETWORK_ERROR,
+                message: error instanceof Error ? error.message : 'Network error',
+            });
+        }
+    }
+    /**
+     * Revoke an invite.
+     *
+     * @param inviteId - Invite ID to revoke
+     * @returns Success or error
+     *
+     * @example
+     * ```ts
+     * const inviteService = new InviteService();
+     * const result = await inviteService.revoke('inv_abc123');
+     *
+     * if (result.ok) {
+     *   console.log('Invite revoked');
+     * }
+     * ```
+     */
+    async revoke(inviteId) {
+        try {
+            const response = await fetch(`${this.inviteApiUrl}/invites/${inviteId}/revoke`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+            });
+            if (response.status === 404) {
+                return err({
+                    code: InviteErrorCode.INVITE_NOT_FOUND,
+                    message: 'Invite not found',
+                    hint: 'The invite may have already been revoked or expired',
+                });
+            }
+            if (!response.ok) {
+                return err({
+                    code: InviteErrorCode.NETWORK_ERROR,
+                    message: `Failed to revoke invite: ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            return ok(data);
+        }
+        catch (error) {
+            return err({
+                code: InviteErrorCode.NETWORK_ERROR,
+                message: error instanceof Error ? error.message : 'Network error',
+            });
+        }
+    }
+    /**
+     * Extract invite ID from URL.
+     *
+     * @param url - Invite URL
+     * @returns Invite ID or null
+     *
+     * @example
+     * ```ts
+     * extractInviteId('https://xbind.to/invite/abc123') // 'abc123'
+     * extractInviteId('https://xbind.to/billing/invite/xyz') // 'xyz'
+     * ```
+     */
+    extractInviteId(url) {
+        try {
+            const parsed = new URL(url);
+            const segments = parsed.pathname.split('/').filter(s => s.length > 0);
+            // Look for 'invite' segment followed by ID
+            const inviteIndex = segments.indexOf('invite');
+            if (inviteIndex !== -1 && segments[inviteIndex + 1]) {
+                return segments[inviteIndex + 1] ?? null;
+            }
+            // Fallback: last segment
+            if (segments.length > 0) {
+                return segments[segments.length - 1] ?? null;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist-standalone/key-agreement.d.ts

@@ -0,0 +1,122 @@
+import type { Result } from '@private.me/shared';
+/** X25519 ephemeral key pair for ECDH key agreement. */
+export interface EphemeralKeyPair {
+    /** Web Crypto private key handle (X25519). */
+    readonly privateKey: CryptoKey;
+    /** Web Crypto public key handle (X25519). */
+    readonly publicKey: CryptoKey;
+    /** Raw 32-byte X25519 public key for wire transport. */
+    readonly rawPublicKey: Uint8Array;
+}
+/** Result of ECDH key agreement. */
+export interface KeyAgreementResult {
+    /** Derived AES-256-GCM shared key. */
+    readonly sharedKey: CryptoKey;
+    /** Ephemeral public key to include in envelope. */
+    readonly ephemeralPublicKey: Uint8Array;
+}
+/** Result of hybrid (X25519 + ML-KEM-768) key agreement. */
+export interface HybridKeyAgreementResult {
+    /** Derived AES-256-GCM shared key (from HKDF over X25519 + ML-KEM shared secrets). */
+    readonly sharedKey: CryptoKey;
+    /** Ephemeral X25519 public key to include in envelope (32 bytes). */
+    readonly ephemeralPublicKey: Uint8Array;
+    /** ML-KEM-768 ciphertext to include in envelope (1088 bytes). */
+    readonly kemCiphertext: Uint8Array;
+}
+/** Error codes for key agreement operations. Sub-codes give context. */
+export type KeyAgreementError = 'KEYGEN_FAILED' | 'DERIVE_FAILED' | 'IMPORT_FAILED' | 'INVALID_KEY_LENGTH' | 'INVALID_KEY_LENGTH:EXPECTED_32' | 'KEM_ENCAPSULATE_FAILED' | 'KEM_DECAPSULATE_FAILED' | 'HKDF_FAILED';
+/**
+ * Generate an ephemeral X25519 key pair for ECDH key agreement.
+ *
+ * Uses Web Crypto API to generate a fresh X25519 key pair.
+ * The key pair is ephemeral -- it should be used for a single
+ * key agreement and then discarded.
+ *
+ * @returns Result containing the ephemeral key pair or error.
+ */
+export declare function generateEphemeralKeyPair(): Promise<Result<EphemeralKeyPair, KeyAgreementError>>;
+/**
+ * Import a raw 32-byte X25519 public key into a CryptoKey.
+ *
+ * Used by the receiver to import the sender's ephemeral public
+ * key from the envelope for ECDH derivation.
+ *
+ * @param rawPublicKey - Raw 32-byte X25519 public key.
+ * @returns Result containing the imported CryptoKey or error.
+ */
+export declare function importX25519PublicKey(rawPublicKey: Uint8Array): Promise<Result<CryptoKey, KeyAgreementError>>;
+/**
+ * Derive a shared AES-256-GCM key via X25519 ECDH.
+ *
+ * Performs ECDH key agreement between a local private key and a
+ * remote public key, producing 256 bits of shared secret that
+ * are imported as an AES-256-GCM key.
+ *
+ * @param localPrivateKey - Local X25519 private key.
+ * @param remotePublicKey - Remote X25519 public key (CryptoKey).
+ * @returns Result containing the derived AES-256-GCM key or error.
+ */
+export declare function deriveSharedKeyECDH(localPrivateKey: CryptoKey, remotePublicKey: CryptoKey): Promise<Result<CryptoKey, KeyAgreementError>>;
+/**
+ * Perform sender-side ECDH key agreement.
+ *
+ * Generates an ephemeral X25519 key pair, derives a shared key
+ * with the recipient's static X25519 public key, and returns
+ * both the shared key and the ephemeral public key to include
+ * in the envelope.
+ *
+ * @param recipientX25519PubKey - Recipient's static X25519 public key.
+ * @returns Result containing the key agreement result or error.
+ */
+export declare function senderKeyAgreement(recipientX25519PubKey: CryptoKey): Promise<Result<KeyAgreementResult, KeyAgreementError>>;
+/**
+ * Perform receiver-side ECDH key agreement.
+ *
+ * Imports the sender's ephemeral public key from the envelope
+ * and derives the shared key using the receiver's static X25519
+ * private key.
+ *
+ * @param receiverPrivateKey - Receiver's static X25519 private key.
+ * @param senderEphemeralPubRaw - Sender's ephemeral public key (raw bytes).
+ * @returns Result containing the derived AES-256-GCM key or error.
+ */
+export declare function receiverKeyAgreement(receiverPrivateKey: CryptoKey, senderEphemeralPubRaw: Uint8Array): Promise<Result<CryptoKey, KeyAgreementError>>;
+/**
+ * Combine X25519 and ML-KEM shared secrets via HKDF-SHA256.
+ *
+ * Concatenates 32B X25519 + 32B ML-KEM shared secrets, runs HKDF
+ * with zero salt and 'xail-hybrid-kem-v2' info, outputs 256-bit AES key.
+ * Secure as long as either X25519 OR ML-KEM remains unbroken.
+ *
+ * @param x25519Shared - 32-byte raw X25519 ECDH shared bits.
+ * @param mlKemShared - 32-byte ML-KEM-768 shared secret.
+ * @returns AES-256-GCM CryptoKey derived from both secrets.
+ */
+export declare function combineSharedSecrets(x25519Shared: Uint8Array, mlKemShared: Uint8Array): Promise<Result<CryptoKey, KeyAgreementError>>;
+/**
+ * Perform sender-side hybrid key agreement (X25519 + ML-KEM-768).
+ *
+ * 1. Generate ephemeral X25519, ECDH → x25519SharedBits
+ * 2. ML-KEM-768 encapsulate → kemCiphertext + mlKemShared
+ * 3. HKDF(x25519Shared || mlKemShared) → AES-256-GCM key
+ *
+ * @param recipientX25519Pub - Recipient's static X25519 public key.
+ * @param recipientMlKemPub - Recipient's ML-KEM-768 public key (1184B).
+ * @returns Hybrid key agreement result with shared key, ephemeral pub, and KEM ciphertext.
+ */
+export declare function senderHybridKeyAgreement(recipientX25519Pub: CryptoKey, recipientMlKemPub: Uint8Array): Promise<Result<HybridKeyAgreementResult, KeyAgreementError>>;
+/**
+ * Perform receiver-side hybrid key agreement (X25519 + ML-KEM-768).
+ *
+ * 1. Import ephemeral X25519, ECDH → x25519SharedBits
+ * 2. ML-KEM-768 decapsulate → mlKemShared
+ * 3. HKDF(x25519Shared || mlKemShared) → same AES-256-GCM key
+ *
+ * @param x25519PrivateKey - Receiver's static X25519 private key.
+ * @param ephPubRaw - Sender's ephemeral X25519 public key (32B).
+ * @param kemCiphertext - ML-KEM-768 ciphertext from sender (1088B).
+ * @param mlKemSecretKey - Receiver's ML-KEM-768 secret key (2400B).
+ * @returns AES-256-GCM shared key or error.
+ */
+export declare function receiverHybridKeyAgreement(x25519PrivateKey: CryptoKey, ephPubRaw: Uint8Array, kemCiphertext: Uint8Array, mlKemSecretKey: Uint8Array): Promise<Result<CryptoKey, KeyAgreementError>>;