@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/agent.js

@@ -1 +1,1800 @@
-import{ok,err}from"./_deps/shared/index.js";import{fromBase64,toBase64,generateUUID,formatShareHeader,parseShareHeader}from"./crypto-utils.js";import{loadCryptoPackage,getCrypto}from"./vault-store-loader.js";import{QuotaExceededError,VaultStoreError}from"./errors.js";import{generateIdentity,verify,importPublicKey,identityFromSeed,exportPKCS8,exportX25519PKCS8,extractRawEd25519,extractRawX25519}from"./identity.js";import{createEnvelope,createEnvelopeV2,createEnvelopeV3,createEnvelopeV4,decryptPayload,validateEnvelope,generateSharedKey}from"./envelope.js";import{generateXchangeKey,xchangeEncrypt,xchangeDecrypt}from"./_deps/xchange/index.js";import{verifyMlDsa65}from"./identity.js";import{senderKeyAgreement,receiverKeyAgreement,senderHybridKeyAgreement,receiverHybridKeyAgreement,importX25519PublicKey}from"./key-agreement.js";import{splitForChannel,reconstructFromChannel,DEFAULT_SPLIT_CONFIG}from"./split-channel.js";import{MemoryNonceStore}from"./nonce-store.js";import{HttpsTransportAdapter}from"./transport.js";import{MemoryTrustRegistry,HttpTrustRegistry}from"./trust-registry.js";import{ProgressReporter}from"./_deps/ux-helpers/index.js";import{DefaultSecurityPolicy,describeSecurityMode}from"./security-policy.js";import{DEFAULT_BACKUP_CONFIG}from"./backup-config.js";const DEFAULT_RELAY_URL=process.env.XBIND_RELAY_URL||"https://private.me/relay",DEFAULT_REGISTRY_URL=process.env.XBIND_REGISTRY_URL||"https://private.me/registry";export function parseAgentError(e){const t=e.split(":");return 1===t.length?{code:t[0]??e}:{code:t[0]??e,subCode:t.slice(1).join(":")}}const TIMESTAMP_WINDOW_MS=3e4;function toArrayBuffer(e){const t=new ArrayBuffer(e.byteLength);return new Uint8Array(t).set(e),t}function compareBytes(e,t){const r=Math.min(e.length,t.length);for(let i=0;i<r;i++){const r=e[i]??0,a=t[i]??0;if(r!==a)return r-a}return e.length-t.length}function concatBytes(e,t){const r=new Uint8Array(e.length+t.length);return r.set(e),r.set(t,e.length),r}export class Agent{identity;name;registry;transports;nonceStore;timestampWindowMs;securityPolicy;backupConfig;shareAccumulator=new Map;lastDetail="";lastSecurityDecision;cleanupTimer;cryptoModule=null;get lastErrorDetail(){return this.lastDetail}get lastSecurity(){return this.lastSecurityDecision}constructor(e,t,r,i,a,s,n,o){this.identity=e,this.name=t,this.registry=r,this.transports=i,this.nonceStore=a,this.timestampWindowMs=s,this.securityPolicy=n??new DefaultSecurityPolicy,this.backupConfig=o??DEFAULT_BACKUP_CONFIG}get did(){return this.identity.did}getTransports(){return this.transports}async ensureCrypto(){if(this.cryptoModule)return this.cryptoModule;const e=getCrypto();if(e)return this.cryptoModule=e,e;const t=await loadCryptoPackage(this.identity);if(!t.ok){if("VAULT_QUOTA_EXCEEDED"===t.error){const e="https://private.me/subscribe?product=xbind&tier=pro";throw new QuotaExceededError(`Monthly usage quota exceeded (Free tier: 100K operations/month). Upgrade to Pro tier for unlimited access at $5 per 100K operations. Visit: ${e}`,e)}throw new VaultStoreError(t.error,`Failed to load crypto package: ${t.error}`)}return this.cryptoModule=t.value,t.value}static isSupported(){try{return void 0!==globalThis.crypto&&void 0!==globalThis.crypto.subtle&&"function"==typeof globalThis.crypto.subtle.generateKey&&"function"==typeof globalThis.crypto.subtle.sign&&"function"==typeof globalThis.crypto.subtle.verify&&"function"==typeof globalThis.crypto.subtle.encrypt&&"function"==typeof globalThis.crypto.getRandomValues}catch{return!1}}static async fromIdentity(e,t){const r=t.nonceStore??new MemoryNonceStore,i=t.timestampWindowMs??3e4,a=Array.isArray(t.transport)?t.transport:[t.transport],s=new Agent(e,t.name??e.did,t.registry,a,r,i,t.securityPolicy,t.backupConfig);return ok(s)}static fromParts(e,t,r,i){const a=Array.isArray(r)?r:[r];return new Agent(e,i?.name??e.did,t,a,i?.nonceStore??new MemoryNonceStore,i?.timestampWindowMs??3e4,i?.securityPolicy,i?.backupConfig)}static async fromSeed(e,t){const r=await identityFromSeed(e,{postQuantumSig:t.postQuantumSig});if(!r.ok)return err("IDENTITY_FAILED:KEYGEN");const i=await t.registry.register(r.value.did,r.value.rawPublicKey,t.name??r.value.did,t.scopes,r.value.rawX25519PublicKey,r.value.mlKemPublicKey,r.value.mlDsaPublicKey,t.xchange??!1);if(!i.ok&&"ALREADY_REGISTERED"!==i.error){const e="NETWORK_ERROR"===i.error?"REGISTRATION_FAILED:NETWORK_ERROR":"REGISTRATION_FAILED";return err(e)}const a=t.nonceStore??new MemoryNonceStore,s=t.timestampWindowMs??3e4,n=Array.isArray(t.transport)?t.transport:[t.transport];return ok(new Agent(r.value,t.name??r.value.did,t.registry,n,a,s,t.securityPolicy,t.backupConfig))}static async lazy(e){const{createLazyAgent:t}=await import("./lazy-init.js");return t(e)}isReady(){return void 0!==this.identity&&void 0!==this.registry&&this.transports.length>0}static async create(e){const t=await generateIdentity({postQuantumSig:e.postQuantumSig});if(!t.ok)return err("IDENTITY_FAILED:KEYGEN");const r=await e.registry.register(t.value.did,t.value.rawPublicKey,e.name,e.scopes,t.value.rawX25519PublicKey,t.value.mlKemPublicKey,t.value.mlDsaPublicKey,e.xchange??!1);if(!r.ok){const e="ALREADY_REGISTERED"===r.error?"REGISTRATION_FAILED:ALREADY_REGISTERED":"NETWORK_ERROR"===r.error?"REGISTRATION_FAILED:NETWORK_ERROR":"REGISTRATION_FAILED";return err(e)}const i=e.nonceStore??new MemoryNonceStore,a=e.timestampWindowMs??3e4,s=Array.isArray(e.transport)?e.transport:[e.transport],n=new Agent(t.value,e.name,e.registry,s,i,a,e.securityPolicy,e.backupConfig);try{await n.ensureCrypto()}catch(e){return err(e instanceof QuotaExceededError?"QUOTA_EXCEEDED":e instanceof VaultStoreError?"IDENTITY_FAILED:VAULT_STORE":"IDENTITY_FAILED")}return ok(n)}static async quickstart(e){const t=new MemoryTrustRegistry,r=new HttpsTransportAdapter({baseUrl:DEFAULT_RELAY_URL}),i=await generateIdentity({postQuantumSig:!1});if(!i.ok)throw new Error("Failed to generate ephemeral identity");const a=e?.name??`agent-${Date.now()}`,s=await t.register(i.value.did,i.value.rawPublicKey,a,void 0,i.value.rawX25519PublicKey,i.value.mlKemPublicKey,i.value.mlDsaPublicKey,!1);if(!s.ok)throw new Error(`Failed to register ephemeral identity: ${s.error}`);const n=new Agent(i.value,a,t,[r],new MemoryNonceStore,3e4,void 0,void 0);return n.cleanupTimer=setTimeout(async()=>{await t.revoke(i.value.did)},36e5),n}static async from(e={}){const t=e.identity??"persistent",r=e.identityTTL??36e5,i="ephemeral"===t,a="string"==typeof e.registry?new HttpTrustRegistry({baseUrl:e.registry}):e.registry??(i?new MemoryTrustRegistry:new HttpTrustRegistry({baseUrl:DEFAULT_REGISTRY_URL})),s=e.transport?Array.isArray(e.transport)?e.transport:[e.transport]:[new HttpsTransportAdapter({baseUrl:DEFAULT_RELAY_URL})],n=await generateIdentity({postQuantumSig:e.postQuantumSig??!1});if(!n.ok)throw new Error("Failed to generate identity");const o=i?`ephemeral-agent-${Date.now()}`:`agent-${Date.now()}`,c=await a.register(n.value.did,n.value.rawPublicKey,o,void 0,n.value.rawX25519PublicKey,n.value.mlKemPublicKey,n.value.mlDsaPublicKey,!1);if(!c.ok)throw new Error(`Failed to register identity: ${c.error}`);const l=new Agent(n.value,o,a,s,new MemoryNonceStore,3e4,e.securityPolicy,e.backupConfig);return i&&(l.cleanupTimer=setTimeout(async()=>{await a.revoke(n.value.did)},r)),l}async send(e){const t=new ProgressReporter(e.onProgress);t.start("Resolving recipient identity...");const r=await this.registry.resolve(e.to);if(!r.ok)return err("REVOKED"===r.error?"RECIPIENT_REVOKED":"RECIPIENT_NOT_FOUND");t.update("Checking recipient authorization...",10);if(!await this.registry.hasReceiveScope(e.to,e.scope))return this.lastDetail=`recipient=${e.to}, scope=${e.scope}`,err("RECEIVER_SCOPE_DENIED");t.update("Preparing message...",15);const i=(new TextEncoder).encode(JSON.stringify(e.payload));t.update("Determining security level...",20);const a=this.securityPolicy.classify({action:e.action??"send",params:"object"==typeof e.payload&&null!==e.payload?e.payload:{},sender:this.did,recipient:e.to,scope:e.scope,securityOverride:e.security});this.lastSecurityDecision=a,t.update(`Security: ${describeSecurityMode(a.mode)} — ${a.reason}`,25);const s=void 0!==e.splitChannel?e.splitChannel:"split"===a.mode.type;if(s&&(e.xchange||"xchange"===a.mode.type)){t.update("Checking Xchange support...",20);if(await this.canUseXchange(e.to))return this.sendXchange(e,i,t)}t.update("Establishing key agreement...",30);const n=await this.trySenderECDH(e.to);return n?s?this.sendSplitChannel(e,i,n.sharedKey,n.ephemeralPublicKey,n.kemCiphertext,n.recipientHasMlDsa,t):n.kemCiphertext&&n.recipientHasMlDsa&&this.identity.mlDsaSecretKey?this.sendWithHybridV3(e,i,n.sharedKey,n.ephemeralPublicKey,n.kemCiphertext,t):n.kemCiphertext?this.sendWithHybrid(e,i,n.sharedKey,n.ephemeralPublicKey,n.kemCiphertext,t):this.sendWithECDH(e,i,n.sharedKey,n.ephemeralPublicKey,t):err("KEY_AGREEMENT_FAILED:RECIPIENT_HAS_NO_X25519_KEY")}async receive(e,t){this.lastDetail="";const r=new ProgressReporter(t?.onProgress);r.start("Verifying envelope signature...");const i=await this.verifyEnvelope(e);if(!i.ok)return i;const{senderRawKey:a,payloadBytes:s}=i.value;let n;if(4===e.v)return err("VERIFICATION_FAILED:UNSUPPORTED_VERSION");if(r.update("Deriving shared key...",30),2!==e.v&&3!==e.v||!("kemCiphertext"in e)){if(!e.ephemeralPub){if(t?.allowCleartext){let t;try{t=JSON.parse((new TextDecoder).decode(s))}catch{return err("DECRYPT_FAILED:PARSE")}return r.complete(),ok({sender:e.sender,payload:t,scope:e.scope,timestamp:e.timestamp})}return err("DECRYPT_FAILED:NO_EPHEMERAL_KEY")}{if("string"!=typeof e.ephemeralPub)return this.lastDetail="ephemeralPub not string",err("VERIFICATION_FAILED:INVALID_ENVELOPE");const t=fromBase64(e.ephemeralPub),i=await receiverKeyAgreement(this.identity.x25519PrivateKey,t);if(i.ok)n=i.value;else{if(this.identity.rotatedKeys&&this.identity.rotatedKeys.length>0)for(const e of this.identity.rotatedKeys){const i=await receiverKeyAgreement(e.x25519PrivateKey,t);if(i.ok){n=i.value,r.update("Decrypting with rotated keys...",45);break}}if(!n)return err("DECRYPT_FAILED:KEY_AGREEMENT")}}}else{if(!this.identity.mlKemSecretKey)return err("DECRYPT_FAILED:KEY_AGREEMENT");if("string"!=typeof e.ephemeralPub||"string"!=typeof e.kemCiphertext)return this.lastDetail="ephemeralPub or kemCiphertext not string",err("VERIFICATION_FAILED:INVALID_ENVELOPE");const t=fromBase64(e.ephemeralPub),i=fromBase64(e.kemCiphertext);if(!this.identity.mlKemPublicKey||!this.identity.mlKemSecretKey)return this.lastDetail="ML-KEM keys not available in identity",err("DECRYPT_FAILED:MISSING_MLKEM_KEYS");const a=await receiverHybridKeyAgreement(this.identity.x25519PrivateKey,this.identity.rawX25519PublicKey,t,i,this.identity.mlKemSecretKey,this.identity.mlKemPublicKey);if(a.ok)n=a.value;else{if(this.identity.rotatedKeys&&this.identity.rotatedKeys.length>0)for(const e of this.identity.rotatedKeys){if(!e.mlKemSecretKey)continue;const a=await receiverHybridKeyAgreement(e.x25519PrivateKey,this.identity.rawX25519PublicKey,t,i,e.mlKemSecretKey,this.identity.mlKemPublicKey);if(a.ok){n=a.value,r.update("Decrypting with rotated keys...",45);break}}if(!n)return err("DECRYPT_FAILED:KEY_AGREEMENT")}}if(r.update("Decrypting payload...",60),!n)return err("DECRYPT_FAILED:KEY_AGREEMENT");const o=await decryptPayload(e,n);if(!o.ok)return err("DECRYPT_FAILED:DECRYPTION");let c;r.update("Parsing message...",90);try{c=JSON.parse((new TextDecoder).decode(o.value))}catch{return err("DECRYPT_FAILED:PARSE")}return r.complete(),ok({sender:e.sender,payload:c,scope:e.scope,timestamp:e.timestamp,metadata:e.protocol&&e.documentationUrl?{protocol:e.protocol,documentationUrl:e.documentationUrl}:void 0})}async verifySignature(e){const t=await this.registry.resolve(e.sender);if(!t.ok)return err("VERIFICATION_FAILED:DID_NOT_IN_REGISTRY");const r=await importPublicKey(t.value);if(!r.ok)return err("VERIFICATION_FAILED:KEY_IMPORT_FAILED");const i=fromBase64(e.signature),a=JSON.stringify({v:e.v,alg:e.alg,sender:e.sender,recipient:e.recipient,timestamp:e.timestamp,nonce:e.nonce,scope:e.scope,payload:e.payload}),s=(new TextEncoder).encode(a),n=await verify(r.value,i,s);return n.ok?ok({sender:e.sender,valid:n.value}):err("VERIFICATION_FAILED:SIGNATURE_MISMATCH")}async exportSeeds(){const e=await exportPKCS8(this.identity.privateKey);if(!e.ok)return err("IDENTITY_FAILED");const t=await exportX25519PKCS8(this.identity.x25519PrivateKey);if(!t.ok)return err("IDENTITY_FAILED");const r=extractRawEd25519(e.value);if(!r.ok)return err("IDENTITY_FAILED");const i=extractRawX25519(t.value);return i.ok?ok({ed25519:r.value,x25519:i.value,mlKemSecretKey:this.identity.mlKemSecretKey,mlKemPublicKey:this.identity.mlKemPublicKey}):err("IDENTITY_FAILED")}async splitKey(e){const{splitKeyWithBackup:t}=await import("./backup-config.js"),r=await t(e,this.backupConfig);return r.ok?r:err("ENVELOPE_FAILED:SPLIT")}async reconstructKey(e){const{reconstructKeyFromBackup:t}=await import("./backup-config.js"),r=await t(e);return r.ok?r:err("DECRYPT_FAILED")}async receiveSigned(e){this.lastDetail="";const t=await this.verifyEnvelope(e);if(!t.ok)return t;let r;try{r=JSON.parse((new TextDecoder).decode(t.value.payloadBytes))}catch{return err("DECRYPT_FAILED:PARSE")}return ok({sender:e.sender,payload:r,scope:e.scope,timestamp:e.timestamp,metadata:e.protocol&&e.documentationUrl?{protocol:e.protocol,documentationUrl:e.documentationUrl}:void 0})}async discover(e){const{getToolRegistry:t}=await import("./agent-call.js"),r=t();if(!r)return[];if(!e)return r.listAll();return r.search(e)}middleware(){return async(e,t,r)=>{const i=validateEnvelope(e.body);if(!i.ok)return void t.status(400).json({error:i.error});const a=await this.receive(i.value);if(!a.ok){const e="TIMESTAMP_EXPIRED"===a.error||"REPLAY_DETECTED"===a.error?403:401;return void t.status(e).json({error:a.error})}e.agentMessage=a.value,r()}}cleanup(){this.cleanupTimer&&(clearTimeout(this.cleanupTimer),this.cleanupTimer=void 0)}dispose(){this.cleanup()}async trySenderECDH(e){const t=await this.registry.getEntry(e);if(!t.ok||!t.value.x25519PublicKey)return null;const r=!!t.value.mlDsaPublicKey,i=await importX25519PublicKey(t.value.x25519PublicKey);if(!i.ok)return null;if(t.value.mlKemPublicKey&&this.identity.mlKemSecretKey){const e=await senderHybridKeyAgreement(i.value,t.value.mlKemPublicKey);if(e.ok)return{sharedKey:e.value.sharedKey,ephemeralPublicKey:e.value.ephemeralPublicKey,kemCiphertext:e.value.kemCiphertext,recipientHasMlDsa:r}}const a=await senderKeyAgreement(i.value);return a.ok?{...a.value,recipientHasMlDsa:r}:null}async sendWithECDH(e,t,r,i,a){a?.update("Encrypting message with ECDH...",60);const s=await createEnvelope({senderDid:this.identity.did,recipientDid:e.to,scope:e.scope,plaintext:t,privateKey:this.identity.privateKey,sharedKey:r,ephemeralPublicKey:i});if(!s.ok)return err("ENVELOPE_FAILED:ENCRYPT");a?.update("Sending message...",90);const n=await this.transports[0].send(s.value,e.to);return n.ok&&a?.complete(),n}async sendWithHybrid(e,t,r,i,a,s){s?.update("Encrypting message with hybrid KEM...",60);const n=await createEnvelopeV2({senderDid:this.identity.did,recipientDid:e.to,scope:e.scope,plaintext:t,privateKey:this.identity.privateKey,sharedKey:r,ephemeralPublicKey:i,kemCiphertext:a});if(!n.ok)return err("ENVELOPE_FAILED:ENCRYPT");s?.update("Sending message...",90);const o=await this.transports[0].send(n.value,e.to);return o.ok&&s?.complete(),o}async sendWithHybridV3(e,t,r,i,a,s){if(!this.identity.mlDsaSecretKey)return err("ENVELOPE_FAILED:PQ_KEY_MISSING");s?.update("Encrypting with post-quantum signatures...",60);const n=await createEnvelopeV3({senderDid:this.identity.did,recipientDid:e.to,scope:e.scope,plaintext:t,privateKey:this.identity.privateKey,sharedKey:r,ephemeralPublicKey:i,kemCiphertext:a,mlDsaSecretKey:this.identity.mlDsaSecretKey});if(!n.ok)return this.lastDetail=`v3 envelope error: ${n.error}`,err("ENVELOPE_FAILED:ENCRYPT");s?.update("Sending message...",90);const o=await this.transports[0].send(n.value,e.to);return o.ok&&s?.complete(),o}async sendDirect(e,t,r,i){i?.update("Encrypting message...",60);const a=await createEnvelope({senderDid:this.identity.did,recipientDid:e.to,scope:e.scope,plaintext:t,privateKey:this.identity.privateKey,sharedKey:r});if(!a.ok)return err("ENVELOPE_FAILED:ENCRYPT");i?.update("Sending message...",90);const s=await this.transports[0].send(a.value,e.to);return s.ok&&i?.complete(),s}async canUseXchange(e){const t=await this.registry.getEntry(e);return!!t.ok&&!0===t.value.xchange}async sendXchange(e,t,r){const i=e.splitChannelConfig??DEFAULT_SPLIT_CONFIG;this.transports.length<i.totalShares&&console.warn(`Split-channel: ${i.totalShares} shares but only ${this.transports.length} transport(s). For channel separation, provide at least ${i.totalShares} transports.`),r?.update("Generating Xchange key...",40);const a=await generateXchangeKey();if(!a.ok)return err("KEY_AGREEMENT_FAILED");r?.update("Encrypting message...",50);const s=await xchangeEncrypt(t,a.value);if(!s.ok)return err("ENVELOPE_FAILED:ENCRYPT");const n=await this.ensureCrypto(),o=i.totalShares,c=i.threshold,l=n.nextOddPrime(o)-1,d=n.pkcs7Pad(s.value,l),{key:u,signature:p}=await n.generateHMAC(d);let y;r?.update("Splitting message into shares...",60);try{y=n.splitXorIDA(d,o,c)}catch{return err("ENVELOPE_FAILED:SPLIT")}const h=toBase64(u),E=toBase64(p),m=generateUUID(),g=[];r?.update("Sending shares...",70);for(let t=0;t<y.length;t++){const i=y[t],a=formatShareHeader(toBase64(i)),s=(new TextEncoder).encode(a),n=await createEnvelopeV4({senderDid:this.identity.did,recipientDid:e.to,scope:e.scope,shareData:s,privateKey:this.identity.privateKey,shareIndex:t,shareTotal:o,shareThreshold:c,shareGroupId:m,shareHmacKey:h,shareHmacSig:E});if(!n.ok){g.push(err("ENVELOPE_FAILED:ENCRYPT"));continue}const l=this.transports[t%this.transports.length],d=await l.send(n.value,e.to);g.push(d);const u=70+Math.floor((t+1)/y.length*20);r?.update(`Sent share ${t+1}/${y.length}...`,u)}return g.filter(e=>e.ok).length<c?err("SEND_FAILED:BELOW_THRESHOLD"):(r?.complete(),ok(void 0))}async sendSplitChannel(e,t,r,i,a,s,n){const o=e.splitChannelConfig??DEFAULT_SPLIT_CONFIG;this.transports.length<o.totalShares&&console.warn(`Split-channel: ${o.totalShares} shares but only ${this.transports.length} transport(s). For channel separation, provide at least ${o.totalShares} transports.`),n?.update("Splitting message into shares...",50);const c=await splitForChannel(t,o);if(!c.ok)return err("ENVELOPE_FAILED:SPLIT");const l=c.value;n?.update("Encrypting and sending shares...",70);return(await this.sendShareEnvelopes(e,l,r,i,a,s,n)).filter(e=>e.ok).length<o.threshold?err("SEND_FAILED:BELOW_THRESHOLD"):(n?.complete(),ok(void 0))}async sendShareEnvelopes(e,t,r,i,a,s,n){const o=[];for(let c=0;c<t.length;c++){const l=t[c],d=(new TextEncoder).encode(l.data);let u;if(u=a&&i&&s&&this.identity.mlDsaSecretKey?await createEnvelopeV3({senderDid:this.identity.did,recipientDid:e.to,scope:e.scope,plaintext:d,privateKey:this.identity.privateKey,sharedKey:r,ephemeralPublicKey:i,kemCiphertext:a,mlDsaSecretKey:this.identity.mlDsaSecretKey,shareIndex:l.index,shareTotal:l.total,shareThreshold:l.threshold,shareGroupId:l.groupId,shareHmacKey:l.hmacKey,shareHmacSig:l.hmacSig}):a&&i?await createEnvelopeV2({senderDid:this.identity.did,recipientDid:e.to,scope:e.scope,plaintext:d,privateKey:this.identity.privateKey,sharedKey:r,ephemeralPublicKey:i,kemCiphertext:a,shareIndex:l.index,shareTotal:l.total,shareThreshold:l.threshold,shareGroupId:l.groupId,shareHmacKey:l.hmacKey,shareHmacSig:l.hmacSig}):await createEnvelope({senderDid:this.identity.did,recipientDid:e.to,scope:e.scope,plaintext:d,privateKey:this.identity.privateKey,sharedKey:r,ephemeralPublicKey:i,shareIndex:l.index,shareTotal:l.total,shareThreshold:l.threshold,shareGroupId:l.groupId,shareHmacKey:l.hmacKey,shareHmacSig:l.hmacSig}),!u.ok){o.push(err("ENVELOPE_FAILED:ENCRYPT"));continue}const p=this.transports[c%this.transports.length],y=await p.send(u.value,e.to);o.push(y);const h=70+Math.floor((c+1)/t.length*20);n?.update(`Sent share ${c+1}/${t.length}...`,h)}return o}async receiveSplitShare(e){if(void 0===e.shareGroupId)return err("VERIFICATION_FAILED");const t=await this.receiveRaw(e);if(!t.ok)return t;const{sender:r,decryptedText:i,scope:a,timestamp:s}=t.value,n={data:i,index:e.shareIndex??0,total:e.shareTotal??2,threshold:e.shareThreshold??2,groupId:e.shareGroupId,hmacKey:e.shareHmacKey??"",hmacSig:e.shareHmacSig??""};return this.accumulateShare(n,r,a,s)}async receiveXchangeShare(e){this.lastDetail="";const t=await this.verifyEnvelope(e);if(!t.ok)return t;const r={data:(new TextDecoder).decode(t.value.payloadBytes),index:e.shareIndex,total:e.shareTotal,threshold:e.shareThreshold,groupId:e.shareGroupId,hmacKey:e.shareHmacKey,hmacSig:e.shareHmacSig};return this.accumulateXchangeShare(r,e.sender,e.scope,e.timestamp)}async accumulateXchangeShare(e,t,r,i){const a=this.shareAccumulator.get(e.groupId)??[];if(a.some(t=>t.index===e.index)||(a.push(e),this.shareAccumulator.set(e.groupId,a)),a.length<e.threshold)return ok(null);this.shareAccumulator.delete(e.groupId);const s=a.slice(0,e.threshold),n=e.total,o=e.threshold;let c;try{c=s.map(e=>fromBase64(parseShareHeader(e.data)))}catch{return err("DECRYPT_FAILED")}const l=s.map(e=>e.index),d=await this.ensureCrypto();let u,p,y;try{u=d.reconstructXorIDA(c,l,n,o)}catch{return err("DECRYPT_FAILED")}try{p=fromBase64(s[0].hmacKey),y=fromBase64(s[0].hmacSig)}catch{return err("DECRYPT_FAILED")}if(!await d.verifyHMAC(p,u,y))return this.lastDetail="HMAC verification failed before decrypt",err("DECRYPT_FAILED");const h=d.nextOddPrime(n)-1,E=d.pkcs7Unpad(u,h);if(!E.ok)return err("DECRYPT_FAILED");const m=await xchangeDecrypt(E.value);if(!m.ok)return err("DECRYPT_FAILED:DECRYPTION");let g;try{g=JSON.parse((new TextDecoder).decode(m.value))}catch{return err("DECRYPT_FAILED:PARSE")}return ok({sender:t,payload:g,scope:r,timestamp:i})}async accumulateShare(e,t,r,i){const a=this.shareAccumulator.get(e.groupId)??[];if(a.some(t=>t.index===e.index)||(a.push(e),this.shareAccumulator.set(e.groupId,a)),a.length<e.threshold)return ok(null);this.shareAccumulator.delete(e.groupId);const s=await reconstructFromChannel(a);if(!s.ok)return err("DECRYPT_FAILED");let n;try{n=JSON.parse((new TextDecoder).decode(s.value))}catch{return err("DECRYPT_FAILED")}return ok({sender:t,payload:n,scope:r,timestamp:i})}async verifyEnvelope(e){if(!e||"object"!=typeof e)return this.lastDetail="envelope is null or not an object",err("VERIFICATION_FAILED:INVALID_ENVELOPE");if(1!==e.v&&2!==e.v&&3!==e.v&&4!==e.v||"Ed25519"!==e.alg)return this.lastDetail=`v=${String(e.v)}, alg=${String(e.alg)}`,err("VERIFICATION_FAILED:UNSUPPORTED_VERSION");if("number"!=typeof e.timestamp||!Number.isFinite(e.timestamp))return this.lastDetail=`timestamp=${String(e.timestamp)} (must be finite number)`,err("VERIFICATION_FAILED:INVALID_ENVELOPE");const t=Math.abs(Date.now()-e.timestamp);if(t>this.timestampWindowMs)return this.lastDetail=`age=${t}ms, max=${this.timestampWindowMs}ms`,err("TIMESTAMP_EXPIRED");const r=void 0!==e.shareGroupId?{shareGroupId:e.shareGroupId,shareIndex:e.shareIndex}:void 0;if(!await this.nonceStore.check(e.nonce,e.sender,r))return this.lastDetail=`nonce=${e.nonce}`,err("REPLAY_DETECTED");const i=await this.registry.resolve(e.sender);if(!i.ok)return this.lastDetail=`did=${e.sender}`,err("VERIFICATION_FAILED:DID_NOT_IN_REGISTRY");const a=await importPublicKey(i.value);if(!a.ok)return this.lastDetail=`did=${e.sender}`,err("VERIFICATION_FAILED:KEY_IMPORT_FAILED");if(!e.signature||"string"!=typeof e.signature)return this.lastDetail="signature field missing or invalid",err("VERIFICATION_FAILED:SIGNATURE_MISMATCH");const s=fromBase64(e.signature),n=JSON.stringify({v:e.v,alg:e.alg,sender:e.sender,recipient:e.recipient,timestamp:e.timestamp,nonce:e.nonce,scope:e.scope,payload:e.payload}),o=(new TextEncoder).encode(n),c=await verify(a.value,s,o);if(!c.ok||!c.value)return this.lastDetail="signature does not match canonical envelope (v1.1.3+ required)",err("VERIFICATION_FAILED:SIGNATURE_MISMATCH");if(3===e.v&&"pqSignature"in e){if("string"!=typeof e.pqSignature)return this.lastDetail="pqSignature field not a string",err("VERIFICATION_FAILED:INVALID_ENVELOPE");const t=await this.registry.getEntry(e.sender);if(!t.ok||!t.value.mlDsaPublicKey)return this.lastDetail=`did=${e.sender} missing ML-DSA public key`,err("VERIFICATION_FAILED:PQ_KEY_MISSING");const r=fromBase64(e.pqSignature),i=await verifyMlDsa65(t.value.mlDsaPublicKey,r,o);if(!i.ok||!i.value)return this.lastDetail="ML-DSA-65 signature does not match canonical envelope (v1.1.3+ required)",err("VERIFICATION_FAILED:PQ_SIGNATURE_MISMATCH")}if(!await this.registry.hasScope(e.sender,e.scope))return this.lastDetail=`scope=${e.scope}`,err("SCOPE_DENIED");if("string"!=typeof e.payload)return this.lastDetail="payload field not a string",err("VERIFICATION_FAILED:INVALID_ENVELOPE");const l=fromBase64(e.payload);return ok({senderRawKey:i.value,payloadBytes:l})}async receiveRaw(e){const t=await this.verifyEnvelope(e);if(!t.ok)return t;const{senderRawKey:r}=t.value;if(4===e.v)return err("VERIFICATION_FAILED:UNSUPPORTED_VERSION");let i;if(2!==e.v&&3!==e.v||!("kemCiphertext"in e)){if(!e.ephemeralPub)return err("DECRYPT_FAILED:NO_EPHEMERAL_KEY");{if("string"!=typeof e.ephemeralPub)return err("DECRYPT_FAILED:INVALID_ENVELOPE");const t=fromBase64(e.ephemeralPub),r=await receiverKeyAgreement(this.identity.x25519PrivateKey,t);if(r.ok)i=r.value;else{if(this.identity.rotatedKeys&&this.identity.rotatedKeys.length>0)for(const e of this.identity.rotatedKeys){const r=await receiverKeyAgreement(e.x25519PrivateKey,t);if(r.ok){i=r.value;break}}if(!i)return err("DECRYPT_FAILED:KEY_AGREEMENT")}}}else{if(!this.identity.mlKemSecretKey)return err("DECRYPT_FAILED:KEY_AGREEMENT");if("string"!=typeof e.ephemeralPub||"string"!=typeof e.kemCiphertext)return err("DECRYPT_FAILED:INVALID_ENVELOPE");const t=fromBase64(e.ephemeralPub),r=fromBase64(e.kemCiphertext);if(!this.identity.mlKemPublicKey||!this.identity.mlKemSecretKey)return this.lastDetail="ML-KEM keys not available in identity",err("DECRYPT_FAILED:MISSING_MLKEM_KEYS");const a=await receiverHybridKeyAgreement(this.identity.x25519PrivateKey,this.identity.rawX25519PublicKey,t,r,this.identity.mlKemSecretKey,this.identity.mlKemPublicKey);if(a.ok)i=a.value;else{if(this.identity.rotatedKeys&&this.identity.rotatedKeys.length>0)for(const e of this.identity.rotatedKeys){if(!e.mlKemSecretKey)continue;const a=await receiverHybridKeyAgreement(e.x25519PrivateKey,this.identity.rawX25519PublicKey,t,r,e.mlKemSecretKey,this.identity.mlKemPublicKey);if(a.ok){i=a.value;break}}if(!i)return err("DECRYPT_FAILED:KEY_AGREEMENT")}}if(!i)return err("DECRYPT_FAILED:KEY_AGREEMENT");const a=await decryptPayload(e,i);if(!a.ok)return err("DECRYPT_FAILED:DECRYPTION");const s=(new TextDecoder).decode(a.value);return ok({sender:e.sender,decryptedText:s,scope:e.scope,timestamp:e.timestamp})}async createTestEnvelope(e,t,r){const i=await this.registry.getEntry(e);if(!i.ok||!i.value.x25519PublicKey)return null;const a=await importX25519PublicKey(i.value.x25519PublicKey);if(!a.ok)return null;const s=await senderKeyAgreement(a.value);if(!s.ok)return null;const n=(new TextEncoder).encode(JSON.stringify(t)),o=await createEnvelope({senderDid:this.identity.did,recipientDid:e,scope:r,plaintext:n,privateKey:this.identity.privateKey,sharedKey:s.value.sharedKey,ephemeralPublicKey:s.value.ephemeralPublicKey});return o.ok?o.value:null}async invite(e){if(!this.transports||0===this.transports.length)return err("SEND_FAILED");const t=Buffer.from(this.identity.rawPublicKey).toString("base64"),r={from:this.identity.did,to:e.to,payload:{agentName:this.name,message:e.message,publicKey:t,endpoint:""}},i=this.transports[0];if(!i)return err("SEND_FAILED");return(await i.send(r,e.to)).ok?ok(void 0):err("SEND_FAILED")}}export{generateSharedKey};
+import { ok, err } from"./_deps/shared/index.js";
+import { fromBase64, toBase64, generateUUID, formatShareHeader, parseShareHeader, } from './crypto-utils.js';
+import { loadCryptoPackage, getCrypto, } from './vault-store-loader.js';
+import { QuotaExceededError, VaultStoreError } from './errors.js';
+import { generateIdentity, verify, importPublicKey, identityFromSeed, exportPKCS8, exportX25519PKCS8, extractRawEd25519, extractRawX25519, } from './identity.js';
+import { createEnvelope, createEnvelopeV2, createEnvelopeV3, createEnvelopeV4, decryptPayload, validateEnvelope, generateSharedKey, } from './envelope.js';
+import { generateXchangeKey, xchangeEncrypt, xchangeDecrypt } from"./_deps/xchange/index.js";
+import { verifyMlDsa65 } from './identity.js';
+import { senderKeyAgreement, receiverKeyAgreement, senderHybridKeyAgreement, receiverHybridKeyAgreement, importX25519PublicKey, } from './key-agreement.js';
+import { splitForChannel, reconstructFromChannel, DEFAULT_SPLIT_CONFIG, } from './split-channel.js';
+import { MemoryNonceStore } from './nonce-store.js';
+import { HttpsTransportAdapter } from './transport.js';
+import { MemoryTrustRegistry, HttpTrustRegistry } from './trust-registry.js';
+import { ProgressReporter } from"./_deps/ux-helpers/index.js";
+import { DefaultSecurityPolicy, describeSecurityMode } from './security-policy.js';
+import { DEFAULT_BACKUP_CONFIG } from './backup-config.js';
+/* ── Configuration ── */
+/**
+ * Default relay URL for message transport.
+ * Override via XBIND_RELAY_URL environment variable.
+ */
+const DEFAULT_RELAY_URL = process.env.XBIND_RELAY_URL || 'https://private.me/relay';
+/**
+ * Default registry URL for DID resolution.
+ * Override via XBIND_REGISTRY_URL environment variable.
+ */
+const DEFAULT_REGISTRY_URL = process.env.XBIND_REGISTRY_URL || 'https://private.me/registry';
+/**
+ * Parse an AgentError string into structured detail.
+ *
+ * Splits colon-separated error codes into base code and sub-code.
+ *
+ * @param error - An AgentError string (e.g. 'DECRYPT_FAILED:KEY_AGREEMENT').
+ * @returns Parsed error detail.
+ */
+export function parseAgentError(error) {
+    const parts = error.split(':');
+    if (parts.length === 1)
+        return { code: parts[0] ?? error };
+    return { code: parts[0] ?? error, subCode: parts.slice(1).join(':') };
+}
+const TIMESTAMP_WINDOW_MS = 30_000;
+/* ── Key Agreement ── */
+/** Copy Uint8Array to fresh ArrayBuffer. */
+function toArrayBuffer(data) {
+    const buf = new ArrayBuffer(data.byteLength);
+    new Uint8Array(buf).set(data);
+    return buf;
+}
+// SECURITY FIX (v1.1.6): deriveSharedKey() REMOVED
+//
+// Previous implementation derived AES-256-GCM keys from public-only inputs:
+//   AES key = SHA-256(sort(pubA, pubB))
+//
+// Both public keys appear in the envelope (sender/recipient DIDs). Any passive
+// observer can derive the same key and decrypt all messages. Zero forward secrecy.
+//
+// Fix: All senders/receivers MUST use X25519 ECDH for proper key agreement.
+// Recipients without x25519 keys fail with KEY_AGREEMENT_FAILED:RECIPIENT_HAS_NO_X25519_KEY.
+//
+// Removed: deriveSharedKey() function and export (agent.ts:2305)
+// Removed: Sender fallback at line 959
+// Removed: Receiver fallbacks at lines 1036, 2209
+function compareBytes(a, b) {
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const ai = a[i] ?? 0;
+        const bi = b[i] ?? 0;
+        if (ai !== bi)
+            return ai - bi;
+    }
+    return a.length - b.length;
+}
+function concatBytes(a, b) {
+    const result = new Uint8Array(a.length + b.length);
+    result.set(a);
+    result.set(b, a.length);
+    return result;
+}
+/* ── Agent Class ── */
+/**
+ * Top-level Xail Agent SDK API.
+ *
+ * Provides cryptographically secure agent-to-agent messaging with:
+ * - Ed25519 digital signatures
+ * - X25519 ECDH forward secrecy
+ * - ML-KEM-768 post-quantum encryption
+ * - ML-DSA-65 post-quantum signatures (opt-in)
+ * - XorIDA information-theoretic split-channel delivery
+ *
+ * @example Basic Agent Usage
+ * ```typescript
+ * import { Agent } from '@private.me/xbind';
+ *
+ * // Create an agent with auto-generated identity
+ * const alice = await Agent.create({
+ *   name: 'alice',
+ *   registry: 'https://private.me/registry'
+ * });
+ * if (!alice.ok) throw new Error(alice.error);
+ *
+ * const bob = await Agent.create({
+ *   name: 'bob',
+ *   registry: 'https://private.me/registry'
+ * });
+ * if (!bob.ok) throw new Error(bob.error);
+ *
+ * // Send encrypted message
+ * const result = await alice.value.send({
+ *   to: bob.value.identity.did,
+ *   payload: { message: 'Hello, Bob!' },
+ *   scope: ['read:profile']
+ * });
+ *
+ * // Receive and decrypt message
+ * if (result.ok && result.value.envelope) {
+ *   const message = await bob.value.receive(result.value.envelope);
+ *   if (message.ok) {
+ *     console.log('Received:', message.value.payload);
+ *   }
+ * }
+ * ```
+ *
+ * @example Using Existing Identity
+ * ```typescript
+ * import { Agent, identityFromSeed } from '@private.me/xbind';
+ *
+ * // Restore identity from seed
+ * const seed = process.env.XBIND_SEED;
+ * const identity = await identityFromSeed(seed);
+ * if (!identity.ok) throw new Error(identity.error);
+ *
+ * // Create agent from existing identity
+ * const agent = new Agent(identity.value, {
+ *   name: 'my-agent',
+ *   registry: 'https://private.me/registry'
+ * });
+ * ```
+ */
+export class Agent {
+    identity;
+    name;
+    registry;
+    transports;
+    nonceStore;
+    timestampWindowMs;
+    securityPolicy;
+    backupConfig;
+    /** Accumulates split-channel shares by groupId until threshold is met. */
+    shareAccumulator = new Map();
+    /** Diagnostic detail from the last failed verification step. */
+    lastDetail = '';
+    /** Last security decision made by the policy (for debugging/logging). */
+    lastSecurityDecision;
+    /** Timer for ephemeral agent auto-cleanup. */
+    cleanupTimer;
+    /** Crypto package (XorIDA algorithms) loaded from Vault Store. */
+    cryptoModule = null;
+    /**
+     * Human-readable diagnostic from the last failed receive/verify call.
+     *
+     * Populated during verification with context like age vs max window.
+     * Empty string if no error has occurred or after a successful call.
+     */
+    get lastErrorDetail() {
+        return this.lastDetail;
+    }
+    /**
+     * Last security decision made by the security policy.
+     *
+     * Shows which security mode was selected and why. Useful for debugging
+     * and understanding when/why Xorida split-channel was activated.
+     *
+     * Returns undefined if no send() has been called yet.
+     */
+    get lastSecurity() {
+        return this.lastSecurityDecision;
+    }
+    constructor(identity, name, registry, transports, nonceStore, timestampWindowMs, securityPolicy, backupConfig) {
+        this.identity = identity;
+        this.name = name;
+        this.registry = registry;
+        this.transports = transports;
+        this.nonceStore = nonceStore;
+        this.timestampWindowMs = timestampWindowMs;
+        this.securityPolicy = securityPolicy ?? new DefaultSecurityPolicy();
+        this.backupConfig = backupConfig ?? DEFAULT_BACKUP_CONFIG;
+    }
+    /** The agent's DID. */
+    get did() {
+        return this.identity.did;
+    }
+    /**
+     * Get the agent's transport adapters.
+     * @internal Used by MessageStream for envelope handling.
+     */
+    getTransports() {
+        return this.transports;
+    }
+    /**
+     * Ensure crypto package is loaded from Vault Store.
+     *
+     * Loads XorIDA algorithms with:
+     * - DID-based authentication
+     * - Usage quota verification (Free: 100K/month, Pro: unlimited)
+     * - 7-day memory cache
+     *
+     * @returns Crypto package or throws QuotaExceededError/VaultStoreError
+     * @throws {QuotaExceededError} If Free tier quota exceeded (>120K hard cap)
+     * @throws {VaultStoreError} If vault fetch/load fails
+     * @private
+     */
+    async ensureCrypto() {
+        // Check cache first
+        if (this.cryptoModule) {
+            return this.cryptoModule;
+        }
+        // Try global cache (shared across agents)
+        const cached = getCrypto();
+        if (cached) {
+            this.cryptoModule = cached;
+            return cached;
+        }
+        // Load from Vault Store
+        const result = await loadCryptoPackage(this.identity);
+        if (!result.ok) {
+            // Handle quota exceeded with user-friendly error
+            if (result.error === 'VAULT_QUOTA_EXCEEDED') {
+                const upgradeUrl = 'https://private.me/subscribe?product=xbind&tier=pro';
+                throw new QuotaExceededError(`Monthly usage quota exceeded (Free tier: 100K operations/month). Upgrade to Pro tier for unlimited access at $5 per 100K operations. Visit: ${upgradeUrl}`, upgradeUrl);
+            }
+            // Other vault errors
+            throw new VaultStoreError(result.error, `Failed to load crypto package: ${result.error}`);
+        }
+        // Cache locally
+        this.cryptoModule = result.value;
+        return result.value;
+    }
+    /**
+     * Check whether the runtime supports the SDK's crypto requirements.
+     *
+     * Verifies that `crypto.subtle` is available and supports Ed25519 +
+     * AES-256-GCM. Call this before lazy-loading the SDK in middleware
+     * to avoid failing on the first `Agent.create()` call.
+     *
+     * @returns `true` if the runtime has the required Web Crypto APIs.
+     */
+    static isSupported() {
+        try {
+            return (typeof globalThis.crypto !== 'undefined' &&
+                typeof globalThis.crypto.subtle !== 'undefined' &&
+                typeof globalThis.crypto.subtle.generateKey === 'function' &&
+                typeof globalThis.crypto.subtle.sign === 'function' &&
+                typeof globalThis.crypto.subtle.verify === 'function' &&
+                typeof globalThis.crypto.subtle.encrypt === 'function' &&
+                typeof globalThis.crypto.getRandomValues === 'function');
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Create an Agent from a persisted identity (skips keygen + registration).
+     *
+     * Use this with importFromPKCS8 or importIdentity to restore a
+     * previously created agent across process restarts.
+     *
+     * @param identity - A previously exported AgentIdentity.
+     * @param opts - Agent options (registry, transport, etc.).
+     * @returns Agent instance or error.
+     */
+    static async fromIdentity(identity, opts) {
+        const nonceStore = opts.nonceStore ?? new MemoryNonceStore();
+        const timestampWindowMs = opts.timestampWindowMs ?? TIMESTAMP_WINDOW_MS;
+        const transports = Array.isArray(opts.transport) ? opts.transport : [opts.transport];
+        const agent = new Agent(identity, opts.name ?? identity.did, opts.registry, transports, nonceStore, timestampWindowMs, opts.securityPolicy, opts.backupConfig);
+        return ok(agent);
+    }
+    /**
+     * Build an Agent from pre-constructed parts (synchronous).
+     *
+     * Unlike `create()` this does NOT generate keys or register with the
+     * registry — the caller is responsible for both.  Useful when identity
+     * is provisioned in a factory step, registration is handled by an
+     * external system, or transport is wired up at runtime.
+     *
+     * @param identity  - A previously generated or imported AgentIdentity.
+     * @param registry  - Trust registry the agent will query for peers.
+     * @param transport - Transport adapter for envelope delivery.
+     * @param opts      - Optional overrides (name, nonceStore, timestampWindowMs).
+     * @returns A fully wired Agent instance.
+     */
+    static fromParts(identity, registry, transport, opts) {
+        const transports = Array.isArray(transport) ? transport : [transport];
+        return new Agent(identity, opts?.name ?? identity.did, registry, transports, opts?.nonceStore ?? new MemoryNonceStore(), opts?.timestampWindowMs ?? TIMESTAMP_WINDOW_MS, opts?.securityPolicy, opts?.backupConfig);
+    }
+    /**
+     * Create an Agent from a deterministic 32-byte seed.
+     *
+     * Uses HKDF-SHA256 to derive Ed25519 + X25519 keys from the seed.
+     * The same seed always produces the same DID and keys.
+     *
+     * **Just-in-Time Registration (JITR):** Automatically registers identity
+     * with the trust registry on first use. Follows industry standards (AWS IoT
+     * JITR, OAuth DCR, MCP 2025 spec) for zero-config onboarding. Idempotent:
+     * safe to call multiple times (ignores ALREADY_REGISTERED errors).
+     *
+     * Ideal for IoT, servers, AI agents: zero-config deployment with automatic
+     * registration on first connection.
+     *
+     * @param seed - Exactly 32 bytes of high-entropy key material.
+     * @param opts - Agent options (registry, transport, scopes, etc.).
+     * @returns Agent instance or error.
+     */
+    static async fromSeed(seed, opts) {
+        const idResult = await identityFromSeed(seed, { postQuantumSig: opts.postQuantumSig });
+        if (!idResult.ok)
+            return err('IDENTITY_FAILED:KEYGEN');
+        // JITR: Auto-register with trust registry (zero-config onboarding)
+        // Includes all keys: Ed25519 (signing), X25519 (encryption), ML-KEM, ML-DSA
+        const regResult = await opts.registry.register(idResult.value.did, idResult.value.rawPublicKey, opts.name ?? idResult.value.did, opts.scopes, idResult.value.rawX25519PublicKey, idResult.value.mlKemPublicKey, idResult.value.mlDsaPublicKey, opts.xchange ?? false);
+        // Idempotent: Ignore ALREADY_REGISTERED (agent may have registered before)
+        // Fail on other errors (network issues, invalid data, etc.)
+        if (!regResult.ok && regResult.error !== 'ALREADY_REGISTERED') {
+            const sub = regResult.error === 'NETWORK_ERROR'
+                ? 'REGISTRATION_FAILED:NETWORK_ERROR'
+                : 'REGISTRATION_FAILED';
+            return err(sub);
+        }
+        const nonceStore = opts.nonceStore ?? new MemoryNonceStore();
+        const timestampWindowMs = opts.timestampWindowMs ?? TIMESTAMP_WINDOW_MS;
+        const transports = Array.isArray(opts.transport) ? opts.transport : [opts.transport];
+        return ok(new Agent(idResult.value, opts.name ?? idResult.value.did, opts.registry, transports, nonceStore, timestampWindowMs, opts.securityPolicy, opts.backupConfig));
+    }
+    /**
+     * Create a lazy agent that initializes on first use (zero-click onboarding).
+     *
+     * Defers invite acceptance and identity generation until first send/receive.
+     * Reads invite code from XBIND_INVITE_CODE environment variable.
+     * Auto-accepts invite and configures registry/transport automatically.
+     *
+     * @param config - Lazy agent configuration (name required).
+     * @returns Lazy agent wrapper (synchronous).
+     *
+     * @example
+     * ```ts
+     * // Environment: XBIND_INVITE_CODE=XBD-abc123, XBIND_AUTO_ACCEPT=true
+     *
+     * // Synchronous construction (no await):
+     * const agent = Agent.lazy({ name: 'my-service' });
+     *
+     * // Auto-accept happens on first send/receive:
+     * await agent.send({
+     *   to: 'did:key:z6Mk...',
+     *   payload: { action: 'test' },
+     *   scope: 'test',
+     * });
+     * ```
+     */
+    static async lazy(config) {
+        // Dynamic import avoids circular dependency
+        const { createLazyAgent } = await import('./lazy-init.js');
+        return createLazyAgent(config);
+    }
+    /**
+     * Check whether this agent is fully initialized and ready to send/receive.
+     *
+     * Returns `true` if identity, registry, and transport are all present.
+     * Construction always produces a ready agent (invalid inputs cause the
+     * factory to return an error instead), so this is primarily useful in
+     * middleware that lazily initializes agents and needs a guard.
+     *
+     * @returns `true` if the agent can send and receive messages.
+     */
+    isReady() {
+        return (this.identity !== undefined &&
+            this.registry !== undefined &&
+            this.transports.length > 0);
+    }
+    /** Create a new agent, generate identity, register with trust registry. */
+    static async create(opts) {
+        const idResult = await generateIdentity({ postQuantumSig: opts.postQuantumSig });
+        if (!idResult.ok)
+            return err('IDENTITY_FAILED:KEYGEN');
+        const regResult = await opts.registry.register(idResult.value.did, idResult.value.rawPublicKey, opts.name, opts.scopes, idResult.value.rawX25519PublicKey, idResult.value.mlKemPublicKey, idResult.value.mlDsaPublicKey, opts.xchange ?? false);
+        if (!regResult.ok) {
+            const sub = regResult.error === 'ALREADY_REGISTERED'
+                ? 'REGISTRATION_FAILED:ALREADY_REGISTERED'
+                : regResult.error === 'NETWORK_ERROR'
+                    ? 'REGISTRATION_FAILED:NETWORK_ERROR'
+                    : 'REGISTRATION_FAILED';
+            return err(sub);
+        }
+        const nonceStore = opts.nonceStore ?? new MemoryNonceStore();
+        const timestampWindowMs = opts.timestampWindowMs ?? TIMESTAMP_WINDOW_MS;
+        const transports = Array.isArray(opts.transport) ? opts.transport : [opts.transport];
+        const agent = new Agent(idResult.value, opts.name, opts.registry, transports, nonceStore, timestampWindowMs, opts.securityPolicy, opts.backupConfig);
+        // Preload crypto package from Vault Store (payment-gated)
+        // This validates quota and caches crypto for 7 days
+        try {
+            await agent.ensureCrypto();
+        }
+        catch (error) {
+            // Convert vault errors to Result type
+            if (error instanceof QuotaExceededError) {
+                return err('QUOTA_EXCEEDED');
+            }
+            if (error instanceof VaultStoreError) {
+                return err('IDENTITY_FAILED:VAULT_STORE');
+            }
+            // Unknown error
+            return err('IDENTITY_FAILED');
+        }
+        return ok(agent);
+    }
+    /**
+     * Quickstart: create an agent with zero configuration.
+     *
+     * Creates an ephemeral agent with auto-cleanup after 1 hour. No policy
+     * restrictions by default (allow all operations). Ideal for getting
+     * started, prototyping, and simple use cases.
+     *
+     * Uses in-memory registry and default transport. Identity auto-expires
+     * and is deregistered after TTL.
+     *
+     * @param opts - Optional configuration (name only)
+     * @returns Agent instance (throws on error for simpler API)
+     *
+     * @example
+     * ```ts
+     * // Zero config (ephemeral identity, 1-hour TTL):
+     * const agent = await Agent.quickstart();
+     *
+     * // With custom name:
+     * const agent = await Agent.quickstart({ name: 'my-service' });
+     *
+     * // Agent is ready to use immediately:
+     * await agent.send({
+     *   to: 'did:key:z6Mk...',
+     *   payload: { action: 'test' },
+     *   scope: 'test',
+     * });
+     * ```
+     */
+    static async quickstart(opts) {
+        // Use in-memory registry for ephemeral agents
+        const registry = new MemoryTrustRegistry();
+        // Use default transport
+        const transport = new HttpsTransportAdapter({
+            baseUrl: DEFAULT_RELAY_URL,
+        });
+        // Generate ephemeral identity (1-hour TTL)
+        const idResult = await generateIdentity({ postQuantumSig: false });
+        if (!idResult.ok) {
+            throw new Error('Failed to generate ephemeral identity');
+        }
+        // Auto-generate name if not provided
+        const name = opts?.name ?? `agent-${Date.now()}`;
+        // Register ephemeral identity
+        const regResult = await registry.register(idResult.value.did, idResult.value.rawPublicKey, name, undefined, // scopes - no restrictions (allow all)
+        idResult.value.rawX25519PublicKey, idResult.value.mlKemPublicKey, idResult.value.mlDsaPublicKey, false);
+        if (!regResult.ok) {
+            throw new Error(`Failed to register ephemeral identity: ${regResult.error}`);
+        }
+        // Create agent instance
+        const agent = new Agent(idResult.value, name, registry, [transport], new MemoryNonceStore(), TIMESTAMP_WINDOW_MS, undefined, // No policy restrictions (allow all)
+        undefined);
+        // Auto-cleanup after 1 hour (ephemeral identity)
+        const TTL_MS = 3600000; // 1 hour
+        agent.cleanupTimer = setTimeout(async () => {
+            await registry.revoke(idResult.value.did);
+            // Ephemeral agent auto-revoked after TTL (no logging to avoid production noise)
+        }, TTL_MS);
+        return agent;
+    }
+    /**
+     * Create agent from simplified options (async factory).
+     *
+     * This is the async-safe way to construct agents with AgentOptions.
+     *
+     * @param options - Agent configuration
+     * @returns Agent instance
+     *
+     * @example
+     * ```typescript
+     * import { Agent } from '@private.me/xbind';
+     *
+     * // Ephemeral agent (auto-cleanup after 1 hour)
+     * const agent = await Agent.from({
+     *   identity: 'ephemeral',
+     *   identityTTL: 3600, // seconds
+     * });
+     *
+     * // Use the agent
+     * await agent.send({ to, payload, scope: 'read' });
+     * ```
+     */
+    static async from(options = {}) {
+        const identity = options.identity ?? 'persistent';
+        const identityTTL = options.identityTTL ?? 3600000; // 1 hour default (ms)
+        const isEphemeral = identity === 'ephemeral';
+        // Resolve registry
+        const registry = typeof options.registry === 'string'
+            ? new HttpTrustRegistry({ baseUrl: options.registry })
+            : options.registry ?? (isEphemeral ? new MemoryTrustRegistry() : new HttpTrustRegistry({ baseUrl: DEFAULT_REGISTRY_URL }));
+        // Resolve transport
+        const transports = options.transport
+            ? Array.isArray(options.transport)
+                ? options.transport
+                : [options.transport]
+            : [new HttpsTransportAdapter({ baseUrl: DEFAULT_RELAY_URL })];
+        // Generate identity
+        const idResult = await generateIdentity({
+            postQuantumSig: options.postQuantumSig ?? false,
+        });
+        if (!idResult.ok) {
+            throw new Error('Failed to generate identity');
+        }
+        // Register identity (ephemeral agents use auto-generated names)
+        const name = isEphemeral
+            ? `ephemeral-agent-${Date.now()}`
+            : `agent-${Date.now()}`;
+        const regResult = await registry.register(idResult.value.did, idResult.value.rawPublicKey, name, undefined, // scopes
+        idResult.value.rawX25519PublicKey, idResult.value.mlKemPublicKey, idResult.value.mlDsaPublicKey, false);
+        if (!regResult.ok) {
+            throw new Error(`Failed to register identity: ${regResult.error}`);
+        }
+        // Create agent instance
+        const agent = new Agent(idResult.value, name, registry, transports, new MemoryNonceStore(), TIMESTAMP_WINDOW_MS, options.securityPolicy, options.backupConfig);
+        // Setup TTL cleanup for ephemeral identities
+        if (isEphemeral) {
+            agent.cleanupTimer = setTimeout(async () => {
+                // Auto-deregister after TTL expires
+                await registry.revoke(idResult.value.did);
+            }, identityTTL);
+        }
+        return agent;
+    }
+    /** Send a message to a recipient. */
+    async send(opts) {
+        const progress = new ProgressReporter(opts.onProgress);
+        progress.start('Resolving recipient identity...');
+        const recipientKey = await this.registry.resolve(opts.to);
+        if (!recipientKey.ok) {
+            return err(recipientKey.error === 'REVOKED'
+                ? 'RECIPIENT_REVOKED'
+                : 'RECIPIENT_NOT_FOUND');
+        }
+        // Bilateral authorization: check if recipient accepts this scope
+        progress.update('Checking recipient authorization...', 10);
+        const receiverAccepts = await this.registry.hasReceiveScope(opts.to, opts.scope);
+        if (!receiverAccepts) {
+            this.lastDetail = `recipient=${opts.to}, scope=${opts.scope}`;
+            return err('RECEIVER_SCOPE_DENIED');
+        }
+        progress.update('Preparing message...', 15);
+        const plaintext = new TextEncoder().encode(JSON.stringify(opts.payload));
+        // Security policy: classify action risk and determine security mode
+        progress.update('Determining security level...', 20);
+        const securityDecision = this.securityPolicy.classify({
+            action: opts.action ?? 'send',
+            params: typeof opts.payload === 'object' && opts.payload !== null
+                ? opts.payload
+                : {},
+            sender: this.did,
+            recipient: opts.to,
+            scope: opts.scope,
+            securityOverride: opts.security,
+        });
+        this.lastSecurityDecision = securityDecision;
+        // Log security decision for transparency
+        progress.update(`Security: ${describeSecurityMode(securityDecision.mode)} — ${securityDecision.reason}`, 25);
+        // Determine whether to use split-channel based on policy decision
+        // Backward compatibility: explicit splitChannel flag overrides policy
+        const shouldUseSplitChannel = opts.splitChannel !== undefined
+            ? opts.splitChannel
+            : securityDecision.mode.type === 'split';
+        // Xchange: opt-in via xchange: true on send or policy decision. Faster (single security layer) but
+        // trades per-share encryption and KEM for ~180x speed. Falls back to V3 if
+        // recipient doesn't support Xchange.
+        if (shouldUseSplitChannel && (opts.xchange || securityDecision.mode.type === 'xchange')) {
+            progress.update('Checking Xchange support...', 20);
+            const canXchange = await this.canUseXchange(opts.to);
+            if (canXchange) {
+                return this.sendXchange(opts, plaintext, progress);
+            }
+            // Fall back to V3 split-channel if recipient doesn't support Xchange
+        }
+        progress.update('Establishing key agreement...', 30);
+        const ecdhResult = await this.trySenderECDH(opts.to);
+        if (ecdhResult) {
+            if (shouldUseSplitChannel) {
+                return this.sendSplitChannel(opts, plaintext, ecdhResult.sharedKey, ecdhResult.ephemeralPublicKey, ecdhResult.kemCiphertext, ecdhResult.recipientHasMlDsa, progress);
+            }
+            // V3: both sides have ML-DSA + hybrid KEM
+            if (ecdhResult.kemCiphertext && ecdhResult.recipientHasMlDsa && this.identity.mlDsaSecretKey) {
+                return this.sendWithHybridV3(opts, plaintext, ecdhResult.sharedKey, ecdhResult.ephemeralPublicKey, ecdhResult.kemCiphertext, progress);
+            }
+            if (ecdhResult.kemCiphertext) {
+                return this.sendWithHybrid(opts, plaintext, ecdhResult.sharedKey, ecdhResult.ephemeralPublicKey, ecdhResult.kemCiphertext, progress);
+            }
+            return this.sendWithECDH(opts, plaintext, ecdhResult.sharedKey, ecdhResult.ephemeralPublicKey, progress);
+        }
+        // SECURITY FIX (v1.1.6): Removed insecure fallback to deriveSharedKey()
+        // Recipient must have x25519 public key registered for secure ECDH key agreement
+        return err('KEY_AGREEMENT_FAILED:RECIPIENT_HAS_NO_X25519_KEY');
+    }
+    /**
+     * Verify and decrypt an incoming encrypted envelope (v1 or v2).
+     *
+     * ROT-1: Supports key rotation with fallback to old keys.
+     * If decryption fails with current keys, tries old rotated keys.
+     *
+     * @param envelope - Incoming transport envelope.
+     * @param opts - Optional receive options (e.g. allowCleartext).
+     */
+    async receive(envelope, opts) {
+        this.lastDetail = '';
+        const progress = new ProgressReporter(opts?.onProgress);
+        progress.start('Verifying envelope signature...');
+        const verified = await this.verifyEnvelope(envelope);
+        if (!verified.ok)
+            return verified;
+        const { senderRawKey, payloadBytes } = verified.value;
+        let sharedKey;
+        // V4 Xchange: use receiveXchangeShare() instead
+        if (envelope.v === 4) {
+            return err('VERIFICATION_FAILED:UNSUPPORTED_VERSION');
+        }
+        progress.update('Deriving shared key...', 30);
+        // V2/V3 hybrid path: use X25519 + ML-KEM-768
+        if ((envelope.v === 2 || envelope.v === 3) && 'kemCiphertext' in envelope) {
+            if (!this.identity.mlKemSecretKey) {
+                return err('DECRYPT_FAILED:KEY_AGREEMENT');
+            }
+            // Type guards to prevent crashes on malformed envelopes
+            if (typeof envelope.ephemeralPub !== 'string' || typeof envelope.kemCiphertext !== 'string') {
+                this.lastDetail = 'ephemeralPub or kemCiphertext not string';
+                return err('VERIFICATION_FAILED:INVALID_ENVELOPE');
+            }
+            const ephPubBytes = fromBase64(envelope.ephemeralPub);
+            const kemCtBytes = fromBase64(envelope.kemCiphertext);
+            // Validate identity has required public keys for IETF X-Wing combiner
+            if (!this.identity.mlKemPublicKey || !this.identity.mlKemSecretKey) {
+                this.lastDetail = 'ML-KEM keys not available in identity';
+                return err('DECRYPT_FAILED:MISSING_MLKEM_KEYS');
+            }
+            const hybridKey = await receiverHybridKeyAgreement(this.identity.x25519PrivateKey, this.identity.rawX25519PublicKey, ephPubBytes, kemCtBytes, this.identity.mlKemSecretKey, this.identity.mlKemPublicKey);
+            if (!hybridKey.ok) {
+                // ROT-1: Try old rotated keys if current key agreement fails
+                if (this.identity.rotatedKeys && this.identity.rotatedKeys.length > 0) {
+                    for (const rotated of this.identity.rotatedKeys) {
+                        if (!rotated.mlKemSecretKey)
+                            continue; // Skip if ML-KEM key not available
+                        const oldHybridKey = await receiverHybridKeyAgreement(rotated.x25519PrivateKey, this.identity.rawX25519PublicKey, // Still use current public key (sender may not know about rotation yet)
+                        ephPubBytes, kemCtBytes, rotated.mlKemSecretKey, this.identity.mlKemPublicKey);
+                        if (oldHybridKey.ok) {
+                            sharedKey = oldHybridKey.value;
+                            progress.update('Decrypting with rotated keys...', 45);
+                            break;
+                        }
+                    }
+                }
+                if (!sharedKey)
+                    return err('DECRYPT_FAILED:KEY_AGREEMENT');
+            }
+            else {
+                sharedKey = hybridKey.value;
+            }
+        }
+        else if (envelope.ephemeralPub) {
+            // V1 with ECDH forward secrecy
+            if (typeof envelope.ephemeralPub !== 'string') {
+                this.lastDetail = 'ephemeralPub not string';
+                return err('VERIFICATION_FAILED:INVALID_ENVELOPE');
+            }
+            const ephPubBytes = fromBase64(envelope.ephemeralPub);
+            const ecdhKey = await receiverKeyAgreement(this.identity.x25519PrivateKey, ephPubBytes);
+            if (!ecdhKey.ok) {
+                // ROT-1: Try old rotated keys if current key agreement fails
+                if (this.identity.rotatedKeys && this.identity.rotatedKeys.length > 0) {
+                    for (const rotated of this.identity.rotatedKeys) {
+                        const oldEcdhKey = await receiverKeyAgreement(rotated.x25519PrivateKey, ephPubBytes);
+                        if (oldEcdhKey.ok) {
+                            sharedKey = oldEcdhKey.value;
+                            progress.update('Decrypting with rotated keys...', 45);
+                            break;
+                        }
+                    }
+                }
+                if (!sharedKey)
+                    return err('DECRYPT_FAILED:KEY_AGREEMENT');
+            }
+            else {
+                sharedKey = ecdhKey.value;
+            }
+        }
+        else {
+            // No ephemeralPub: check if this is a signed-only envelope (allowCleartext)
+            if (opts?.allowCleartext) {
+                // Signed-only envelope: return payload directly (already verified signature above)
+                let payload;
+                try {
+                    payload = JSON.parse(new TextDecoder().decode(payloadBytes));
+                }
+                catch {
+                    return err('DECRYPT_FAILED:PARSE');
+                }
+                progress.complete();
+                return ok({
+                    sender: envelope.sender,
+                    payload,
+                    scope: envelope.scope,
+                    timestamp: envelope.timestamp,
+                });
+            }
+            // SECURITY FIX (v1.1.6): Removed insecure V1 SHA-256 fallback
+            // Envelopes without ephemeralPub are rejected (sender must use X25519 ECDH)
+            return err('DECRYPT_FAILED:NO_EPHEMERAL_KEY');
+        }
+        progress.update('Decrypting payload...', 60);
+        // TypeScript narrowing: sharedKey is guaranteed to be defined here due to control flow
+        if (!sharedKey)
+            return err('DECRYPT_FAILED:KEY_AGREEMENT');
+        const decrypted = await decryptPayload(envelope, sharedKey);
+        if (!decrypted.ok) {
+            return err('DECRYPT_FAILED:DECRYPTION');
+        }
+        progress.update('Parsing message...', 90);
+        let payload;
+        try {
+            payload = JSON.parse(new TextDecoder().decode(decrypted.value));
+        }
+        catch {
+            return err('DECRYPT_FAILED:PARSE');
+        }
+        progress.complete();
+        // Mechanism 2: Protocol information available in metadata for applications to display
+        // Applications can show this to users if needed (envelope.protocol, envelope.documentationUrl)
+        return ok({
+            sender: envelope.sender,
+            payload,
+            scope: envelope.scope,
+            timestamp: envelope.timestamp,
+            metadata: envelope.protocol && envelope.documentationUrl
+                ? {
+                    protocol: envelope.protocol,
+                    documentationUrl: envelope.documentationUrl,
+                }
+                : undefined,
+        });
+    }
+    /**
+     * Verify only the signature on an envelope without consuming the nonce.
+     *
+     * Does NOT check timestamp, nonce, or scope. Use this for pre-screening
+     * or audit logging where you need to confirm the sender but don't want
+     * to consume replay-prevention state.
+     *
+     * @param envelope - The envelope to verify.
+     * @returns `{ sender, valid }` or error if the DID cannot be resolved.
+     */
+    async verifySignature(envelope) {
+        const senderKey = await this.registry.resolve(envelope.sender);
+        if (!senderKey.ok)
+            return err('VERIFICATION_FAILED:DID_NOT_IN_REGISTRY');
+        const pubKey = await importPublicKey(senderKey.value);
+        if (!pubKey.ok)
+            return err('VERIFICATION_FAILED:KEY_IMPORT_FAILED');
+        const sigBytes = fromBase64(envelope.signature);
+        // SECURITY FIX (v1.1.3): Verify canonical representation (not just payload)
+        const canonicalData = JSON.stringify({
+            v: envelope.v,
+            alg: envelope.alg,
+            sender: envelope.sender,
+            recipient: envelope.recipient,
+            timestamp: envelope.timestamp,
+            nonce: envelope.nonce,
+            scope: envelope.scope,
+            payload: envelope.payload,
+        });
+        const canonicalBytes = new TextEncoder().encode(canonicalData);
+        const sigValid = await verify(pubKey.value, sigBytes, canonicalBytes);
+        if (!sigValid.ok)
+            return err('VERIFICATION_FAILED:SIGNATURE_MISMATCH');
+        return ok({ sender: envelope.sender, valid: sigValid.value });
+    }
+    /**
+     * Export the raw 32-byte private key seeds for both Ed25519 and X25519.
+     *
+     * These are the raw private key bytes extracted from PKCS8, NOT the
+     * original HKDF seed (that derivation is one-way). Use these for
+     * persistence or cross-device transfer.
+     *
+     * @returns Two 32-byte Uint8Arrays or error.
+     */
+    async exportSeeds() {
+        const edPkcs8 = await exportPKCS8(this.identity.privateKey);
+        if (!edPkcs8.ok)
+            return err('IDENTITY_FAILED');
+        const x25519Pkcs8 = await exportX25519PKCS8(this.identity.x25519PrivateKey);
+        if (!x25519Pkcs8.ok)
+            return err('IDENTITY_FAILED');
+        const edRaw = extractRawEd25519(edPkcs8.value);
+        if (!edRaw.ok)
+            return err('IDENTITY_FAILED');
+        const x25519Raw = extractRawX25519(x25519Pkcs8.value);
+        if (!x25519Raw.ok)
+            return err('IDENTITY_FAILED');
+        return ok({
+            ed25519: edRaw.value,
+            x25519: x25519Raw.value,
+            mlKemSecretKey: this.identity.mlKemSecretKey,
+            mlKemPublicKey: this.identity.mlKemPublicKey,
+        });
+    }
+    /**
+     * Split a cryptographic key into backup shares using XorIDA.
+     *
+     * Uses the agent's backup configuration (default: k=2, n=3).
+     * Any `threshold` shares can reconstruct the original key.
+     * Each share reveals zero information (information-theoretic security).
+     *
+     * @param key - The key to split (32 or 64 bytes typical).
+     * @returns Array of backup shares or error.
+     *
+     * @example
+     * ```typescript
+     * // Generate a key and split it
+     * const key = crypto.getRandomValues(new Uint8Array(32));
+     * const shares = await agent.splitKey(key);
+     *
+     * if (shares.ok) {
+     *   // Store shares in separate locations
+     *   shares.value.forEach((share, i) => {
+     *     storeShare(`backup-${i}.json`, JSON.stringify(share));
+     *   });
+     * }
+     * ```
+     */
+    async splitKey(key) {
+        // Dynamic import avoids circular dependency
+        const { splitKeyWithBackup } = await import('./backup-config.js');
+        const result = await splitKeyWithBackup(key, this.backupConfig);
+        if (!result.ok) {
+            return err('ENVELOPE_FAILED:SPLIT');
+        }
+        return result;
+    }
+    /**
+     * Reconstruct a cryptographic key from backup shares.
+     *
+     * Requires at least `threshold` shares. Verifies HMAC before returning
+     * the reconstructed key to prevent tampering.
+     *
+     * @param shares - Backup shares (must be >= threshold).
+     * @returns Reconstructed key or error.
+     *
+     * @example
+     * ```typescript
+     * // Load shares from storage
+     * const share0 = JSON.parse(loadShare('backup-0.json'));
+     * const share1 = JSON.parse(loadShare('backup-1.json'));
+     *
+     * // Reconstruct from any 2 shares (threshold=2)
+     * const key = await agent.reconstructKey([share0, share1]);
+     *
+     * if (key.ok) {
+     *   // Use reconstructed key
+     *   console.log('Key recovered:', key.value);
+     * }
+     * ```
+     */
+    async reconstructKey(shares) {
+        // Dynamic import avoids circular dependency
+        const { reconstructKeyFromBackup } = await import('./backup-config.js');
+        const result = await reconstructKeyFromBackup(shares);
+        if (!result.ok) {
+            return err('DECRYPT_FAILED');
+        }
+        return result;
+    }
+    /**
+     * Verify a signed (unencrypted) envelope and return the message.
+     *
+     * Use for envelopes created with createSignedEnvelope().
+     * Verifies signature, timestamp, nonce, and scope — skips decryption.
+     *
+     * @param envelope - A signed (unencrypted) transport envelope.
+     * @returns Verified message or error with sub-code.
+     */
+    async receiveSigned(envelope) {
+        this.lastDetail = '';
+        const verified = await this.verifyEnvelope(envelope);
+        if (!verified.ok)
+            return verified;
+        let payload;
+        try {
+            payload = JSON.parse(new TextDecoder().decode(verified.value.payloadBytes));
+        }
+        catch {
+            return err('DECRYPT_FAILED:PARSE');
+        }
+        // Mechanism 2: Protocol information available in metadata for applications to display
+        // Applications can show this to users if needed (envelope.protocol, envelope.documentationUrl)
+        return ok({
+            sender: envelope.sender,
+            payload,
+            scope: envelope.scope,
+            timestamp: envelope.timestamp,
+            metadata: envelope.protocol && envelope.documentationUrl
+                ? {
+                    protocol: envelope.protocol,
+                    documentationUrl: envelope.documentationUrl,
+                }
+                : undefined,
+        });
+    }
+    /**
+     * Discover available tools in the registry.
+     *
+     * Query xRegistry for tools matching the given service prefix or capability.
+     * Returns tool metadata including name, description, schema, and trust level.
+     *
+     * @param service - Optional service prefix to filter by (e.g., "payments")
+     * @returns Array of tool metadata or empty array if none found
+     *
+     * @example
+     * ```typescript
+     * import { Agent } from '@private.me/xbind';
+     * import { ToolRegistry } from"./_deps/xregistry/index.js";
+     * import { setToolRegistry } from '@private.me/xbind/agent-call';
+     *
+     * const registry = new ToolRegistry();
+     * registry.register({
+     *   name: 'payments:createCharge',
+     *   description: 'Create a payment charge',
+     *   schema: { type: 'object', properties: { amount: { type: 'number' } } },
+     *   trustLevel: 'verified',
+     *   endpoint: 'https://api.stripe.com/v1/charges',
+     *   capabilities: ['payment', 'charge']
+     * });
+     *
+     * setToolRegistry(registry);
+     *
+     * const agent = await Agent.quickstart();
+     *
+     * // Discover all payment tools
+     * const tools = await agent.discover('payments');
+     * console.log(tools); // [{ name: 'payments:createCharge', ... }]
+     *
+     * // Discover all tools
+     * const allTools = await agent.discover();
+     * ```
+     */
+    async discover(service) {
+        // Import dynamically to avoid circular dependency
+        // SAFETY: Dynamic import allows agent-call.ts to import agent.ts without circular reference
+        const { getToolRegistry } = await import('./agent-call.js');
+        const registry = getToolRegistry();
+        if (!registry) {
+            // No registry configured - return empty array
+            return [];
+        }
+        if (!service) {
+            // No filter - return all tools
+            return registry.listAll();
+        }
+        // Filter by service prefix using registry search
+        // Search handles name, capability, and description matching
+        const results = registry.search(service);
+        return results;
+    }
+    /** Generate an Express-compatible middleware handler. */
+    middleware() {
+        return async (req, res, next) => {
+            const validated = validateEnvelope(req.body);
+            if (!validated.ok) {
+                res.status(400).json({ error: validated.error });
+                return;
+            }
+            // SAFETY: validateEnvelope returns AnyTransportEnvelope
+            const result = await this.receive(validated.value);
+            if (!result.ok) {
+                const code = result.error === 'TIMESTAMP_EXPIRED'
+                    || result.error === 'REPLAY_DETECTED'
+                    ? 403 : 401;
+                res.status(code).json({ error: result.error });
+                return;
+            }
+            req['agentMessage'] = result.value;
+            next();
+        };
+    }
+    /**
+     * Cleanup resources (timers, handlers, etc.)
+     *
+     * Call this in tests or when disposing an agent to prevent timer leaks.
+     * Clears the ephemeral identity auto-cleanup timer if present.
+     */
+    cleanup() {
+        if (this.cleanupTimer) {
+            clearTimeout(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+    }
+    /**
+     * Dispose of agent resources (alias for cleanup)
+     *
+     * Provided for compatibility with test cleanup patterns.
+     */
+    dispose() {
+        this.cleanup();
+    }
+    /**
+     * Attempt sender-side key agreement.
+     *
+     * If both sides support ML-KEM-768, uses hybrid (X25519 + ML-KEM-768).
+     * Otherwise falls back to X25519-only ECDH.
+     * Returns null if recipient has no X25519 key registered.
+     * Also returns whether recipient supports ML-DSA-65 for v3 envelopes.
+     */
+    async trySenderECDH(recipientDid) {
+        const entry = await this.registry.getEntry(recipientDid);
+        if (!entry.ok || !entry.value.x25519PublicKey)
+            return null;
+        const recipientHasMlDsa = !!entry.value.mlDsaPublicKey;
+        const recipientX25519 = await importX25519PublicKey(entry.value.x25519PublicKey);
+        if (!recipientX25519.ok)
+            return null;
+        // Try hybrid if both sides have ML-KEM keys
+        if (entry.value.mlKemPublicKey && this.identity.mlKemSecretKey) {
+            const hybrid = await senderHybridKeyAgreement(recipientX25519.value, entry.value.mlKemPublicKey);
+            if (hybrid.ok) {
+                return {
+                    sharedKey: hybrid.value.sharedKey,
+                    ephemeralPublicKey: hybrid.value.ephemeralPublicKey,
+                    kemCiphertext: hybrid.value.kemCiphertext,
+                    recipientHasMlDsa,
+                };
+            }
+        }
+        // Fallback to X25519-only
+        const result = await senderKeyAgreement(recipientX25519.value);
+        if (!result.ok)
+            return null;
+        return { ...result.value, recipientHasMlDsa };
+    }
+    /** Send with ECDH forward secrecy (ephemeral key in envelope). */
+    async sendWithECDH(opts, plaintext, sharedKey, ephemeralPublicKey, progress) {
+        progress?.update('Encrypting message with ECDH...', 60);
+        const envelope = await createEnvelope({
+            senderDid: this.identity.did,
+            recipientDid: opts.to,
+            scope: opts.scope,
+            plaintext,
+            privateKey: this.identity.privateKey,
+            sharedKey,
+            ephemeralPublicKey,
+        });
+        if (!envelope.ok)
+            return err('ENVELOPE_FAILED:ENCRYPT');
+        progress?.update('Sending message...', 90);
+        const result = await this.transports[0].send(envelope.value, opts.to);
+        if (result.ok) {
+            progress?.complete();
+        }
+        return result;
+    }
+    /** Send with hybrid KEM (X25519 + ML-KEM-768) via v2 envelope. */
+    async sendWithHybrid(opts, plaintext, sharedKey, ephemeralPublicKey, kemCiphertext, progress) {
+        progress?.update('Encrypting message with hybrid KEM...', 60);
+        const envelope = await createEnvelopeV2({
+            senderDid: this.identity.did,
+            recipientDid: opts.to,
+            scope: opts.scope,
+            plaintext,
+            privateKey: this.identity.privateKey,
+            sharedKey,
+            ephemeralPublicKey,
+            kemCiphertext,
+        });
+        if (!envelope.ok)
+            return err('ENVELOPE_FAILED:ENCRYPT');
+        progress?.update('Sending message...', 90);
+        // SAFETY: AnyTransportEnvelope is accepted by transport.send
+        const result = await this.transports[0].send(envelope.value, opts.to);
+        if (result.ok) {
+            progress?.complete();
+        }
+        return result;
+    }
+    /** Send with hybrid KEM + dual signatures via v3 envelope. */
+    async sendWithHybridV3(opts, plaintext, sharedKey, ephemeralPublicKey, kemCiphertext, progress) {
+        if (!this.identity.mlDsaSecretKey) {
+            return err('ENVELOPE_FAILED:PQ_KEY_MISSING');
+        }
+        progress?.update('Encrypting with post-quantum signatures...', 60);
+        const envelope = await createEnvelopeV3({
+            senderDid: this.identity.did,
+            recipientDid: opts.to,
+            scope: opts.scope,
+            plaintext,
+            privateKey: this.identity.privateKey,
+            sharedKey,
+            ephemeralPublicKey,
+            kemCiphertext,
+            mlDsaSecretKey: this.identity.mlDsaSecretKey,
+        });
+        if (!envelope.ok) {
+            this.lastDetail = `v3 envelope error: ${envelope.error}`;
+            return err('ENVELOPE_FAILED:ENCRYPT');
+        }
+        progress?.update('Sending message...', 90);
+        // SAFETY: AnyTransportEnvelope is accepted by transport.send
+        const result = await this.transports[0].send(envelope.value, opts.to);
+        if (result.ok) {
+            progress?.complete();
+        }
+        return result;
+    }
+    async sendDirect(opts, plaintext, sharedKey, progress) {
+        progress?.update('Encrypting message...', 60);
+        const envelope = await createEnvelope({
+            senderDid: this.identity.did,
+            recipientDid: opts.to,
+            scope: opts.scope,
+            plaintext,
+            privateKey: this.identity.privateKey,
+            sharedKey,
+        });
+        if (!envelope.ok)
+            return err('ENVELOPE_FAILED:ENCRYPT');
+        progress?.update('Sending message...', 90);
+        const result = await this.transports[0].send(envelope.value, opts.to);
+        if (result.ok) {
+            progress?.complete();
+        }
+        return result;
+    }
+    /**
+     * Check whether the recipient supports Xchange (XorIDA key transport).
+     *
+     * @param recipientDid - Recipient DID to check.
+     * @returns True if recipient has xchange: true in registry.
+     */
+    async canUseXchange(recipientDid) {
+        const entry = await this.registry.getEntry(recipientDid);
+        if (!entry.ok)
+            return false;
+        return entry.value.xchange === true;
+    }
+    /**
+     * Send via Xchange mode: random key + AES-GCM encrypt, bundle, XorIDA split, v4 envelopes.
+     *
+     * Opt-in performance mode. No KEM, no key agreement — the random key is
+     * embedded in the bundle and split across channels. Single security layer
+     * (information-theoretic) + Ed25519 authentication. ~180x faster than V3.
+     */
+    async sendXchange(opts, plaintext, progress) {
+        const config = opts.splitChannelConfig ?? DEFAULT_SPLIT_CONFIG;
+        if (this.transports.length < config.totalShares) {
+            // eslint-disable-next-line no-console
+            console.warn(`Split-channel: ${config.totalShares} shares but only ${this.transports.length} transport(s). ` +
+                `For channel separation, provide at least ${config.totalShares} transports.`);
+        }
+        progress?.update('Generating Xchange key...', 40);
+        const keyResult = await generateXchangeKey();
+        if (!keyResult.ok)
+            return err('KEY_AGREEMENT_FAILED');
+        progress?.update('Encrypting message...', 50);
+        const bundleResult = await xchangeEncrypt(plaintext, keyResult.value);
+        if (!bundleResult.ok)
+            return err('ENVELOPE_FAILED:ENCRYPT');
+        // Load crypto package from Vault Store (payment-gated)
+        const crypto = await this.ensureCrypto();
+        const n = config.totalShares;
+        const k = config.threshold;
+        const p = crypto.nextOddPrime(n);
+        const blockSize = p - 1;
+        const padded = crypto.pkcs7Pad(bundleResult.value, blockSize);
+        const { key: hmacKey, signature: hmacSig } = await crypto.generateHMAC(padded);
+        progress?.update('Splitting message into shares...', 60);
+        let shareArrays;
+        try {
+            shareArrays = crypto.splitXorIDA(padded, n, k);
+        }
+        catch {
+            return err('ENVELOPE_FAILED:SPLIT');
+        }
+        const hmacKeyB64 = toBase64(hmacKey);
+        const hmacSigB64 = toBase64(hmacSig);
+        const groupId = generateUUID();
+        const results = [];
+        progress?.update('Sending shares...', 70);
+        for (let i = 0; i < shareArrays.length; i++) {
+            const shareData = shareArrays[i];
+            const shareB64 = formatShareHeader(toBase64(shareData));
+            const shareBytes = new TextEncoder().encode(shareB64);
+            const envResult = await createEnvelopeV4({
+                senderDid: this.identity.did,
+                recipientDid: opts.to,
+                scope: opts.scope,
+                shareData: shareBytes,
+                privateKey: this.identity.privateKey,
+                shareIndex: i,
+                shareTotal: n,
+                shareThreshold: k,
+                shareGroupId: groupId,
+                shareHmacKey: hmacKeyB64,
+                shareHmacSig: hmacSigB64,
+            });
+            if (!envResult.ok) {
+                results.push(err('ENVELOPE_FAILED:ENCRYPT'));
+                continue;
+            }
+            // Route share[i] to transports[i % transports.length]
+            const transport = this.transports[i % this.transports.length];
+            // SAFETY: Transport accepts v1; v4 has same required fields
+            const sendResult = await transport.send(envResult.value, opts.to);
+            results.push(sendResult);
+            // Update progress for each share sent
+            const shareProgress = 70 + Math.floor((i + 1) / shareArrays.length * 20);
+            progress?.update(`Sent share ${i + 1}/${shareArrays.length}...`, shareProgress);
+        }
+        const successes = results.filter((r) => r.ok).length;
+        if (successes < k) {
+            return err('SEND_FAILED:BELOW_THRESHOLD');
+        }
+        progress?.complete();
+        return ok(undefined);
+    }
+    /**
+     * Split plaintext via XorIDA and send each share as a separate V3 envelope.
+     *
+     * Default split-channel path with three independent cryptographic layers:
+     * XorIDA payload split, hybrid PQ KEM, and dual signatures.
+     * Returns ok() if at least threshold sends succeed.
+     */
+    async sendSplitChannel(opts, plaintext, sharedKey, ephemeralPublicKey, kemCiphertext, recipientHasMlDsa, progress) {
+        const config = opts.splitChannelConfig ?? DEFAULT_SPLIT_CONFIG;
+        if (this.transports.length < config.totalShares) {
+            // eslint-disable-next-line no-console
+            console.warn(`Split-channel: ${config.totalShares} shares but only ${this.transports.length} transport(s). ` +
+                `For channel separation, provide at least ${config.totalShares} transports.`);
+        }
+        progress?.update('Splitting message into shares...', 50);
+        const splitResult = await splitForChannel(plaintext, config);
+        if (!splitResult.ok)
+            return err('ENVELOPE_FAILED:SPLIT');
+        const shares = splitResult.value;
+        progress?.update('Encrypting and sending shares...', 70);
+        const results = await this.sendShareEnvelopes(opts, shares, sharedKey, ephemeralPublicKey, kemCiphertext, recipientHasMlDsa, progress);
+        const successes = results.filter((r) => r.ok).length;
+        if (successes < config.threshold) {
+            return err('SEND_FAILED:BELOW_THRESHOLD');
+        }
+        progress?.complete();
+        return ok(undefined);
+    }
+    /**
+     * Create and send an envelope for each share independently.
+     *
+     * Routes share[i] to transports[i % transports.length] for channel separation.
+     */
+    async sendShareEnvelopes(opts, shares, sharedKey, ephemeralPublicKey, kemCiphertext, recipientHasMlDsa, progress) {
+        const results = [];
+        for (let i = 0; i < shares.length; i++) {
+            const share = shares[i];
+            const shareBytes = new TextEncoder().encode(share.data);
+            let envResult;
+            if (kemCiphertext && ephemeralPublicKey && recipientHasMlDsa && this.identity.mlDsaSecretKey) {
+                envResult = await createEnvelopeV3({
+                    senderDid: this.identity.did,
+                    recipientDid: opts.to,
+                    scope: opts.scope,
+                    plaintext: shareBytes,
+                    privateKey: this.identity.privateKey,
+                    sharedKey,
+                    ephemeralPublicKey,
+                    kemCiphertext,
+                    mlDsaSecretKey: this.identity.mlDsaSecretKey,
+                    shareIndex: share.index,
+                    shareTotal: share.total,
+                    shareThreshold: share.threshold,
+                    shareGroupId: share.groupId,
+                    shareHmacKey: share.hmacKey,
+                    shareHmacSig: share.hmacSig,
+                });
+            }
+            else if (kemCiphertext && ephemeralPublicKey) {
+                envResult = await createEnvelopeV2({
+                    senderDid: this.identity.did,
+                    recipientDid: opts.to,
+                    scope: opts.scope,
+                    plaintext: shareBytes,
+                    privateKey: this.identity.privateKey,
+                    sharedKey,
+                    ephemeralPublicKey,
+                    kemCiphertext,
+                    shareIndex: share.index,
+                    shareTotal: share.total,
+                    shareThreshold: share.threshold,
+                    shareGroupId: share.groupId,
+                    shareHmacKey: share.hmacKey,
+                    shareHmacSig: share.hmacSig,
+                });
+            }
+            else {
+                envResult = await createEnvelope({
+                    senderDid: this.identity.did,
+                    recipientDid: opts.to,
+                    scope: opts.scope,
+                    plaintext: shareBytes,
+                    privateKey: this.identity.privateKey,
+                    sharedKey,
+                    ephemeralPublicKey,
+                    shareIndex: share.index,
+                    shareTotal: share.total,
+                    shareThreshold: share.threshold,
+                    shareGroupId: share.groupId,
+                    shareHmacKey: share.hmacKey,
+                    shareHmacSig: share.hmacSig,
+                });
+            }
+            if (!envResult.ok) {
+                results.push(err('ENVELOPE_FAILED:ENCRYPT'));
+                continue;
+            }
+            // Route share[i] to transports[i % transports.length]
+            const transport = this.transports[i % this.transports.length];
+            // SAFETY: Transport accepts v1; v2/v3 is a superset of v1 fields
+            const sendResult = await transport.send(envResult.value, opts.to);
+            results.push(sendResult);
+            // Update progress for each share sent
+            const shareProgress = 70 + Math.floor((i + 1) / shares.length * 20);
+            progress?.update(`Sent share ${i + 1}/${shares.length}...`, shareProgress);
+        }
+        return results;
+    }
+    /**
+     * Receive and accumulate a split-channel share envelope.
+     *
+     * Verifies the envelope, extracts share metadata, accumulates shares.
+     * When threshold is reached, reconstructs the original plaintext.
+     *
+     * @param envelope - A share envelope with split-channel metadata
+     * @returns AgentMessage if threshold met, null if more shares needed
+     */
+    async receiveSplitShare(envelope) {
+        if (envelope.shareGroupId === undefined) {
+            return err('VERIFICATION_FAILED');
+        }
+        const receiveResult = await this.receiveRaw(envelope);
+        if (!receiveResult.ok)
+            return receiveResult;
+        const { sender, decryptedText, scope, timestamp } = receiveResult.value;
+        const share = {
+            data: decryptedText,
+            index: envelope.shareIndex ?? 0,
+            total: envelope.shareTotal ?? 2,
+            threshold: envelope.shareThreshold ?? 2,
+            groupId: envelope.shareGroupId,
+            hmacKey: envelope.shareHmacKey ?? '',
+            hmacSig: envelope.shareHmacSig ?? '',
+        };
+        return this.accumulateShare(share, sender, scope, timestamp);
+    }
+    /**
+     * Receive and accumulate a v4 Xchange share envelope.
+     *
+     * Verifies Ed25519 signature, extracts raw share data (no decryption —
+     * the XorIDA share IS the payload). When threshold is reached,
+     * reconstructs and decrypts via Xchange.
+     *
+     * @param envelope - A v4 Xchange envelope with share metadata.
+     * @returns AgentMessage if threshold met, null if more shares needed.
+     */
+    async receiveXchangeShare(envelope) {
+        this.lastDetail = '';
+        const verified = await this.verifyEnvelope(envelope);
+        if (!verified.ok)
+            return verified;
+        // V4: payload is the raw share data (base64 of share bytes), NOT encrypted
+        const shareText = new TextDecoder().decode(verified.value.payloadBytes);
+        const share = {
+            data: shareText,
+            index: envelope.shareIndex,
+            total: envelope.shareTotal,
+            threshold: envelope.shareThreshold,
+            groupId: envelope.shareGroupId,
+            hmacKey: envelope.shareHmacKey,
+            hmacSig: envelope.shareHmacSig,
+        };
+        return this.accumulateXchangeShare(share, envelope.sender, envelope.scope, envelope.timestamp);
+    }
+    /**
+     * Accumulate a Xchange share and attempt reconstruction + decryption.
+     *
+     * When threshold is met:
+     * 1. Reconstruct padded bundle from XorIDA shares
+     * 2. Verify HMAC (BEFORE decrypt — CRITICAL)
+     * 3. Unpad → extract bundle → xchangeDecrypt → plaintext
+     */
+    async accumulateXchangeShare(share, sender, scope, timestamp) {
+        const existing = this.shareAccumulator.get(share.groupId) ?? [];
+        const isDuplicate = existing.some((s) => s.index === share.index);
+        if (!isDuplicate) {
+            existing.push(share);
+            this.shareAccumulator.set(share.groupId, existing);
+        }
+        if (existing.length < share.threshold) {
+            return ok(null);
+        }
+        this.shareAccumulator.delete(share.groupId);
+        const usedShares = existing.slice(0, share.threshold);
+        const n = share.total;
+        const k = share.threshold;
+        // Decode share data from base64
+        let shareData;
+        try {
+            shareData = usedShares.map((s) => fromBase64(parseShareHeader(s.data)));
+        }
+        catch {
+            return err('DECRYPT_FAILED');
+        }
+        const indices = usedShares.map((s) => s.index);
+        // Load crypto package from Vault Store (payment-gated)
+        const crypto = await this.ensureCrypto();
+        // Reconstruct padded bundle
+        let padded;
+        try {
+            padded = crypto.reconstructXorIDA(shareData, indices, n, k);
+        }
+        catch {
+            return err('DECRYPT_FAILED');
+        }
+        // HMAC verification BEFORE decrypt — CRITICAL
+        let hmacKey;
+        let hmacSig;
+        try {
+            hmacKey = fromBase64(usedShares[0].hmacKey);
+            hmacSig = fromBase64(usedShares[0].hmacSig);
+        }
+        catch {
+            return err('DECRYPT_FAILED');
+        }
+        const hmacValid = await crypto.verifyHMAC(hmacKey, padded, hmacSig);
+        if (!hmacValid) {
+            this.lastDetail = 'HMAC verification failed before decrypt';
+            return err('DECRYPT_FAILED');
+        }
+        // Unpad
+        const p = crypto.nextOddPrime(n);
+        const blockSize = p - 1;
+        const unpadResult = crypto.pkcs7Unpad(padded, blockSize);
+        if (!unpadResult.ok)
+            return err('DECRYPT_FAILED');
+        // Xchange decrypt: extract K, IV, ciphertext from bundle
+        const decryptResult = await xchangeDecrypt(unpadResult.value);
+        if (!decryptResult.ok)
+            return err('DECRYPT_FAILED:DECRYPTION');
+        let payload;
+        try {
+            payload = JSON.parse(new TextDecoder().decode(decryptResult.value));
+        }
+        catch {
+            return err('DECRYPT_FAILED:PARSE');
+        }
+        // Mechanism 2: Protocol information available in return value
+        // Applications can display: "Secured with PRIVATE.ME/xBind/v3. Learn more: https://private.me/docs/xbind.html"
+        return ok({ sender, payload, scope, timestamp });
+    }
+    /**
+     * Accumulate a share and attempt reconstruction when threshold is met.
+     */
+    async accumulateShare(share, sender, scope, timestamp) {
+        const existing = this.shareAccumulator.get(share.groupId) ?? [];
+        const isDuplicate = existing.some((s) => s.index === share.index);
+        if (!isDuplicate) {
+            existing.push(share);
+            this.shareAccumulator.set(share.groupId, existing);
+        }
+        if (existing.length < share.threshold) {
+            return ok(null);
+        }
+        this.shareAccumulator.delete(share.groupId);
+        const result = await reconstructFromChannel(existing);
+        if (!result.ok)
+            return err('DECRYPT_FAILED');
+        let payload;
+        try {
+            payload = JSON.parse(new TextDecoder().decode(result.value));
+        }
+        catch {
+            return err('DECRYPT_FAILED');
+        }
+        // Mechanism 2: Protocol information available in return value
+        // Applications can display: "Secured with PRIVATE.ME/xBind/v3. Learn more: https://private.me/docs/xbind.html"
+        return ok({ sender, payload, scope, timestamp });
+    }
+    /**
+     * Common envelope verification: version, timestamp, nonce, DID, signature, scope.
+     *
+     * Used by receive(), receiveSigned(), and receiveRaw() to avoid duplication.
+     * Consumes the nonce on success (replay prevention).
+     */
+    async verifyEnvelope(envelope) {
+        // Runtime null guard: catch null/undefined despite TypeScript types
+        if (!envelope || typeof envelope !== 'object') {
+            this.lastDetail = 'envelope is null or not an object';
+            return err('VERIFICATION_FAILED:INVALID_ENVELOPE');
+        }
+        if ((envelope.v !== 1 && envelope.v !== 2 && envelope.v !== 3 && envelope.v !== 4) || envelope.alg !== 'Ed25519') {
+            this.lastDetail = `v=${String(envelope.v)}, alg=${String(envelope.alg)}`;
+            return err('VERIFICATION_FAILED:UNSUPPORTED_VERSION');
+        }
+        // SECURITY FIX (v1.1.3): Type guard for timestamp (prevent type confusion)
+        // Attack: Send timestamp: "soon" → Date.now() - "soon" = NaN → window check bypassed
+        if (typeof envelope.timestamp !== 'number' || !Number.isFinite(envelope.timestamp)) {
+            this.lastDetail = `timestamp=${String(envelope.timestamp)} (must be finite number)`;
+            return err('VERIFICATION_FAILED:INVALID_ENVELOPE');
+        }
+        const age = Math.abs(Date.now() - envelope.timestamp);
+        if (age > this.timestampWindowMs) {
+            this.lastDetail = `age=${age}ms, max=${this.timestampWindowMs}ms`;
+            return err('TIMESTAMP_EXPIRED');
+        }
+        // DEDUP-1: Pass shareContext for share-aware deduplication
+        // Allows same nonce with different shares (idempotent retries)
+        // while still blocking true replays (same nonce + same share)
+        const shareContext = envelope.shareGroupId !== undefined ? {
+            shareGroupId: envelope.shareGroupId,
+            shareIndex: envelope.shareIndex,
+        } : undefined;
+        const nonceOk = await this.nonceStore.check(envelope.nonce, envelope.sender, shareContext);
+        if (!nonceOk) {
+            this.lastDetail = `nonce=${envelope.nonce}`;
+            return err('REPLAY_DETECTED');
+        }
+        const senderKey = await this.registry.resolve(envelope.sender);
+        if (!senderKey.ok) {
+            this.lastDetail = `did=${envelope.sender}`;
+            return err('VERIFICATION_FAILED:DID_NOT_IN_REGISTRY');
+        }
+        const pubKey = await importPublicKey(senderKey.value);
+        if (!pubKey.ok) {
+            this.lastDetail = `did=${envelope.sender}`;
+            return err('VERIFICATION_FAILED:KEY_IMPORT_FAILED');
+        }
+        // SECURITY FIX (v1.1.3): Guard for missing signature field (prevent TypeError crash)
+        // Attack: Send envelope without signature field → fromBase64(undefined) throws → DoS
+        if (!envelope.signature || typeof envelope.signature !== 'string') {
+            this.lastDetail = 'signature field missing or invalid';
+            return err('VERIFICATION_FAILED:SIGNATURE_MISMATCH');
+        }
+        // SECURITY FIX (v1.1.3): Verify signature over canonical envelope representation
+        // (not just payload) to prevent replay attacks via nonce substitution
+        const sigBytes = fromBase64(envelope.signature);
+        // Create canonical representation for signature verification
+        const canonicalData = JSON.stringify({
+            v: envelope.v,
+            alg: envelope.alg,
+            sender: envelope.sender,
+            recipient: envelope.recipient,
+            timestamp: envelope.timestamp,
+            nonce: envelope.nonce,
+            scope: envelope.scope,
+            payload: envelope.payload,
+        });
+        const canonicalBytes = new TextEncoder().encode(canonicalData);
+        // Verify canonical signature (v1.1.3+)
+        // SECURITY: No legacy fallback. Pre-v1.1.3 envelopes use payload-only signatures
+        // that don't cover nonce, allowing unlimited replay attacks. All senders must upgrade.
+        const sigValid = await verify(pubKey.value, sigBytes, canonicalBytes);
+        if (!sigValid.ok || !sigValid.value) {
+            this.lastDetail = 'signature does not match canonical envelope (v1.1.3+ required)';
+            return err('VERIFICATION_FAILED:SIGNATURE_MISMATCH');
+        }
+        // V3: verify ML-DSA-65 post-quantum signature (both sigs must pass)
+        if (envelope.v === 3 && 'pqSignature' in envelope) {
+            // SECURITY FIX (v1.1.5): Guard for non-string pqSignature field
+            if (typeof envelope.pqSignature !== 'string') {
+                this.lastDetail = 'pqSignature field not a string';
+                return err('VERIFICATION_FAILED:INVALID_ENVELOPE');
+            }
+            const senderEntry = await this.registry.getEntry(envelope.sender);
+            if (!senderEntry.ok || !senderEntry.value.mlDsaPublicKey) {
+                this.lastDetail = `did=${envelope.sender} missing ML-DSA public key`;
+                return err('VERIFICATION_FAILED:PQ_KEY_MISSING');
+            }
+            const pqSigBytes = fromBase64(envelope.pqSignature);
+            // Verify ML-DSA-65 post-quantum signature (canonical only, v1.1.3+)
+            // SECURITY: No legacy fallback for same replay protection reasons as Ed25519
+            const pqValid = await verifyMlDsa65(senderEntry.value.mlDsaPublicKey, pqSigBytes, canonicalBytes);
+            if (!pqValid.ok || !pqValid.value) {
+                this.lastDetail = 'ML-DSA-65 signature does not match canonical envelope (v1.1.3+ required)';
+                return err('VERIFICATION_FAILED:PQ_SIGNATURE_MISMATCH');
+            }
+        }
+        const hasScope = await this.registry.hasScope(envelope.sender, envelope.scope);
+        if (!hasScope) {
+            this.lastDetail = `scope=${envelope.scope}`;
+            return err('SCOPE_DENIED');
+        }
+        // SECURITY FIX (v1.1.5): Guard for non-string payload field
+        if (typeof envelope.payload !== 'string') {
+            this.lastDetail = 'payload field not a string';
+            return err('VERIFICATION_FAILED:INVALID_ENVELOPE');
+        }
+        // Return decoded payload bytes for decryption
+        const payloadBytes = fromBase64(envelope.payload);
+        return ok({ senderRawKey: senderKey.value, payloadBytes });
+    }
+    /**
+     * Verify and decrypt an envelope, returning raw text (no JSON parse).
+     * Used by receiveSplitShare to get the raw decrypted share data.
+     *
+     * ROT-1: Supports key rotation with fallback to old keys.
+     */
+    async receiveRaw(envelope) {
+        const verified = await this.verifyEnvelope(envelope);
+        if (!verified.ok)
+            return verified;
+        const { senderRawKey } = verified.value;
+        // V4 Xchange: use receiveXchangeShare() instead
+        if (envelope.v === 4) {
+            return err('VERIFICATION_FAILED:UNSUPPORTED_VERSION');
+        }
+        let sharedKey;
+        // V2/V3 hybrid path
+        if ((envelope.v === 2 || envelope.v === 3) && 'kemCiphertext' in envelope) {
+            if (!this.identity.mlKemSecretKey) {
+                return err('DECRYPT_FAILED:KEY_AGREEMENT');
+            }
+            // SECURITY FIX (v1.1.5): Guard for non-string fields
+            if (typeof envelope.ephemeralPub !== 'string' || typeof envelope.kemCiphertext !== 'string') {
+                return err('DECRYPT_FAILED:INVALID_ENVELOPE');
+            }
+            const ephPubBytes = fromBase64(envelope.ephemeralPub);
+            const kemCtBytes = fromBase64(envelope.kemCiphertext);
+            // Validate identity has required public keys for IETF X-Wing combiner
+            if (!this.identity.mlKemPublicKey || !this.identity.mlKemSecretKey) {
+                this.lastDetail = 'ML-KEM keys not available in identity';
+                return err('DECRYPT_FAILED:MISSING_MLKEM_KEYS');
+            }
+            const hybridKey = await receiverHybridKeyAgreement(this.identity.x25519PrivateKey, this.identity.rawX25519PublicKey, ephPubBytes, kemCtBytes, this.identity.mlKemSecretKey, this.identity.mlKemPublicKey);
+            if (!hybridKey.ok) {
+                // ROT-1: Try old rotated keys if current key agreement fails
+                if (this.identity.rotatedKeys && this.identity.rotatedKeys.length > 0) {
+                    for (const rotated of this.identity.rotatedKeys) {
+                        if (!rotated.mlKemSecretKey)
+                            continue; // Skip if ML-KEM key not available
+                        const oldHybridKey = await receiverHybridKeyAgreement(rotated.x25519PrivateKey, this.identity.rawX25519PublicKey, ephPubBytes, kemCtBytes, rotated.mlKemSecretKey, this.identity.mlKemPublicKey);
+                        if (oldHybridKey.ok) {
+                            sharedKey = oldHybridKey.value;
+                            break;
+                        }
+                    }
+                }
+                if (!sharedKey)
+                    return err('DECRYPT_FAILED:KEY_AGREEMENT');
+            }
+            else {
+                sharedKey = hybridKey.value;
+            }
+        }
+        else if (envelope.ephemeralPub) {
+            // SECURITY FIX (v1.1.5): Guard for non-string field
+            if (typeof envelope.ephemeralPub !== 'string') {
+                return err('DECRYPT_FAILED:INVALID_ENVELOPE');
+            }
+            const ephPubBytes = fromBase64(envelope.ephemeralPub);
+            const ecdhKey = await receiverKeyAgreement(this.identity.x25519PrivateKey, ephPubBytes);
+            if (!ecdhKey.ok) {
+                // ROT-1: Try old rotated keys if current key agreement fails
+                if (this.identity.rotatedKeys && this.identity.rotatedKeys.length > 0) {
+                    for (const rotated of this.identity.rotatedKeys) {
+                        const oldEcdhKey = await receiverKeyAgreement(rotated.x25519PrivateKey, ephPubBytes);
+                        if (oldEcdhKey.ok) {
+                            sharedKey = oldEcdhKey.value;
+                            break;
+                        }
+                    }
+                }
+                if (!sharedKey)
+                    return err('DECRYPT_FAILED:KEY_AGREEMENT');
+            }
+            else {
+                sharedKey = ecdhKey.value;
+            }
+        }
+        else {
+            // SECURITY FIX (v1.1.6): Removed insecure fallback
+            // Envelopes without ephemeralPub rejected (sender must use X25519 ECDH)
+            return err('DECRYPT_FAILED:NO_EPHEMERAL_KEY');
+        }
+        // TypeScript narrowing: sharedKey is guaranteed to be defined here due to control flow
+        if (!sharedKey)
+            return err('DECRYPT_FAILED:KEY_AGREEMENT');
+        const decrypted = await decryptPayload(envelope, sharedKey);
+        if (!decrypted.ok)
+            return err('DECRYPT_FAILED:DECRYPTION');
+        const decryptedText = new TextDecoder().decode(decrypted.value);
+        return ok({
+            sender: envelope.sender,
+            decryptedText,
+            scope: envelope.scope,
+            timestamp: envelope.timestamp,
+        });
+    }
+    /**
+     * Create a test envelope for testing purposes.
+     *
+     * This is a helper method for tests to create properly signed and encrypted
+     * envelopes without going through the full send() flow.
+     *
+     * @param recipientDid - Recipient DID
+     * @param payload - Payload object (will be JSON serialized)
+     * @param scope - Permission scope
+     * @returns TransportEnvelope or null if creation failed
+     * @internal
+     */
+    async createTestEnvelope(recipientDid, payload, scope) {
+        // Resolve recipient entry
+        const entry = await this.registry.getEntry(recipientDid);
+        if (!entry.ok || !entry.value.x25519PublicKey)
+            return null;
+        // Import X25519 public key
+        const recipientX25519 = await importX25519PublicKey(entry.value.x25519PublicKey);
+        if (!recipientX25519.ok)
+            return null;
+        // Perform ECDH key agreement
+        const kaResult = await senderKeyAgreement(recipientX25519.value);
+        if (!kaResult.ok)
+            return null;
+        // Serialize payload
+        const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+        // Create envelope
+        const envelopeResult = await createEnvelope({
+            senderDid: this.identity.did,
+            recipientDid,
+            scope,
+            plaintext,
+            privateKey: this.identity.privateKey,
+            sharedKey: kaResult.value.sharedKey,
+            ephemeralPublicKey: kaResult.value.ephemeralPublicKey,
+        });
+        if (!envelopeResult.ok)
+            return null;
+        return envelopeResult.value;
+    }
+    /**
+     * Send email invitation to establish connection.
+     *
+     * Uses email transport to send branded invitation with one-click acceptance.
+     * Requires EmailTransport to be configured in agent options.
+     *
+     * @param opts - Invitation options
+     * @returns Result with success status
+     *
+     * @example
+     * ```ts
+     * await agent.invite({
+     *   to: 'fulfillment@acme.com',
+     *   message: 'Connect our payment systems'
+     * });
+     * ```
+     */
+    async invite(opts) {
+        if (!this.transports || this.transports.length === 0) {
+            return err('SEND_FAILED');
+        }
+        // Convert raw public key to base64 for transmission
+        const publicKeyBase64 = Buffer.from(this.identity.rawPublicKey).toString('base64');
+        // Create invitation envelope
+        const envelope = {
+            from: this.identity.did,
+            to: opts.to,
+            payload: {
+                agentName: this.name,
+                message: opts.message,
+                publicKey: publicKeyBase64,
+                endpoint: '', // Email-based invites don't need endpoint
+            },
+        };
+        // Send via first transport (assumed to be EmailTransport for invite())
+        const transport = this.transports[0];
+        if (!transport) {
+            return err('SEND_FAILED');
+        }
+        const result = await transport.send(envelope, opts.to);
+        if (!result.ok) {
+            return err('SEND_FAILED');
+        }
+        return ok(undefined);
+    }
+}
+// SECURITY FIX (v1.1.6): Removed deriveSharedKey export (insecure, public-key-only derivation)
+export { generateSharedKey };