@private.me/xbind 1.2.0

package/dist-standalone/cjs/lazy-init.js

@@ -0,0 +1,300 @@
+"use strict";
+/**
+ * @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' });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LazyAgent = exports.LazyAgentErrorCode = void 0;
+exports.createLazyAgent = createLazyAgent;
+const shared_1 = require("../_deps/shared/index.js");
+const agent_js_1 = require("./agent.js");
+const auto_accept_js_1 = require("./auto-accept.js");
+const trust_registry_js_1 = require("./trust-registry.js");
+const transport_js_1 = require("./transport.js");
+const crypto_1 = require("../_deps/crypto/index.js");
+/**
+ * Lazy agent error codes.
+ */
+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 || (exports.LazyAgentErrorCode = LazyAgentErrorCode = {}));
+/**
+ * Lazy agent wrapper.
+ *
+ * Proxies all Agent methods and initializes on first call.
+ * Caches the initialized agent for subsequent calls.
+ */
+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 (0, shared_1.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_js_1.Agent.create({
+                name: this.config.name,
+                registry: new trust_registry_js_1.MemoryTrustRegistry(),
+                transport: new transport_js_1.HttpsTransportAdapter({ baseUrl: 'http://localhost' }), // Placeholder
+                postQuantumSig: this.config.postQuantumSig,
+                xchange: this.config.xchange,
+            });
+            if (!tempAgentResult.ok) {
+                return (0, shared_1.err)(tempAgentResult.error);
+            }
+            const tempAgent = tempAgentResult.value;
+            // Export public key for invite acceptance
+            const seedsResult = await tempAgent.exportSeeds();
+            if (!seedsResult.ok) {
+                return (0, shared_1.err)('IDENTITY_FAILED');
+            }
+            const publicKey = (0, crypto_1.toBase64)(tempAgent.identity.rawPublicKey);
+            const x25519PublicKey = tempAgent.identity.rawX25519PublicKey
+                ? (0, crypto_1.toBase64)(tempAgent.identity.rawX25519PublicKey)
+                : undefined;
+            // Auto-accept invite
+            const acceptResult = await (0, auto_accept_js_1.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 trust_registry_js_1.MemoryTrustRegistry();
+                }
+                // Use inviter's endpoint as default transport if not provided
+                if (!transport) {
+                    transport = new transport_js_1.HttpsTransportAdapter({
+                        baseUrl: acceptResult.value.from.endpoint,
+                    });
+                }
+            }
+            // Return temp agent as initialized agent
+            this.agent = tempAgent;
+            return (0, shared_1.ok)(tempAgent);
+        }
+        // Step 2: No invite code — create agent normally
+        const defaultRegistry = registry ?? new trust_registry_js_1.MemoryTrustRegistry();
+        const defaultTransport = transport ?? new transport_js_1.HttpsTransportAdapter({
+            baseUrl: endpoint || 'http://localhost',
+        });
+        const agentResult = await agent_js_1.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 (0, shared_1.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 (0, shared_1.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 (0, shared_1.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;
+    }
+}
+exports.LazyAgent = LazyAgent;
+/**
+ * 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',
+ * });
+ * ```
+ */
+function createLazyAgent(config) {
+    return new LazyAgent(config);
+}

package/dist-standalone/cjs/mdns-discovery.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * @module mdns-discovery
+ * mDNS service discovery for local network device pairing.
+ *
+ * Service Type: _privateme._tcp.local (RFC 6763 compliant)
+ * Port: 58472 (dynamic range 58000-58999)
+ * TXT Record: did=z6Mk..., endpoint=http://192.168.1.5:58472, name=Desktop
+ *
+ * Security properties:
+ * - Physical proximity required (same LAN)
+ * - User confirmation on both devices
+ * - Nonce-based challenge-response
+ * - 60-second timeout
+ * - Gold Standard compliant (GS-CONNECT requirement #26)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MdnsDiscoveryManager = exports.DiscoveryErrorCode = void 0;
+const bonjour_service_1 = __importDefault(require("bonjour-service"));
+const shared_1 = require("../_deps/shared/index.js");
+/**
+ * Discovery error types.
+ */
+var DiscoveryErrorCode;
+(function (DiscoveryErrorCode) {
+    DiscoveryErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    DiscoveryErrorCode["TIMEOUT"] = "TIMEOUT";
+    DiscoveryErrorCode["NO_SERVICES"] = "NO_SERVICES";
+    DiscoveryErrorCode["INVALID_SERVICE"] = "INVALID_SERVICE";
+})(DiscoveryErrorCode || (exports.DiscoveryErrorCode = DiscoveryErrorCode = {}));
+/**
+ * mDNS discovery manager.
+ *
+ * Advertises service on local network and scans for other devices.
+ * Uses bonjour-service library (RFC 6763/6762 compliant).
+ */
+class MdnsDiscoveryManager {
+    bonjour;
+    service = null;
+    serviceType = 'privateme';
+    protocol = 'tcp';
+    port = 58472;
+    constructor() {
+        this.bonjour = new bonjour_service_1.default();
+    }
+    /**
+     * Advertise service on local network.
+     *
+     * Broadcasts mDNS announcement with device DID and HTTP endpoint.
+     * Other devices on the same LAN can discover this service via scan().
+     *
+     * @param name - Device name (e.g., "Desktop", "MacBook Pro")
+     * @param did - Device DID
+     * @param port - Local HTTP server port (default: 58472)
+     *
+     * @example
+     * ```typescript
+     * const manager = new MdnsDiscoveryManager();
+     * manager.advertise('Desktop', 'did:key:z6Mk...', 58472);
+     * // Service now visible to other devices on LAN
+     * ```
+     */
+    advertise(name, did, port = this.port) {
+        // Stop existing advertisement
+        if (this.service) {
+            this.service.stop?.();
+        }
+        // Publish service
+        this.service = this.bonjour.publish({
+            name,
+            type: this.serviceType,
+            protocol: this.protocol,
+            port,
+            txt: {
+                did,
+                endpoint: `http://localhost:${port}`, // Will be replaced with actual IP by Bonjour
+                name,
+            },
+        });
+    }
+    /**
+     * Scan local network for services.
+     *
+     * Discovers all Private.Me devices on the same LAN.
+     * Filters out own DID from results (can't pair with self).
+     *
+     * @param ownDid - Own device DID (to filter out)
+     * @param timeoutMs - Scan timeout in milliseconds (default: 5000ms)
+     * @returns Array of discovered services
+     *
+     * @example
+     * ```typescript
+     * const manager = new MdnsDiscoveryManager();
+     * const result = await manager.scan('did:key:z6Mk...myDid', 5000);
+     * if (result.ok) {
+     *   console.log(`Found ${result.value.length} devices`);
+     *   for (const service of result.value) {
+     *     console.log(`${service.name} - ${service.did}`);
+     *   }
+     * }
+     * ```
+     */
+    async scan(ownDid, timeoutMs = 5000) {
+        return new Promise((resolve) => {
+            const discovered = new Map();
+            let resolved = false;
+            // Browse for services
+            const browser = this.bonjour.find({
+                type: this.serviceType,
+                protocol: this.protocol,
+            });
+            // Handle service discovery
+            browser.on('up', (service) => {
+                try {
+                    // Parse TXT record
+                    const txt = service.txt;
+                    if (!txt || !txt.did || !txt.name) {
+                        return; // Invalid service - missing required fields
+                    }
+                    // Filter out own DID
+                    if (txt.did === ownDid) {
+                        return;
+                    }
+                    // Extract endpoint
+                    const endpoint = txt.endpoint || `http://${service.host || 'localhost'}:${service.port}`;
+                    // Extract addresses (filter IPv4 only)
+                    const addresses = (service.addresses || []).filter((addr) => {
+                        // Simple IPv4 check (contains dots, not colons)
+                        return addr.includes('.') && !addr.includes(':');
+                    });
+                    const info = {
+                        name: txt.name,
+                        did: txt.did,
+                        endpoint,
+                        addresses,
+                        port: service.port || this.port,
+                    };
+                    discovered.set(txt.did, info);
+                }
+                catch (error) {
+                    // Ignore invalid service
+                }
+            });
+            // Timeout after specified duration
+            const timeoutId = setTimeout(() => {
+                if (resolved)
+                    return;
+                resolved = true;
+                browser.stop();
+                if (discovered.size === 0) {
+                    resolve((0, shared_1.err)({
+                        code: DiscoveryErrorCode.NO_SERVICES,
+                        message: 'No devices found on local network',
+                        hint: 'Ensure both devices are on the same Wi-Fi network',
+                    }));
+                }
+                else {
+                    resolve((0, shared_1.ok)(Array.from(discovered.values())));
+                }
+            }, timeoutMs);
+            // Allow cleanup if promise resolves early
+            browser.on('error', (error) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                clearTimeout(timeoutId);
+                browser.stop();
+                resolve((0, shared_1.err)({
+                    code: DiscoveryErrorCode.NETWORK_ERROR,
+                    message: error.message,
+                    hint: 'Check firewall settings and network connectivity',
+                }));
+            });
+        });
+    }
+    /**
+     * Stop advertising service.
+     *
+     * Removes mDNS announcement from local network.
+     * Other devices will no longer see this service.
+     */
+    stopAdvertising() {
+        if (this.service) {
+            this.service.stop?.();
+            this.service = null;
+        }
+    }
+    /**
+     * Release resources.
+     *
+     * Stops advertising and cleans up Bonjour instance.
+     * Call this when shutting down the application.
+     */
+    destroy() {
+        this.stopAdvertising();
+        this.bonjour.destroy();
+    }
+}
+exports.MdnsDiscoveryManager = MdnsDiscoveryManager;

package/dist-standalone/cjs/nonce-store.js

@@ -0,0 +1,66 @@
+"use strict";
+/* ── NonceStore — Replay Prevention ── */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryNonceStore = void 0;
+/** Default TTL for nonce entries: 10 minutes. */
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+/** Default cleanup interval: 60 seconds. */
+const DEFAULT_CLEANUP_INTERVAL_MS = 60 * 1000;
+/**
+ * In-memory nonce store for development and single-process deployments.
+ *
+ * Stores nonces in a Map keyed by "senderDid:nonce" with expiry timestamps.
+ * Periodic cleanup removes expired entries to prevent unbounded growth.
+ */
+class MemoryNonceStore {
+    seen = new Map();
+    ttlMs;
+    cleanupIntervalMs;
+    timer = null;
+    constructor(opts) {
+        this.ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
+        this.cleanupIntervalMs = opts?.cleanupIntervalMs ?? DEFAULT_CLEANUP_INTERVAL_MS;
+        // Timer starts lazily on first check() to avoid blocking process exit in tests
+    }
+    /** Start cleanup timer on first use. */
+    ensureTimer() {
+        if (this.timer !== null)
+            return;
+        const t = setInterval(() => this.cleanup(), this.cleanupIntervalMs);
+        // Unref so the timer doesn't block Node.js process exit
+        if (typeof t === 'object' && 'unref' in t) {
+            t.unref(); // SAFETY: runtime check guards access
+        }
+        this.timer = t;
+    }
+    async check(nonce, senderDid) {
+        this.ensureTimer();
+        const key = `${senderDid}:${nonce}`;
+        const existing = this.seen.get(key);
+        const now = Date.now();
+        if (existing !== undefined && existing > now) {
+            return false;
+        }
+        this.seen.set(key, now + this.ttlMs);
+        return true;
+    }
+    cleanup() {
+        const now = Date.now();
+        for (const [key, expiry] of this.seen) {
+            if (expiry <= now)
+                this.seen.delete(key);
+        }
+    }
+    dispose() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.seen.clear();
+    }
+    /** Number of active (non-expired) entries. Useful for testing. */
+    get size() {
+        return this.seen.size;
+    }
+}
+exports.MemoryNonceStore = MemoryNonceStore;

package/dist-standalone/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}