@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/cjs/invite.js

@@ -1 +1,328 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.InviteService=exports.InviteErrorCode=void 0;const shared_1=require("../_deps/shared/index.js");var InviteErrorCode;!function(e){e.INVALID_INVITE="INVITE_INVALID",e.EXPIRED_INVITE="INVITE_EXPIRED",e.INVITE_NOT_FOUND="INVITE_NOT_FOUND",e.NETWORK_ERROR="INVITE_NETWORK_ERROR",e.ALREADY_CONNECTED="INVITE_ALREADY_CONNECTED"}(InviteErrorCode||(exports.InviteErrorCode=InviteErrorCode={}));class InviteService{inviteApiUrl;constructor(e={}){this.inviteApiUrl=e.inviteApiUrl||"https://xbind.to"}async create(e){const r=e.expiresIn||604800,t=new Date(Date.now()+1e3*r).toISOString();try{const r=await fetch(`${this.inviteApiUrl}/invites/create`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({from:{name:e.from.name,did:e.from.did,endpoint:e.from.endpoint,publicKey:e.from.publicKey,x25519PublicKey:e.from.x25519PublicKey,mlKemPublicKey:e.from.mlKemPublicKey},to:e.target,template:e.template,permissions:e.permissions,expires:t})});if(!r.ok)return(0,shared_1.err)({code:InviteErrorCode.NETWORK_ERROR,message:`Failed to create invite: ${r.status}`});const i=await r.json();return(0,shared_1.ok)(i)}catch(e){return(0,shared_1.err)({code:InviteErrorCode.NETWORK_ERROR,message:e instanceof Error?e.message:"Network error"})}}async accept(e){try{const r=this.extractInviteId(e.inviteUrl);if(!r)return(0,shared_1.err)({code:InviteErrorCode.INVALID_INVITE,message:"Invalid invite URL",hint:"URL should be like: https://xbind.to/invite/abc123"});const t=await fetch(`${this.inviteApiUrl}/invites/${r}/accept`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({acceptor:{name:e.acceptor.name,did:e.acceptor.did,endpoint:e.acceptor.endpoint,publicKey:e.acceptor.publicKey,x25519PublicKey:e.acceptor.x25519PublicKey,mlKemPublicKey:e.acceptor.mlKemPublicKey}})});if(404===t.status)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(410===t.status){const e=await t.json().catch(()=>({}));return(0,shared_1.err)({code:InviteErrorCode.EXPIRED_INVITE,message:e.message||"Invite has expired",hint:e.hint||"Ask the sender to create a new invite"})}if(409===t.status)return(0,shared_1.err)({code:InviteErrorCode.ALREADY_CONNECTED,message:"Services are already connected",hint:"You are already connected to this service"});if(!t.ok)return(0,shared_1.err)({code:InviteErrorCode.NETWORK_ERROR,message:`Failed to accept invite: ${t.status}`});const i=await t.json();return(0,shared_1.ok)(i)}catch(e){return(0,shared_1.err)({code:InviteErrorCode.NETWORK_ERROR,message:e instanceof Error?e.message:"Network error",hint:"Check your network connection and try again"})}}async get(e){try{const r=this.extractInviteId(e);if(!r)return(0,shared_1.err)({code:InviteErrorCode.INVALID_INVITE,message:"Invalid invite URL"});const t=await fetch(`${this.inviteApiUrl}/invites/${r}`,{headers:{Accept:"application/json"}});if(404===t.status)return(0,shared_1.err)({code:InviteErrorCode.INVITE_NOT_FOUND,message:"Invite not found"});if(!t.ok)return(0,shared_1.err)({code:InviteErrorCode.NETWORK_ERROR,message:`Failed to get invite: ${t.status}`});const i=await t.json();return(0,shared_1.ok)(i)}catch(e){return(0,shared_1.err)({code:InviteErrorCode.NETWORK_ERROR,message:e instanceof Error?e.message:"Network error"})}}async revoke(e){try{const r=await fetch(`${this.inviteApiUrl}/invites/${e}/revoke`,{method:"POST",headers:{"Content-Type":"application/json"}});if(404===r.status)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(!r.ok)return(0,shared_1.err)({code:InviteErrorCode.NETWORK_ERROR,message:`Failed to revoke invite: ${r.status}`});const t=await r.json();return(0,shared_1.ok)(t)}catch(e){return(0,shared_1.err)({code:InviteErrorCode.NETWORK_ERROR,message:e instanceof Error?e.message:"Network error"})}}extractInviteId(e){try{const r=new URL(e).pathname.split("/").filter(e=>e.length>0),t=r.indexOf("invite");return-1!==t&&r[t+1]?r[t+1]??null:r.length>0?r[r.length-1]??null:null}catch{return null}}}exports.InviteService=InviteService;
+"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

