@private.me/xbind 1.2.0

package/dist-standalone/key-agreement.js

@@ -0,0 +1,236 @@
+import { ok, err } from"./_deps/shared/index.js";
+import { MlKem768 } from 'mlkem';
+/* -- Constants -- */
+const X25519_RAW_KEY_BYTES = 32;
+const AES_KEY_BITS = 256;
+/* -- Helpers -- */
+/** Copy Uint8Array to fresh ArrayBuffer. */
+function toArrayBuffer(data) {
+    const buf = new ArrayBuffer(data.byteLength);
+    new Uint8Array(buf).set(data);
+    return buf;
+}
+/* -- Key Generation -- */
+/**
+ * Generate an ephemeral X25519 key pair for ECDH key agreement.
+ *
+ * Uses Web Crypto API to generate a fresh X25519 key pair.
+ * The key pair is ephemeral -- it should be used for a single
+ * key agreement and then discarded.
+ *
+ * @returns Result containing the ephemeral key pair or error.
+ */
+export async function generateEphemeralKeyPair() {
+    try {
+        // SAFETY: X25519 generateKey always returns CryptoKeyPair
+        const keyPair = await crypto.subtle.generateKey({ name: 'X25519' }, true, ['deriveBits']);
+        const rawPub = new Uint8Array(await crypto.subtle.exportKey('raw', keyPair.publicKey));
+        return ok({
+            privateKey: keyPair.privateKey,
+            publicKey: keyPair.publicKey,
+            rawPublicKey: rawPub,
+        });
+    }
+    catch {
+        return err('KEYGEN_FAILED');
+    }
+}
+/* -- Key Import -- */
+/**
+ * Import a raw 32-byte X25519 public key into a CryptoKey.
+ *
+ * Used by the receiver to import the sender's ephemeral public
+ * key from the envelope for ECDH derivation.
+ *
+ * @param rawPublicKey - Raw 32-byte X25519 public key.
+ * @returns Result containing the imported CryptoKey or error.
+ */
+export async function importX25519PublicKey(rawPublicKey) {
+    if (rawPublicKey.length !== X25519_RAW_KEY_BYTES) {
+        return err('INVALID_KEY_LENGTH:EXPECTED_32');
+    }
+    try {
+        const key = await crypto.subtle.importKey('raw', toArrayBuffer(rawPublicKey), { name: 'X25519' }, true, []);
+        return ok(key);
+    }
+    catch {
+        return err('IMPORT_FAILED');
+    }
+}
+/* -- ECDH Key Derivation -- */
+/**
+ * Derive a shared AES-256-GCM key via X25519 ECDH.
+ *
+ * Performs ECDH key agreement between a local private key and a
+ * remote public key, producing 256 bits of shared secret that
+ * are imported as an AES-256-GCM key.
+ *
+ * @param localPrivateKey - Local X25519 private key.
+ * @param remotePublicKey - Remote X25519 public key (CryptoKey).
+ * @returns Result containing the derived AES-256-GCM key or error.
+ */
+export async function deriveSharedKeyECDH(localPrivateKey, remotePublicKey) {
+    try {
+        const sharedBits = await crypto.subtle.deriveBits({ name: 'X25519', public: remotePublicKey }, localPrivateKey, AES_KEY_BITS);
+        const aesKey = await crypto.subtle.importKey('raw', sharedBits, { name: 'AES-GCM', length: AES_KEY_BITS }, false, ['encrypt', 'decrypt']);
+        return ok(aesKey);
+    }
+    catch {
+        return err('DERIVE_FAILED');
+    }
+}
+/* -- High-Level API -- */
+/**
+ * Perform sender-side ECDH key agreement.
+ *
+ * Generates an ephemeral X25519 key pair, derives a shared key
+ * with the recipient's static X25519 public key, and returns
+ * both the shared key and the ephemeral public key to include
+ * in the envelope.
+ *
+ * @param recipientX25519PubKey - Recipient's static X25519 public key.
+ * @returns Result containing the key agreement result or error.
+ */
+export async function senderKeyAgreement(recipientX25519PubKey) {
+    const ephemeral = await generateEphemeralKeyPair();
+    if (!ephemeral.ok)
+        return ephemeral;
+    const shared = await deriveSharedKeyECDH(ephemeral.value.privateKey, recipientX25519PubKey);
+    if (!shared.ok)
+        return shared;
+    return ok({
+        sharedKey: shared.value,
+        ephemeralPublicKey: ephemeral.value.rawPublicKey,
+    });
+}
+/**
+ * Perform receiver-side ECDH key agreement.
+ *
+ * Imports the sender's ephemeral public key from the envelope
+ * and derives the shared key using the receiver's static X25519
+ * private key.
+ *
+ * @param receiverPrivateKey - Receiver's static X25519 private key.
+ * @param senderEphemeralPubRaw - Sender's ephemeral public key (raw bytes).
+ * @returns Result containing the derived AES-256-GCM key or error.
+ */
+export async function receiverKeyAgreement(receiverPrivateKey, senderEphemeralPubRaw) {
+    const imported = await importX25519PublicKey(senderEphemeralPubRaw);
+    if (!imported.ok)
+        return imported;
+    return deriveSharedKeyECDH(receiverPrivateKey, imported.value);
+}
+/* -- Hybrid Key Agreement (X25519 + ML-KEM-768) -- */
+const HYBRID_HKDF_INFO = 'xail-hybrid-kem-v2';
+/**
+ * Combine X25519 and ML-KEM shared secrets via HKDF-SHA256.
+ *
+ * Concatenates 32B X25519 + 32B ML-KEM shared secrets, runs HKDF
+ * with zero salt and 'xail-hybrid-kem-v2' info, outputs 256-bit AES key.
+ * Secure as long as either X25519 OR ML-KEM remains unbroken.
+ *
+ * @param x25519Shared - 32-byte raw X25519 ECDH shared bits.
+ * @param mlKemShared - 32-byte ML-KEM-768 shared secret.
+ * @returns AES-256-GCM CryptoKey derived from both secrets.
+ */
+export async function combineSharedSecrets(x25519Shared, mlKemShared) {
+    try {
+        const combined = new Uint8Array(x25519Shared.length + mlKemShared.length);
+        combined.set(x25519Shared);
+        combined.set(mlKemShared, x25519Shared.length);
+        const baseKey = await crypto.subtle.importKey('raw', toArrayBuffer(combined), 'HKDF', false, ['deriveBits']);
+        const derived = await crypto.subtle.deriveBits({
+            name: 'HKDF',
+            hash: 'SHA-256',
+            salt: new Uint8Array(32),
+            info: new TextEncoder().encode(HYBRID_HKDF_INFO),
+        }, baseKey, AES_KEY_BITS);
+        const aesKey = await crypto.subtle.importKey('raw', derived, { name: 'AES-GCM', length: AES_KEY_BITS }, false, ['encrypt', 'decrypt']);
+        return ok(aesKey);
+    }
+    catch {
+        return err('HKDF_FAILED');
+    }
+}
+/**
+ * Perform sender-side hybrid key agreement (X25519 + ML-KEM-768).
+ *
+ * 1. Generate ephemeral X25519, ECDH → x25519SharedBits
+ * 2. ML-KEM-768 encapsulate → kemCiphertext + mlKemShared
+ * 3. HKDF(x25519Shared || mlKemShared) → AES-256-GCM key
+ *
+ * @param recipientX25519Pub - Recipient's static X25519 public key.
+ * @param recipientMlKemPub - Recipient's ML-KEM-768 public key (1184B).
+ * @returns Hybrid key agreement result with shared key, ephemeral pub, and KEM ciphertext.
+ */
+export async function senderHybridKeyAgreement(recipientX25519Pub, recipientMlKemPub) {
+    // Step 1: Ephemeral X25519 ECDH
+    const ephemeral = await generateEphemeralKeyPair();
+    if (!ephemeral.ok)
+        return ephemeral;
+    let x25519Shared;
+    try {
+        x25519Shared = new Uint8Array(await crypto.subtle.deriveBits({ name: 'X25519', public: recipientX25519Pub }, ephemeral.value.privateKey, AES_KEY_BITS));
+    }
+    catch {
+        return err('DERIVE_FAILED');
+    }
+    // Step 2: ML-KEM-768 encapsulate
+    let kemCipherText;
+    let kemSharedSecret;
+    try {
+        const mlkem = new MlKem768();
+        const [cipherText, sharedSecret] = await mlkem.encap(recipientMlKemPub);
+        kemCipherText = cipherText;
+        kemSharedSecret = sharedSecret;
+    }
+    catch {
+        return err('KEM_ENCAPSULATE_FAILED');
+    }
+    // Step 3: Combine via HKDF
+    const combined = await combineSharedSecrets(x25519Shared, kemSharedSecret);
+    if (!combined.ok)
+        return combined;
+    return ok({
+        sharedKey: combined.value,
+        ephemeralPublicKey: ephemeral.value.rawPublicKey,
+        kemCiphertext: kemCipherText,
+    });
+}
+/**
+ * Perform receiver-side hybrid key agreement (X25519 + ML-KEM-768).
+ *
+ * 1. Import ephemeral X25519, ECDH → x25519SharedBits
+ * 2. ML-KEM-768 decapsulate → mlKemShared
+ * 3. HKDF(x25519Shared || mlKemShared) → same AES-256-GCM key
+ *
+ * @param x25519PrivateKey - Receiver's static X25519 private key.
+ * @param ephPubRaw - Sender's ephemeral X25519 public key (32B).
+ * @param kemCiphertext - ML-KEM-768 ciphertext from sender (1088B).
+ * @param mlKemSecretKey - Receiver's ML-KEM-768 secret key (2400B).
+ * @returns AES-256-GCM shared key or error.
+ */
+export async function receiverHybridKeyAgreement(x25519PrivateKey, ephPubRaw, kemCiphertext, mlKemSecretKey) {
+    // Step 1: X25519 ECDH
+    const imported = await importX25519PublicKey(ephPubRaw);
+    if (!imported.ok)
+        return imported;
+    let x25519Shared;
+    try {
+        x25519Shared = new Uint8Array(await crypto.subtle.deriveBits({ name: 'X25519', public: imported.value }, x25519PrivateKey, AES_KEY_BITS));
+    }
+    catch {
+        return err('DERIVE_FAILED');
+    }
+    // Step 2: ML-KEM-768 decapsulate
+    let mlKemShared;
+    try {
+        const mlkem = new MlKem768();
+        mlKemShared = await mlkem.decap(kemCiphertext, mlKemSecretKey);
+    }
+    catch {
+        return err('KEM_DECAPSULATE_FAILED');
+    }
+    // Step 3: Combine via HKDF
+    return combineSharedSecrets(x25519Shared, mlKemShared);
+}

