@private.me/xbind 1.2.0

package/dist-standalone/cjs/invite.js

@@ -0,0 +1,328 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InviteService = exports.InviteErrorCode = void 0;
+const shared_1 = require("../_deps/shared/index.js");
+/**
+ * Invite error codes.
+ */
+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 || (exports.InviteErrorCode = InviteErrorCode = {}));
+/**
+ * Invite service for creating and accepting invites.
+ */
+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 (0, shared_1.err)({
+                    code: InviteErrorCode.NETWORK_ERROR,
+                    message: `Failed to create invite: ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            return (0, shared_1.ok)(data);
+        }
+        catch (error) {
+            return (0, shared_1.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 (0, shared_1.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 (0, shared_1.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 (0, shared_1.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 (0, shared_1.err)({
+                    code: InviteErrorCode.ALREADY_CONNECTED,
+                    message: 'Services are already connected',
+                    hint: 'You are already connected to this service',
+                });
+            }
+            if (!response.ok) {
+                return (0, shared_1.err)({
+                    code: InviteErrorCode.NETWORK_ERROR,
+                    message: `Failed to accept invite: ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            return (0, shared_1.ok)(data);
+        }
+        catch (error) {
+            return (0, shared_1.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 (0, shared_1.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 (0, shared_1.err)({
+                    code: InviteErrorCode.INVITE_NOT_FOUND,
+                    message: 'Invite not found',
+                });
+            }
+            if (!response.ok) {
+                return (0, shared_1.err)({
+                    code: InviteErrorCode.NETWORK_ERROR,
+                    message: `Failed to get invite: ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            return (0, shared_1.ok)(data);
+        }
+        catch (error) {
+            return (0, shared_1.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 (0, shared_1.err)({
+                    code: InviteErrorCode.INVITE_NOT_FOUND,
+                    message: 'Invite not found',
+                    hint: 'The invite may have already been revoked or expired',
+                });
+            }
+            if (!response.ok) {
+                return (0, shared_1.err)({
+                    code: InviteErrorCode.NETWORK_ERROR,
+                    message: `Failed to revoke invite: ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            return (0, shared_1.ok)(data);
+        }
+        catch (error) {
+            return (0, shared_1.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;
+        }
+    }
+}
+exports.InviteService = InviteService;

package/dist-standalone/cjs/key-agreement.js

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateEphemeralKeyPair = generateEphemeralKeyPair;
+exports.importX25519PublicKey = importX25519PublicKey;
+exports.deriveSharedKeyECDH = deriveSharedKeyECDH;
+exports.senderKeyAgreement = senderKeyAgreement;
+exports.receiverKeyAgreement = receiverKeyAgreement;
+exports.combineSharedSecrets = combineSharedSecrets;
+exports.senderHybridKeyAgreement = senderHybridKeyAgreement;
+exports.receiverHybridKeyAgreement = receiverHybridKeyAgreement;
+const shared_1 = require("../_deps/shared/index.js");
+const mlkem_1 = require("mlkem");
+/* -- Constants -- */
+const X25519_RAW_KEY_BYTES = 32;
+const AES_KEY_BITS = 256;
+/* -- Helpers -- */
+/** Copy Uint8Array to fresh ArrayBuffer. */
+function toArrayBuffer(data) {
+    const buf = new ArrayBuffer(data.byteLength);
+    new Uint8Array(buf).set(data);
+    return buf;
+}
+/* -- Key Generation -- */
+/**
+ * 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.
+ */
+async function generateEphemeralKeyPair() {
+    try {
+        // SAFETY: X25519 generateKey always returns CryptoKeyPair
+        const keyPair = await crypto.subtle.generateKey({ name: 'X25519' }, true, ['deriveBits']);
+        const rawPub = new Uint8Array(await crypto.subtle.exportKey('raw', keyPair.publicKey));
+        return (0, shared_1.ok)({
+            privateKey: keyPair.privateKey,
+            publicKey: keyPair.publicKey,
+            rawPublicKey: rawPub,
+        });
+    }
+    catch {
+        return (0, shared_1.err)('KEYGEN_FAILED');
+    }
+}
+/* -- Key Import -- */
+/**
+ * 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.
+ */
+async function importX25519PublicKey(rawPublicKey) {
+    if (rawPublicKey.length !== X25519_RAW_KEY_BYTES) {
+        return (0, shared_1.err)('INVALID_KEY_LENGTH:EXPECTED_32');
+    }
+    try {
+        const key = await crypto.subtle.importKey('raw', toArrayBuffer(rawPublicKey), { name: 'X25519' }, true, []);
+        return (0, shared_1.ok)(key);
+    }
+    catch {
+        return (0, shared_1.err)('IMPORT_FAILED');
+    }
+}
+/* -- ECDH Key Derivation -- */
+/**
+ * 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.
+ */
+async function deriveSharedKeyECDH(localPrivateKey, remotePublicKey) {
+    try {
+        const sharedBits = await crypto.subtle.deriveBits({ name: 'X25519', public: remotePublicKey }, localPrivateKey, AES_KEY_BITS);
+        const aesKey = await crypto.subtle.importKey('raw', sharedBits, { name: 'AES-GCM', length: AES_KEY_BITS }, false, ['encrypt', 'decrypt']);
+        return (0, shared_1.ok)(aesKey);
+    }
+    catch {
+        return (0, shared_1.err)('DERIVE_FAILED');
+    }
+}
+/* -- High-Level API -- */
+/**
+ * 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.
+ */
+async function senderKeyAgreement(recipientX25519PubKey) {
+    const ephemeral = await generateEphemeralKeyPair();
+    if (!ephemeral.ok)
+        return ephemeral;
+    const shared = await deriveSharedKeyECDH(ephemeral.value.privateKey, recipientX25519PubKey);
+    if (!shared.ok)
+        return shared;
+    return (0, shared_1.ok)({
+        sharedKey: shared.value,
+        ephemeralPublicKey: ephemeral.value.rawPublicKey,
+    });
+}
+/**
+ * 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.
+ */
+async function receiverKeyAgreement(receiverPrivateKey, senderEphemeralPubRaw) {
+    const imported = await importX25519PublicKey(senderEphemeralPubRaw);
+    if (!imported.ok)
+        return imported;
+    return deriveSharedKeyECDH(receiverPrivateKey, imported.value);
+}
+/* -- Hybrid Key Agreement (X25519 + ML-KEM-768) -- */
+const HYBRID_HKDF_INFO = 'xail-hybrid-kem-v2';
+/**
+ * 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.
+ */
+async function combineSharedSecrets(x25519Shared, mlKemShared) {
+    try {
+        const combined = new Uint8Array(x25519Shared.length + mlKemShared.length);
+        combined.set(x25519Shared);
+        combined.set(mlKemShared, x25519Shared.length);
+        const baseKey = await crypto.subtle.importKey('raw', toArrayBuffer(combined), 'HKDF', false, ['deriveBits']);
+        const derived = await crypto.subtle.deriveBits({
+            name: 'HKDF',
+            hash: 'SHA-256',
+            salt: new Uint8Array(32),
+            info: new TextEncoder().encode(HYBRID_HKDF_INFO),
+        }, baseKey, AES_KEY_BITS);
+        const aesKey = await crypto.subtle.importKey('raw', derived, { name: 'AES-GCM', length: AES_KEY_BITS }, false, ['encrypt', 'decrypt']);
+        return (0, shared_1.ok)(aesKey);
+    }
+    catch {
+        return (0, shared_1.err)('HKDF_FAILED');
+    }
+}
+/**
+ * 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.
+ */
+async function senderHybridKeyAgreement(recipientX25519Pub, recipientMlKemPub) {
+    // Step 1: Ephemeral X25519 ECDH
+    const ephemeral = await generateEphemeralKeyPair();
+    if (!ephemeral.ok)
+        return ephemeral;
+    let x25519Shared;
+    try {
+        x25519Shared = new Uint8Array(await crypto.subtle.deriveBits({ name: 'X25519', public: recipientX25519Pub }, ephemeral.value.privateKey, AES_KEY_BITS));
+    }
+    catch {
+        return (0, shared_1.err)('DERIVE_FAILED');
+    }
+    // Step 2: ML-KEM-768 encapsulate
+    let kemCipherText;
+    let kemSharedSecret;
+    try {
+        const mlkem = new mlkem_1.MlKem768();
+        const [cipherText, sharedSecret] = await mlkem.encap(recipientMlKemPub);
+        kemCipherText = cipherText;
+        kemSharedSecret = sharedSecret;
+    }
+    catch {
+        return (0, shared_1.err)('KEM_ENCAPSULATE_FAILED');
+    }
+    // Step 3: Combine via HKDF
+    const combined = await combineSharedSecrets(x25519Shared, kemSharedSecret);
+    if (!combined.ok)
+        return combined;
+    return (0, shared_1.ok)({
+        sharedKey: combined.value,
+        ephemeralPublicKey: ephemeral.value.rawPublicKey,
+        kemCiphertext: kemCipherText,
+    });
+}
+/**
+ * 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.
+ */
+async function receiverHybridKeyAgreement(x25519PrivateKey, ephPubRaw, kemCiphertext, mlKemSecretKey) {
+    // Step 1: X25519 ECDH
+    const imported = await importX25519PublicKey(ephPubRaw);
+    if (!imported.ok)
+        return imported;
+    let x25519Shared;
+    try {
+        x25519Shared = new Uint8Array(await crypto.subtle.deriveBits({ name: 'X25519', public: imported.value }, x25519PrivateKey, AES_KEY_BITS));
+    }
+    catch {
+        return (0, shared_1.err)('DERIVE_FAILED');
+    }
+    // Step 2: ML-KEM-768 decapsulate
+    let mlKemShared;
+    try {
+        const mlkem = new mlkem_1.MlKem768();
+        mlKemShared = await mlkem.decap(kemCiphertext, mlKemSecretKey);
+    }
+    catch {
+        return (0, shared_1.err)('KEM_DECAPSULATE_FAILED');
+    }
+    // Step 3: Combine via HKDF
+    return combineSharedSecrets(x25519Shared, mlKemShared);
+}