@private.me/xbind 1.2.0

package/dist-standalone/mdns-discovery.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @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)
+ */
+import { Result } from '@private.me/shared';
+/**
+ * mDNS service information.
+ */
+export interface MdnsServiceInfo {
+    /** Service name (e.g., "Desktop", "MacBook Pro") */
+    readonly name: string;
+    /** Device DID */
+    readonly did: string;
+    /** HTTP endpoint (e.g., "http://192.168.1.5:58472") */
+    readonly endpoint: string;
+    /** IPv4 addresses */
+    readonly addresses: readonly string[];
+    /** Port number */
+    readonly port: number;
+}
+/**
+ * Discovery error types.
+ */
+export declare enum DiscoveryErrorCode {
+    NETWORK_ERROR = "NETWORK_ERROR",
+    TIMEOUT = "TIMEOUT",
+    NO_SERVICES = "NO_SERVICES",
+    INVALID_SERVICE = "INVALID_SERVICE"
+}
+/**
+ * Discovery error.
+ */
+export interface DiscoveryError {
+    readonly code: DiscoveryErrorCode;
+    readonly message: string;
+    readonly hint?: string;
+}
+/**
+ * mDNS discovery manager.
+ *
+ * Advertises service on local network and scans for other devices.
+ * Uses bonjour-service library (RFC 6763/6762 compliant).
+ */
+export declare class MdnsDiscoveryManager {
+    private readonly bonjour;
+    private service;
+    private readonly serviceType;
+    private readonly protocol;
+    private readonly port;
+    constructor();
+    /**
+     * 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: string, did: string, port?: number): void;
+    /**
+     * 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}`);
+     *   }
+     * }
+     * ```
+     */
+    scan(ownDid: string, timeoutMs?: number): Promise<Result<MdnsServiceInfo[], DiscoveryError>>;
+    /**
+     * Stop advertising service.
+     *
+     * Removes mDNS announcement from local network.
+     * Other devices will no longer see this service.
+     */
+    stopAdvertising(): void;
+    /**
+     * Release resources.
+     *
+     * Stops advertising and cleans up Bonjour instance.
+     * Call this when shutting down the application.
+     */
+    destroy(): void;
+}

package/dist-standalone/mdns-discovery.js

@@ -0,0 +1,195 @@
+/**
+ * @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)
+ */
+import Bonjour from 'bonjour-service';
+import { ok, err } from"./_deps/shared/index.js";
+/**
+ * Discovery error types.
+ */
+export var DiscoveryErrorCode;
+(function (DiscoveryErrorCode) {
+    DiscoveryErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    DiscoveryErrorCode["TIMEOUT"] = "TIMEOUT";
+    DiscoveryErrorCode["NO_SERVICES"] = "NO_SERVICES";
+    DiscoveryErrorCode["INVALID_SERVICE"] = "INVALID_SERVICE";
+})(DiscoveryErrorCode || (DiscoveryErrorCode = {}));
+/**
+ * mDNS discovery manager.
+ *
+ * Advertises service on local network and scans for other devices.
+ * Uses bonjour-service library (RFC 6763/6762 compliant).
+ */
+export class MdnsDiscoveryManager {
+    bonjour;
+    service = null;
+    serviceType = 'privateme';
+    protocol = 'tcp';
+    port = 58472;
+    constructor() {
+        this.bonjour = new Bonjour();
+    }
+    /**
+     * 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(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(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(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();
+    }
+}

package/dist-standalone/nonce-store.d.ts

@@ -0,0 +1,39 @@
+/** Interface for nonce stores that prevent replay attacks. */
+export interface NonceStore {
+    /**
+     * Check if a nonce is fresh and record it atomically.
+     * @returns true if nonce is new (accepted), false if duplicate (rejected).
+     */
+    check(nonce: string, senderDid: string): Promise<boolean>;
+    /** Remove expired entries. Called automatically on interval. */
+    cleanup(): void;
+    /** Shut down the store and clear any timers. */
+    dispose(): void;
+}
+/** Options for MemoryNonceStore. */
+export interface MemoryNonceStoreOptions {
+    /** TTL in milliseconds for nonce entries. Default: 10 minutes. */
+    readonly ttlMs?: number;
+    /** Cleanup interval in milliseconds. Default: 60 seconds. */
+    readonly cleanupIntervalMs?: number;
+}
+/**
+ * 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.
+ */
+export declare class MemoryNonceStore implements NonceStore {
+    private readonly seen;
+    private readonly ttlMs;
+    private readonly cleanupIntervalMs;
+    private timer;
+    constructor(opts?: MemoryNonceStoreOptions);
+    /** Start cleanup timer on first use. */
+    private ensureTimer;
+    check(nonce: string, senderDid: string): Promise<boolean>;
+    cleanup(): void;
+    dispose(): void;
+    /** Number of active (non-expired) entries. Useful for testing. */
+    get size(): number;
+}

package/dist-standalone/nonce-store.js

@@ -0,0 +1,62 @@
+/* ── NonceStore — Replay Prevention ── */
+/** 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.
+ */
+export 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;
+    }
+}

package/dist-standalone/package.json

@@ -0,0 +1,11 @@
+{
+  "type": "module",
+  "imports": {
+    "@private.me/shared": "./_deps/shared/index.js",
+    "@private.me/crypto": "./_deps/crypto/index.js",
+    "@private.me/xchange": "./_deps/xchange/index.js",
+    "@private.me/ux-helpers": "./_deps/ux-helpers/index.js",
+    "@private.me/xregistry": "./_deps/xregistry/index.js",
+    "mldsa-wasm": "./_deps/mldsa-wasm/dist/mldsa.js"
+  }
+}