package/dist-standalone/lazy-init.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @module lazy-init
+ * Lazy agent initialization for zero-click onboarding.
+ *
+ * Defers invite acceptance and identity generation until first
+ * send/receive call. Enables: `Agent.lazy({ name: 'my-service' })`
+ * with no async/await at construction time.
+ *
+ * @example
+ * ```ts
+ * // Environment: XBIND_INVITE_CODE=XBD-abc123
+ *
+ * // Old way (explicit):
+ * const agent = await Agent.create({ name: 'my-service', registry, transport });
+ *
+ * // New way (lazy):
+ * const agent = Agent.lazy({ name: 'my-service' });
+ * // No await, no async — agent is constructed synchronously.
+ * // Invite auto-accepts on first send/receive:
+ * await agent.send({ to: partnerDid, payload: data, scope: 'test' });
+ * ```
+ */
+import { Result } from '@private.me/shared';
+import { Agent } from './agent.js';
+import type { AgentError, AgentSendOptions, AgentMessage, AgentReceiveOptions } from './agent.js';
+import type { AnyTransportEnvelope } from './envelope.js';
+import type { AutoAcceptConfig } from './auto-accept.js';
+import type { TrustRegistry } from './trust-registry.js';
+import type { XailTransportAdapter } from './transport.js';
+/**
+ * Lazy agent configuration options.
+ */
+export interface LazyAgentConfig {
+    /** Service name (required). */
+    name: string;
+    /** Invite code or URL. If omitted, reads from XBIND_INVITE_CODE. */
+    inviteCode?: string;
+    /** Auto-accept config (optional). */
+    autoAccept?: AutoAcceptConfig;
+    /** Custom trust registry (optional, auto-configured from invite if omitted). */
+    registry?: TrustRegistry;
+    /** Custom transport adapter (optional, auto-configured from invite if omitted). */
+    transport?: XailTransportAdapter | XailTransportAdapter[];
+    /** Enable post-quantum signatures (default: false). */
+    postQuantumSig?: boolean;
+    /** Enable Xchange mode support (default: false). */
+    xchange?: boolean;
+    /** Service endpoint URL (required for invite acceptance). */
+    endpoint?: string;
+}
+/**
+ * Lazy agent error codes.
+ */
+export declare enum LazyAgentErrorCode {
+    INIT_FAILED = "LAZY_AGENT_INIT_FAILED",
+    AUTO_ACCEPT_FAILED = "LAZY_AGENT_AUTO_ACCEPT_FAILED",
+    AGENT_CREATION_FAILED = "LAZY_AGENT_AGENT_CREATION_FAILED"
+}
+/**
+ * Lazy agent error.
+ */
+export interface LazyAgentError {
+    code: LazyAgentErrorCode;
+    message: string;
+    hint?: string;
+    cause?: unknown;
+}
+/**
+ * Lazy agent wrapper.
+ *
+ * Proxies all Agent methods and initializes on first call.
+ * Caches the initialized agent for subsequent calls.
+ */
+export declare class LazyAgent {
+    private config;
+    private agent;
+    private initPromise;
+    private lastError;
+    constructor(config: LazyAgentConfig);
+    /**
+     * Get the agent's DID.
+     *
+     * Triggers initialization if not already initialized.
+     * Throws if initialization fails.
+     */
+    get did(): string;
+    /**
+     * Check if agent is ready (initialized).
+     */
+    isReady(): boolean;
+    /**
+     * Get last initialization error (if any).
+     */
+    getLastError(): LazyAgentError | null;
+    /**
+     * Ensure agent is initialized.
+     *
+     * Can be called explicitly to trigger init before first send/receive.
+     * Safe to call multiple times — subsequent calls return cached agent.
+     *
+     * @returns Agent instance or error
+     */
+    ensureInitialized(): Promise<Result<Agent, AgentError>>;
+    /**
+     * Internal initialization logic.
+     *
+     * 1. Auto-accept invite (if XBIND_INVITE_CODE set)
+     * 2. Create agent identity
+     * 3. Configure registry and transport
+     * 4. Return initialized agent
+     */
+    private initialize;
+    /**
+     * Send a message (proxied to underlying agent).
+     *
+     * Automatically initializes agent on first call.
+     */
+    send(opts: AgentSendOptions): Promise<Result<void, AgentError>>;
+    /**
+     * Receive a message (proxied to underlying agent).
+     *
+     * Automatically initializes agent on first call.
+     */
+    receive(envelope: AnyTransportEnvelope, opts?: AgentReceiveOptions): Promise<Result<AgentMessage, AgentError>>;
+    /**
+     * Receive a split-channel share (proxied to underlying agent).
+     *
+     * Automatically initializes agent on first call.
+     */
+    receiveSplitShare(envelope: AnyTransportEnvelope): Promise<Result<AgentMessage | null, AgentError>>;
+    /**
+     * Get environment variable value.
+     *
+     * @param key - Environment variable name
+     * @returns Environment variable value or empty string
+     */
+    private getEnv;
+    /**
+     * Export the underlying agent (for advanced use cases).
+     *
+     * Throws if agent is not initialized.
+     */
+    getAgent(): Agent;
+}
+/**
+ * Create a lazy agent that initializes on first use.
+ *
+ * Extension method for Agent class. Adds `Agent.lazy()` factory.
+ *
+ * @param config - Lazy agent configuration
+ * @returns Lazy agent wrapper
+ *
+ * @example
+ * ```ts
+ * // Environment: XBIND_INVITE_CODE=XBD-abc123
+ *
+ * const agent = createLazyAgent({ name: 'my-service' });
+ *
+ * // No initialization yet — happens on first send:
+ * await agent.send({
+ *   to: 'did:key:z6Mk...',
+ *   payload: { action: 'test' },
+ *   scope: 'test',
+ * });
+ * ```
+ */
+export declare function createLazyAgent(config: LazyAgentConfig): LazyAgent;

