@private.me/xbind 1.3.5 → 2.3.4

package/dist-standalone/agent.js

@@ -1,1545 +1 @@
-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.
-     *
-     * **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);
-        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 };
+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};