package/dist-standalone/pairing-manager.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @module pairing-manager
+ * Security validation for peer-to-peer device pairing via mDNS.
+ *
+ * Security properties:
+ * - 16-byte cryptographically secure nonce (prevents replay attacks)
+ * - 60-second timeout (limits attack window)
+ * - User confirmation required on BOTH devices
+ * - Nonce echo in response (prevents MITM substitution)
+ * - Trust registry integration (stores paired DIDs with scopes)
+ * - Gold Standard compliant (GS-CONNECT requirement #26, GS-SEC-RNG compliant)
+ */
+import { Result } from '@private.me/shared';
+import type { TrustRegistry } from './trust-registry';
+/**
+ * Pairing request (Device A → Device B).
+ */
+export interface PairingRequest {
+    /** DID of initiating device (Device A) */
+    readonly device_a_did: string;
+    /** Cryptographically secure nonce (16 bytes, hex-encoded) */
+    readonly nonce: string;
+    /** Request timestamp (milliseconds since epoch) */
+    readonly timestamp: number;
+}
+/**
+ * Pairing response (Device B → Device A).
+ */
+export interface PairingResponse {
+    /** DID of responding device (Device B) */
+    readonly device_b_did: string;
+    /** Whether pairing was accepted */
+    readonly accepted: boolean;
+    /** Echo of nonce from request (prevents MITM) */
+    readonly nonce: string;
+}
+/**
+ * Pairing manager for secure peer-to-peer device pairing.
+ *
+ * Implements challenge-response protocol with user confirmation.
+ * Integrates with trust registry for persistent pairing storage.
+ */
+export declare class PairingManager {
+    private readonly pendingNonces;
+    private readonly registry;
+    private readonly deviceDid;
+    /**
+     * Create pairing manager.
+     *
+     * @param deviceDid - DID of this device
+     * @param registry - Trust registry instance
+     */
+    constructor(deviceDid: string, registry: TrustRegistry);
+    /**
+     * Create pairing request.
+     *
+     * Generates cryptographically secure nonce and stores it for validation.
+     * Device A calls this before sending request to Device B.
+     *
+     * @returns Pairing request to send to remote device
+     *
+     * @example
+     * ```typescript
+     * const manager = new PairingManager('did:key:z6MkA...', registry);
+     * const request = manager.createRequest();
+     * // Send request to Device B via HTTP POST
+     * const response = await fetch(`${deviceB.endpoint}/pair`, {
+     *   method: 'POST',
+     *   body: JSON.stringify(request),
+     * });
+     * ```
+     */
+    createRequest(): PairingRequest;
+    /**
+     * Validate pairing request.
+     *
+     * Checks timeout and nonce uniqueness.
+     * Device B calls this when receiving request from Device A.
+     *
+     * @param request - Pairing request from remote device
+     * @returns Ok if valid, Err with reason if invalid
+     *
+     * @example
+     * ```typescript
+     * // Device B receives request
+     * const validation = manager.validateRequest(request);
+     * if (!validation.ok) {
+     *   return res.status(400).json({ error: validation.error });
+     * }
+     * ```
+     */
+    validateRequest(request: PairingRequest): Result<void, string>;
+    /**
+     * Accept pairing request.
+     *
+     * Shows UI prompt for user confirmation, then stores in trust registry.
+     * Device B calls this after validating request.
+     *
+     * @param request - Validated pairing request
+     * @param promptCallback - Async function to show UI prompt (returns true if accepted)
+     * @returns Pairing response to send back to Device A
+     *
+     * @example
+     * ```typescript
+     * const response = await manager.acceptPairing(request, async () => {
+     *   // Show modal: "Device {name} wants to pair. Accept?"
+     *   return await showConfirmationDialog({
+     *     title: 'Pair with Device?',
+     *     message: `DID: ${request.device_a_did.slice(0, 20)}...`,
+     *   });
+     * });
+     *
+     * if (response.ok && response.value.accepted) {
+     *   // Send response back to Device A
+     * }
+     * ```
+     */
+    acceptPairing(request: PairingRequest, promptCallback: () => Promise<boolean>): Promise<Result<PairingResponse, string>>;
+    /**
+     * Finalize pairing.
+     *
+     * Verifies response nonce and stores remote DID in trust registry.
+     * Device A calls this after receiving response from Device B.
+     *
+     * @param response - Pairing response from Device B
+     * @param expectedNonce - Nonce from original request (for verification)
+     * @returns Ok if successful, Err if nonce mismatch or storage failed
+     *
+     * @example
+     * ```typescript
+     * const request = manager.createRequest();
+     * const response = await sendPairingRequest(deviceB.endpoint, request);
+     *
+     * const result = await manager.finalizePairing(response, request.nonce);
+     * if (result.ok) {
+     *   console.log('Pairing successful!');
+     * } else {
+     *   console.error('Pairing failed:', result.error);
+     * }
+     * ```
+     */
+    finalizePairing(response: PairingResponse, expectedNonce: string): Promise<Result<void, string>>;
+    /**
+     * Get pending nonce count (for debugging/monitoring).
+     */
+    getPendingNonceCount(): number;
+}