package/dist-standalone/lazy-init.js

@@ -0,0 +1,295 @@
+/**
+ * @module lazy-init
+ * Lazy agent initialization for zero-click onboarding.
+ *
+ * Defers invite acceptance and identity generation until first
+ * send/receive call. Enables: `Agent.lazy({ name: 'my-service' })`
+ * with no async/await at construction time.
+ *
+ * @example
+ * ```ts
+ * // Environment: XBIND_INVITE_CODE=XBD-abc123
+ *
+ * // Old way (explicit):
+ * const agent = await Agent.create({ name: 'my-service', registry, transport });
+ *
+ * // New way (lazy):
+ * const agent = Agent.lazy({ name: 'my-service' });
+ * // No await, no async — agent is constructed synchronously.
+ * // Invite auto-accepts on first send/receive:
+ * await agent.send({ to: partnerDid, payload: data, scope: 'test' });
+ * ```
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { Agent } from './agent.js';
+import { autoAcceptInvite } from './auto-accept.js';
+import { MemoryTrustRegistry } from './trust-registry.js';
+import { HttpsTransportAdapter } from './transport.js';
+import { toBase64 } from"./_deps/crypto/index.js";
+/**
+ * Lazy agent error codes.
+ */
+export var LazyAgentErrorCode;
+(function (LazyAgentErrorCode) {
+    LazyAgentErrorCode["INIT_FAILED"] = "LAZY_AGENT_INIT_FAILED";
+    LazyAgentErrorCode["AUTO_ACCEPT_FAILED"] = "LAZY_AGENT_AUTO_ACCEPT_FAILED";
+    LazyAgentErrorCode["AGENT_CREATION_FAILED"] = "LAZY_AGENT_AGENT_CREATION_FAILED";
+})(LazyAgentErrorCode || (LazyAgentErrorCode = {}));
+/**
+ * Lazy agent wrapper.
+ *
+ * Proxies all Agent methods and initializes on first call.
+ * Caches the initialized agent for subsequent calls.
+ */
+export class LazyAgent {
+    config;
+    agent = null;
+    initPromise = null;
+    lastError = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Get the agent's DID.
+     *
+     * Triggers initialization if not already initialized.
+     * Throws if initialization fails.
+     */
+    get did() {
+        if (!this.agent) {
+            throw new Error('Agent not initialized. Call send/receive first or await ensureInitialized().');
+        }
+        return this.agent.did;
+    }
+    /**
+     * Check if agent is ready (initialized).
+     */
+    isReady() {
+        return this.agent !== null;
+    }
+    /**
+     * Get last initialization error (if any).
+     */
+    getLastError() {
+        return this.lastError;
+    }
+    /**
+     * Ensure agent is initialized.
+     *
+     * Can be called explicitly to trigger init before first send/receive.
+     * Safe to call multiple times — subsequent calls return cached agent.
+     *
+     * @returns Agent instance or error
+     */
+    async ensureInitialized() {
+        // If already initialized, return cached agent
+        if (this.agent) {
+            return ok(this.agent);
+        }
+        // If initialization is in progress, wait for it
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+        // Start initialization
+        this.initPromise = this.initialize();
+        const result = await this.initPromise;
+        // Clear promise after completion (success or failure)
+        this.initPromise = null;
+        if (result.ok) {
+            this.agent = result.value;
+            this.lastError = null;
+        }
+        else {
+            this.lastError = {
+                code: LazyAgentErrorCode.INIT_FAILED,
+                message: `Agent initialization failed: ${result.error}`,
+                cause: result.error,
+            };
+        }
+        return result;
+    }
+    /**
+     * Internal initialization logic.
+     *
+     * 1. Auto-accept invite (if XBIND_INVITE_CODE set)
+     * 2. Create agent identity
+     * 3. Configure registry and transport
+     * 4. Return initialized agent
+     */
+    async initialize() {
+        // Step 1: Attempt auto-accept if invite code is available
+        const inviteCode = this.config.inviteCode ?? this.getEnv('XBIND_INVITE_CODE');
+        let registry = this.config.registry;
+        let transport = this.config.transport;
+        const endpoint = this.config.endpoint ?? this.getEnv('XBIND_ENDPOINT') ?? '';
+        if (inviteCode) {
+            // Create temporary agent to get DID and public key for invite acceptance
+            const tempAgentResult = await Agent.create({
+                name: this.config.name,
+                registry: new MemoryTrustRegistry(),
+                transport: new HttpsTransportAdapter({ baseUrl: 'http://localhost' }), // Placeholder
+                postQuantumSig: this.config.postQuantumSig,
+                xchange: this.config.xchange,
+            });
+            if (!tempAgentResult.ok) {
+                return err(tempAgentResult.error);
+            }
+            const tempAgent = tempAgentResult.value;
+            // Export public key for invite acceptance
+            const seedsResult = await tempAgent.exportSeeds();
+            if (!seedsResult.ok) {
+                return err('IDENTITY_FAILED');
+            }
+            const publicKey = toBase64(tempAgent.identity.rawPublicKey);
+            const x25519PublicKey = tempAgent.identity.rawX25519PublicKey
+                ? toBase64(tempAgent.identity.rawX25519PublicKey)
+                : undefined;
+            // Auto-accept invite
+            const acceptResult = await autoAcceptInvite({
+                inviteCode,
+                enabled: true,
+                registry: this.config.autoAccept?.registry,
+                inviteApiUrl: this.config.autoAccept?.inviteApiUrl,
+            }, {
+                name: this.config.name,
+                did: tempAgent.did,
+                endpoint,
+                publicKey,
+                x25519PublicKey,
+            });
+            if (!acceptResult.ok) {
+                this.lastError = {
+                    code: LazyAgentErrorCode.AUTO_ACCEPT_FAILED,
+                    message: acceptResult.error.message,
+                    hint: acceptResult.error.hint,
+                    cause: acceptResult.error,
+                };
+                // Non-fatal: continue with temp agent even if auto-accept fails
+                // (registry may already be configured)
+            }
+            else {
+                // Use auto-configured registry if not provided
+                if (!registry && acceptResult.value.registryAutoconfigured) {
+                    // Registry was already configured by autoAcceptInvite
+                    registry = this.config.autoAccept?.registry ?? new MemoryTrustRegistry();
+                }
+                // Use inviter's endpoint as default transport if not provided
+                if (!transport) {
+                    transport = new HttpsTransportAdapter({
+                        baseUrl: acceptResult.value.from.endpoint,
+                    });
+                }
+            }
+            // Return temp agent as initialized agent
+            this.agent = tempAgent;
+            return ok(tempAgent);
+        }
+        // Step 2: No invite code — create agent normally
+        const defaultRegistry = registry ?? new MemoryTrustRegistry();
+        const defaultTransport = transport ?? new HttpsTransportAdapter({
+            baseUrl: endpoint || 'http://localhost',
+        });
+        const agentResult = await Agent.create({
+            name: this.config.name,
+            registry: defaultRegistry,
+            transport: defaultTransport,
+            postQuantumSig: this.config.postQuantumSig,
+            xchange: this.config.xchange,
+        });
+        if (!agentResult.ok) {
+            this.lastError = {
+                code: LazyAgentErrorCode.AGENT_CREATION_FAILED,
+                message: `Agent creation failed: ${agentResult.error}`,
+                cause: agentResult.error,
+            };
+            return agentResult;
+        }
+        this.agent = agentResult.value;
+        return ok(this.agent);
+    }
+    /**
+     * Send a message (proxied to underlying agent).
+     *
+     * Automatically initializes agent on first call.
+     */
+    async send(opts) {
+        const agentResult = await this.ensureInitialized();
+        if (!agentResult.ok) {
+            return agentResult;
+        }
+        return agentResult.value.send(opts);
+    }
+    /**
+     * Receive a message (proxied to underlying agent).
+     *
+     * Automatically initializes agent on first call.
+     */
+    async receive(envelope, opts) {
+        const agentResult = await this.ensureInitialized();
+        if (!agentResult.ok) {
+            return err(agentResult.error);
+        }
+        return agentResult.value.receive(envelope, opts);
+    }
+    /**
+     * Receive a split-channel share (proxied to underlying agent).
+     *
+     * Automatically initializes agent on first call.
+     */
+    async receiveSplitShare(envelope) {
+        const agentResult = await this.ensureInitialized();
+        if (!agentResult.ok) {
+            return err(agentResult.error);
+        }
+        return agentResult.value.receiveSplitShare(envelope);
+    }
+    /**
+     * Get environment variable value.
+     *
+     * @param key - Environment variable name
+     * @returns Environment variable value or empty string
+     */
+    getEnv(key) {
+        // SAFETY: Check for Node.js environment before accessing process
+        if (typeof process !== 'undefined' && typeof process.env !== 'undefined') {
+            return process.env[key] ?? '';
+        }
+        return '';
+    }
+    /**
+     * Export the underlying agent (for advanced use cases).
+     *
+     * Throws if agent is not initialized.
+     */
+    getAgent() {
+        if (!this.agent) {
+            throw new Error('Agent not initialized. Call send/receive first or await ensureInitialized().');
+        }
+        return this.agent;
+    }
+}
+/**
+ * Create a lazy agent that initializes on first use.
+ *
+ * Extension method for Agent class. Adds `Agent.lazy()` factory.
+ *
+ * @param config - Lazy agent configuration
+ * @returns Lazy agent wrapper
+ *
+ * @example
+ * ```ts
+ * // Environment: XBIND_INVITE_CODE=XBD-abc123
+ *
+ * const agent = createLazyAgent({ name: 'my-service' });
+ *
+ * // No initialization yet — happens on first send:
+ * await agent.send({
+ *   to: 'did:key:z6Mk...',
+ *   payload: { action: 'test' },
+ *   scope: 'test',
+ * });
+ * ```
+ */
+export function createLazyAgent(config) {
+    return new LazyAgent(config);
+}