@private.me/xbind 1.2.0

package/dist-standalone/agent.js

@@ -0,0 +1,1529 @@
+import { ok, err } from"./_deps/shared/index.js";
+import { fromBase64, toBase64, splitXorIDA, reconstructXorIDA, nextOddPrime, pkcs7Pad, pkcs7Unpad, generateHMAC, verifyHMAC, generateUUID, formatShareHeader, parseShareHeader, } from"./_deps/crypto/index.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.
+ *
+ * Matches xail.io/sdk specification:
+ * - Agent.create({ name, registry }) — generate identity + register
+ * - agent.send({ to, payload, scope }) — encrypt, sign, deliver
+ * - agent.receive(envelope) — verify, decrypt, return message
+ */
+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;
+    /**
+     * 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;
+    }
+    /**
+     * 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. Skips registry
+     * registration — the caller is responsible for registering externally.
+     *
+     * Ideal for IoT: factory burns seed → field deploys → boot derives identity.
+     *
+     * @param seed - Exactly 32 bytes of high-entropy key material.
+     * @param opts - Agent options (registry, transport, 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');
+        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);
+        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).
+     *
+     * @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);
+            const hybridKey = await receiverHybridKeyAgreement(this.identity.x25519PrivateKey, ephPubBytes, kemCtBytes, this.identity.mlKemSecretKey);
+            if (!hybridKey.ok)
+                return err('DECRYPT_FAILED:KEY_AGREEMENT');
+            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)
+                return err('DECRYPT_FAILED:KEY_AGREEMENT');
+            sharedKey = ecdhKey.value;
+        }
+        else {
+            // 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);
+        const decrypted = await decryptPayload(envelope, sharedKey);
+        if (!decrypted.ok) {
+            if (opts?.allowCleartext) {
+                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,
+                });
+            }
+            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');
+        const n = config.totalShares;
+        const k = config.threshold;
+        const p = nextOddPrime(n);
+        const blockSize = p - 1;
+        const padded = pkcs7Pad(bundleResult.value, blockSize);
+        const { key: hmacKey, signature: hmacSig } = await generateHMAC(padded);
+        progress?.update('Splitting message into shares...', 60);
+        let shareArrays;
+        try {
+            shareArrays = 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);
+        // Reconstruct padded bundle
+        let padded;
+        try {
+            padded = 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 verifyHMAC(hmacKey, padded, hmacSig);
+        if (!hmacValid) {
+            this.lastDetail = 'HMAC verification failed before decrypt';
+            return err('DECRYPT_FAILED');
+        }
+        // Unpad
+        const p = nextOddPrime(n);
+        const blockSize = p - 1;
+        const unpadResult = 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');
+        }
+        const nonceOk = await this.nonceStore.check(envelope.nonce, envelope.sender);
+        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.
+     */
+    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);
+            const hybridKey = await receiverHybridKeyAgreement(this.identity.x25519PrivateKey, ephPubBytes, kemCtBytes, this.identity.mlKemSecretKey);
+            if (!hybridKey.ok)
+                return err('DECRYPT_FAILED:KEY_AGREEMENT');
+            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)
+                return err('DECRYPT_FAILED:KEY_AGREEMENT');
+            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');
+        }
+        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,
+        });
+    }
+    /**
+     * 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 };