@@ -1 +1,335 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),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"),mlkem_1=require("mlkem"),X25519_RAW_KEY_BYTES=32,AES_KEY_BITS=256;function toArrayBuffer(e){const r=new ArrayBuffer(e.byteLength);return new Uint8Array(r).set(e),r}async function generateEphemeralKeyPair(){try{const e=await crypto.subtle.generateKey({name:"X25519"},!0,["deriveBits"]),r=new Uint8Array(await crypto.subtle.exportKey("raw",e.publicKey));return(0,shared_1.ok)({privateKey:e.privateKey,publicKey:e.publicKey,rawPublicKey:r})}catch{return(0,shared_1.err)("KEYGEN_FAILED")}}async function importX25519PublicKey(e){if(e.length!==X25519_RAW_KEY_BYTES)return(0,shared_1.err)("INVALID_KEY_LENGTH:EXPECTED_32");try{const r=await crypto.subtle.importKey("raw",toArrayBuffer(e),{name:"X25519"},!0,[]);return(0,shared_1.ok)(r)}catch{return(0,shared_1.err)("IMPORT_FAILED")}}async function deriveSharedKeyECDH(e,r){try{const t=await crypto.subtle.deriveBits({name:"X25519",public:r},e,AES_KEY_BITS),a=await crypto.subtle.importKey("raw",t,{name:"AES-GCM",length:AES_KEY_BITS},!1,["encrypt","decrypt"]);return(0,shared_1.ok)(a)}catch{return(0,shared_1.err)("DERIVE_FAILED")}}async function senderKeyAgreement(e){const r=await generateEphemeralKeyPair();if(!r.ok)return r;const t=await deriveSharedKeyECDH(r.value.privateKey,e);return t.ok?(0,shared_1.ok)({sharedKey:t.value,ephemeralPublicKey:r.value.rawPublicKey}):t}async function receiverKeyAgreement(e,r){const t=await importX25519PublicKey(r);return t.ok?deriveSharedKeyECDH(e,t.value):t}const HYBRID_HKDF_INFO="xail-hybrid-kem-v2";async function combineSharedSecrets(e,r,t,a,n,i){try{const c=e.length+r.length+t.length+a.length+n.length+i.length,y=new Uint8Array(c);let s=0;y.set(e,s),s+=e.length,y.set(r,s),s+=r.length,y.set(t,s),s+=t.length,y.set(a,s),s+=a.length,y.set(n,s),s+=n.length,y.set(i,s);const o=(new TextEncoder).encode("XWingKEM"),u=await crypto.subtle.importKey("raw",toArrayBuffer(y),"HKDF",!1,["deriveBits"]),l=await crypto.subtle.deriveBits({name:"HKDF",hash:"SHA-256",salt:o,info:(new TextEncoder).encode(HYBRID_HKDF_INFO)},u,AES_KEY_BITS),K=await crypto.subtle.importKey("raw",l,{name:"AES-GCM",length:AES_KEY_BITS},!1,["encrypt","decrypt"]);return(0,shared_1.ok)(K)}catch{return(0,shared_1.err)("HKDF_FAILED")}}async function senderHybridKeyAgreement(e,r){const t=await generateEphemeralKeyPair();if(!t.ok)return t;let a,n,i,c;try{a=new Uint8Array(await crypto.subtle.deriveBits({name:"X25519",public:e},t.value.privateKey,AES_KEY_BITS))}catch{return(0,shared_1.err)("DERIVE_FAILED")}try{const e=await(0,mlkem_1.createMlKem768)(),[t,a]=e.encap(r);n=t,i=a}catch{return(0,shared_1.err)("KEM_ENCAPSULATE_FAILED")}try{const r=await crypto.subtle.exportKey("raw",e);c=new Uint8Array(r)}catch{return(0,shared_1.err)("EXPORT_KEY_FAILED")}const y=await combineSharedSecrets(i,n,a,t.value.rawPublicKey,c,r);return y.ok?(0,shared_1.ok)({sharedKey:y.value,ephemeralPublicKey:t.value.rawPublicKey,kemCiphertext:n}):y}async function receiverHybridKeyAgreement(e,r,t,a,n,i){const c=await importX25519PublicKey(t);if(!c.ok)return c;let y,s;try{y=new Uint8Array(await crypto.subtle.deriveBits({name:"X25519",public:c.value},e,AES_KEY_BITS))}catch{return(0,shared_1.err)("DERIVE_FAILED")}try{s=(await(0,mlkem_1.createMlKem768)()).decap(a,n)}catch{return(0,shared_1.err)("KEM_DECAPSULATE_FAILED")}return combineSharedSecrets(s,a,y,t,r,i)}
+"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.
+ *
+ * @example
+ * ```typescript
+ * import { generateEphemeralKeyPair } from '@private.me/xbind';
+ *
+ * const ephemeral = await generateEphemeralKeyPair();
+ * if (!ephemeral.ok) {
+ *   throw new Error(`Key generation failed: ${ephemeral.error}`);
+ * }
+ *
+ * console.log('Ephemeral public key (32 bytes):', ephemeral.value.rawPublicKey);
+ * // Use ephemeral.value.privateKey for ECDH, then discard
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```typescript
+ * import { senderKeyAgreement, importX25519PublicKey } from '@private.me/xbind';
+ *
+ * // Import recipient's X25519 public key
+ * const recipientPubKeyRaw = new Uint8Array(32); // From recipient's identity
+ * const recipientPubKey = await importX25519PublicKey(recipientPubKeyRaw);
+ * if (!recipientPubKey.ok) throw new Error(recipientPubKey.error);
+ *
+ * // Perform key agreement
+ * const agreement = await senderKeyAgreement(recipientPubKey.value);
+ * if (!agreement.ok) throw new Error(agreement.error);
+ *
+ * // Use shared key for encryption
+ * const { sharedKey, ephemeralPublicKey } = agreement.value;
+ * // Include ephemeralPublicKey in envelope header
+ * ```
+ */
+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 + ML-KEM shared secrets using IETF X-Wing combiner.
+ *
+ * IETF draft-connolly-cfrg-xwing-kem-10 compliant combiner that includes:
+ * - ML-KEM shared secret (32B)
+ * - ML-KEM ciphertext (1088B for ML-KEM-768)
+ * - X25519 shared secret (32B)
+ * - X25519 ephemeral public key (32B)
+ * - X25519 recipient public key (32B)
+ * - ML-KEM recipient public key (1184B for ML-KEM-768)
+ *
+ * This prevents Unknown Key Share (UKS) attacks, transcript manipulation,
+ * and session confusion by binding the key material to the full protocol transcript.
+ *
+ * Session 159 - CRYPTO-1: Upgraded from naive concatenation to IETF standard.
+ *
+ * @param mlKemShared - 32-byte ML-KEM-768 shared secret
+ * @param mlKemCiphertext - 1088-byte ML-KEM-768 ciphertext
+ * @param x25519Shared - 32-byte raw X25519 ECDH shared secret
+ * @param x25519EphemeralPub - 32-byte sender's ephemeral X25519 public key
+ * @param x25519RecipientPub - 32-byte recipient's static X25519 public key
+ * @param mlKemRecipientPub - 1184-byte recipient's ML-KEM-768 public key
+ * @returns AES-256-GCM CryptoKey derived using IETF X-Wing combiner
+ */
+async function combineSharedSecrets(mlKemShared, mlKemCiphertext, x25519Shared, x25519EphemeralPub, x25519RecipientPub, mlKemRecipientPub) {
+    try {
+        // IETF X-Wing combiner: concat all key material + ciphertexts + public keys
+        // This binds the shared secret to the full protocol transcript
+        const totalLength = mlKemShared.length + // 32B
+            mlKemCiphertext.length + // 1088B
+            x25519Shared.length + // 32B
+            x25519EphemeralPub.length + // 32B
+            x25519RecipientPub.length + // 32B
+            mlKemRecipientPub.length; // 1184B
+        // Total: 2400B
+        const combined = new Uint8Array(totalLength);
+        let offset = 0;
+        // Concatenate in IETF X-Wing order
+        combined.set(mlKemShared, offset);
+        offset += mlKemShared.length;
+        combined.set(mlKemCiphertext, offset);
+        offset += mlKemCiphertext.length;
+        combined.set(x25519Shared, offset);
+        offset += x25519Shared.length;
+        combined.set(x25519EphemeralPub, offset);
+        offset += x25519EphemeralPub.length;
+        combined.set(x25519RecipientPub, offset);
+        offset += x25519RecipientPub.length;
+        combined.set(mlKemRecipientPub, offset);
+        // HKDF-Extract with domain separation
+        const domain = new TextEncoder().encode('XWingKEM');
+        const baseKey = await crypto.subtle.importKey('raw', toArrayBuffer(combined), 'HKDF', false, ['deriveBits']);
+        const derived = await crypto.subtle.deriveBits({
+            name: 'HKDF',
+            hash: 'SHA-256',
+            salt: domain, // Domain separation (not zero salt)
+            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 = await (0, mlkem_1.createMlKem768)();
+        const [cipherText, sharedSecret] = mlkem.encap(recipientMlKemPub);
+        kemCipherText = cipherText;
+        kemSharedSecret = sharedSecret;
+    }
+    catch {
+        return (0, shared_1.err)('KEM_ENCAPSULATE_FAILED');
+    }
+    // Step 3: Export recipient's X25519 public key to raw bytes
+    let recipientX25519RawPub;
+    try {
+        const exported = await crypto.subtle.exportKey('raw', recipientX25519Pub);
+        recipientX25519RawPub = new Uint8Array(exported);
+    }
+    catch {
+        return (0, shared_1.err)('EXPORT_KEY_FAILED');
+    }
+    // Step 4: Combine via IETF X-Wing combiner
+    const combined = await combineSharedSecrets(kemSharedSecret, // ML-KEM shared secret
+    kemCipherText, // ML-KEM ciphertext
+    x25519Shared, // X25519 shared secret
+    ephemeral.value.rawPublicKey, // X25519 ephemeral public key
+    recipientX25519RawPub, // X25519 recipient public key
+    recipientMlKemPub);
+    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. IETF X-Wing combiner → same AES-256-GCM key
+ *
+ * Session 159 - CRYPTO-1: Updated to use IETF X-Wing combiner with public keys.
+ *
+ * @param x25519PrivateKey - Receiver's static X25519 private key.
+ * @param x25519PublicKeyRaw - Receiver's static X25519 public key (32B raw bytes).
+ * @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).
+ * @param mlKemPublicKey - Receiver's ML-KEM-768 public key (1184B).
+ * @returns AES-256-GCM shared key or error.
+ */
+async function receiverHybridKeyAgreement(x25519PrivateKey, x25519PublicKeyRaw, ephPubRaw, kemCiphertext, mlKemSecretKey, mlKemPublicKey) {
+    // 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 = await (0, mlkem_1.createMlKem768)();
+        mlKemShared = mlkem.decap(kemCiphertext, mlKemSecretKey);
+    }
+    catch {
+        return (0, shared_1.err)('KEM_DECAPSULATE_FAILED');
+    }
+    // Step 3: Combine via IETF X-Wing combiner
+    return combineSharedSecrets(mlKemShared, // ML-KEM shared secret
+    kemCiphertext, // ML-KEM ciphertext
+    x25519Shared, // X25519 shared secret
+    ephPubRaw, // X25519 ephemeral public key (from sender)
+    x25519PublicKeyRaw, // X25519 recipient public key (own)
+    mlKemPublicKey);
+}