@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/mdns-discovery.js

@@ -1 +1,195 @@
-import Bonjour from"bonjour-service";import{ok,err}from"./_deps/shared/index.js";export var DiscoveryErrorCode;!function(e){e.NETWORK_ERROR="NETWORK_ERROR",e.TIMEOUT="TIMEOUT",e.NO_SERVICES="NO_SERVICES",e.INVALID_SERVICE="INVALID_SERVICE"}(DiscoveryErrorCode||(DiscoveryErrorCode={}));export class MdnsDiscoveryManager{bonjour;service=null;serviceType="privateme";protocol="tcp";port=58472;constructor(){this.bonjour=new Bonjour}advertise(e,o,r=this.port){this.service&&this.service.stop?.(),this.service=this.bonjour.publish({name:e,type:this.serviceType,protocol:this.protocol,port:r,txt:{did:o,endpoint:`http://localhost:${r}`,name:e}})}async scan(e,o=5e3){return new Promise(r=>{const t=new Map;let s=!1;const i=this.bonjour.find({type:this.serviceType,protocol:this.protocol});i.on("up",o=>{try{const r=o.txt;if(!r||!r.did||!r.name)return;if(r.did===e)return;const s=r.endpoint||`http://${o.host||"localhost"}:${o.port}`,i=(o.addresses||[]).filter(e=>e.includes(".")&&!e.includes(":")),n={name:r.name,did:r.did,endpoint:s,addresses:i,port:o.port||this.port};t.set(r.did,n)}catch(e){}});const n=setTimeout(()=>{s||(s=!0,i.stop(),0===t.size?r(err({code:DiscoveryErrorCode.NO_SERVICES,message:"No devices found on local network",hint:"Ensure both devices are on the same Wi-Fi network"})):r(ok(Array.from(t.values()))))},o);i.on("error",e=>{s||(s=!0,clearTimeout(n),i.stop(),r(err({code:DiscoveryErrorCode.NETWORK_ERROR,message:e.message,hint:"Check firewall settings and network connectivity"})))})})}stopAdvertising(){this.service&&(this.service.stop?.(),this.service=null)}destroy(){this.stopAdvertising(),this.bonjour.destroy()}}
+/**
+ * @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.js

@@ -1 +1,76 @@
-const DEFAULT_TTL_MS=6e5,DEFAULT_CLEANUP_INTERVAL_MS=6e4;export class MemoryNonceStore{seen=new Map;ttlMs;cleanupIntervalMs;timer=null;constructor(e){this.ttlMs=e?.ttlMs??6e5,this.cleanupIntervalMs=e?.cleanupIntervalMs??6e4}ensureTimer(){if(null!==this.timer)return;const e=setInterval(()=>this.cleanup(),this.cleanupIntervalMs);"object"==typeof e&&"unref"in e&&e.unref(),this.timer=e}buildKey(e,t,s){if(null==s)return`${t}:${e}`;return`${t}:${e}:${"string"==typeof s.shareGroupId?s.shareGroupId:""}:${"number"==typeof s.shareIndex?String(s.shareIndex):""}`}async check(e,t,s){this.ensureTimer();const n=this.buildKey(e,t,s),r=this.seen.get(n),i=Date.now();return!(void 0!==r&&r>i)&&(this.seen.set(n,i+this.ttlMs),!0)}cleanup(){const e=Date.now(),t=Array.from(this.seen.keys());for(const s of t){const t=this.seen.get(s);void 0!==t&&t<=e&&this.seen.delete(s)}}dispose(){null!==this.timer&&(clearInterval(this.timer),this.timer=null),this.seen.clear()}get size(){return this.seen.size}}
+/* ── 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:shareContext" with expiry timestamps.
+ * Supports share-aware deduplication: same nonce + different shares = allowed (idempotent retry),
+ * same nonce + same share = blocked (true replay).
+ * 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;
+    }
+    /** Build composite key: senderDid:nonce:shareGroupId:shareIndex */
+    buildKey(nonce, senderDid, shareContext) {
+        if (shareContext === undefined || shareContext === null) {
+            return `${senderDid}:${nonce}`;
+        }
+        const groupId = typeof shareContext.shareGroupId === 'string' ? shareContext.shareGroupId : '';
+        const index = typeof shareContext.shareIndex === 'number' ? String(shareContext.shareIndex) : '';
+        return `${senderDid}:${nonce}:${groupId}:${index}`;
+    }
+    async check(nonce, senderDid, shareContext) {
+        this.ensureTimer();
+        const key = this.buildKey(nonce, senderDid, shareContext);
+        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();
+        const keys = Array.from(this.seen.keys());
+        for (const key of keys) {
+            const expiry = this.seen.get(key);
+            if (expiry !== undefined && 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/pairing-manager.js

@@ -1 +1,219 @@
-import{ok,err}from"./_deps/shared/index.js";export class PairingManager{pendingNonces=new Map;registry;deviceDid;constructor(e,r){this.deviceDid=e,this.registry=r,setInterval(()=>{const e=Date.now();for(const[r,i]of this.pendingNonces.entries())e-i>6e4&&this.pendingNonces.delete(r)},1e4)}createRequest(){const e=new Uint8Array(16);if(void 0!==globalThis.crypto&&globalThis.crypto.getRandomValues)globalThis.crypto.getRandomValues(e);else{require("node:crypto").getRandomValues(e)}const r=Array.from(e).map(e=>e.toString(16).padStart(2,"0")).join(""),i=Date.now();return this.pendingNonces.set(r,i),{device_a_did:this.deviceDid,nonce:r,timestamp:i}}validateRequest(e){const r=Date.now()-e.timestamp;return r>6e4?err(`Request expired (${Math.floor(r/1e3)}s old, max 60s)`):r<0?err("Request timestamp in the future (clock skew detected)"):e.device_a_did&&e.nonce&&e.timestamp?ok(void 0):err("Missing required fields (device_a_did, nonce, timestamp)")}async acceptPairing(e,r){const i=this.validateRequest(e);if(!i.ok)return err(i.error);const t=await r();if(t){const r=await this.registry.register(e.device_a_did,new Uint8Array(32),"Paired Device",["pairing"]);if(!r.ok){const e="string"==typeof r.error?r.error:"Unknown error";return err(`Failed to register pairing: ${e}`)}}return ok({device_b_did:this.deviceDid,accepted:t,nonce:e.nonce})}async finalizePairing(e,r){if(e.nonce!==r)return err("Nonce mismatch (possible MITM attack)");if(!e.accepted)return err("Pairing rejected by remote device");this.pendingNonces.delete(r);const i=await this.registry.register(e.device_b_did,new Uint8Array(32),"Paired Device",["pairing"]);if(!i.ok){const e="string"==typeof i.error?i.error:"Unknown error";return err(`Failed to register pairing: ${e}`)}return ok(void 0)}getPendingNonceCount(){return this.pendingNonces.size}}
+/**
+ * @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 { ok, err } from"./_deps/shared/index.js";
+/**
+ * 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 class PairingManager {
+    pendingNonces = new Map(); // nonce → timestamp
+    registry;
+    deviceDid;
+    /**
+     * Create pairing manager.
+     *
+     * @param deviceDid - DID of this device
+     * @param registry - Trust registry instance
+     */
+    constructor(deviceDid, registry) {
+        this.deviceDid = deviceDid;
+        this.registry = registry;
+        // Clean up expired nonces every 10 seconds
+        setInterval(() => {
+            const now = Date.now();
+            for (const [nonce, timestamp] of this.pendingNonces.entries()) {
+                if (now - timestamp > 60_000) {
+                    this.pendingNonces.delete(nonce);
+                }
+            }
+        }, 10_000);
+    }
+    /**
+     * 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() {
+        // Generate cryptographically secure nonce (GS-SEC-RNG: NEVER use Math.random)
+        const nonceBytes = new Uint8Array(16);
+        if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.getRandomValues) {
+            globalThis.crypto.getRandomValues(nonceBytes);
+        }
+        else {
+            // Node.js environment
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const crypto = require('node:crypto');
+            crypto.getRandomValues(nonceBytes);
+        }
+        const nonce = Array.from(nonceBytes)
+            .map((b) => b.toString(16).padStart(2, '0'))
+            .join('');
+        const timestamp = Date.now();
+        // Store nonce for validation (60-second TTL)
+        this.pendingNonces.set(nonce, timestamp);
+        return {
+            device_a_did: this.deviceDid,
+            nonce,
+            timestamp,
+        };
+    }
+    /**
+     * 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) {
+        // Check timeout (60-second window)
+        const age = Date.now() - request.timestamp;
+        if (age > 60_000) {
+            return err(`Request expired (${Math.floor(age / 1000)}s old, max 60s)`);
+        }
+        if (age < 0) {
+            return err('Request timestamp in the future (clock skew detected)');
+        }
+        // Check required fields
+        if (!request.device_a_did || !request.nonce || !request.timestamp) {
+            return err('Missing required fields (device_a_did, nonce, timestamp)');
+        }
+        return ok(undefined);
+    }
+    /**
+     * 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
+     * }
+     * ```
+     */
+    async acceptPairing(request, promptCallback) {
+        // Validate request first
+        const validation = this.validateRequest(request);
+        if (!validation.ok) {
+            return err(validation.error);
+        }
+        // Prompt user for confirmation
+        const accepted = await promptCallback();
+        if (accepted) {
+            // Store in trust registry (Device A → Device B)
+            const registerResult = await this.registry.register(request.device_a_did, new Uint8Array(32), 'Paired Device', ['pairing']);
+            if (!registerResult.ok) {
+                const errorMsg = typeof registerResult.error === 'string'
+                    ? registerResult.error
+                    : 'Unknown error';
+                return err(`Failed to register pairing: ${errorMsg}`);
+            }
+        }
+        // Return response (echo nonce to prevent MITM)
+        return ok({
+            device_b_did: this.deviceDid,
+            accepted,
+            nonce: request.nonce,
+        });
+    }
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    async finalizePairing(response, expectedNonce) {
+        // Verify nonce echo (prevents MITM substitution)
+        if (response.nonce !== expectedNonce) {
+            return err('Nonce mismatch (possible MITM attack)');
+        }
+        // Check if pairing was accepted
+        if (!response.accepted) {
+            return err('Pairing rejected by remote device');
+        }
+        // Remove nonce from pending set
+        this.pendingNonces.delete(expectedNonce);
+        // Store in trust registry (Device B → Device A)
+        const registerResult = await this.registry.register(response.device_b_did, new Uint8Array(32), 'Paired Device', ['pairing']);
+        if (!registerResult.ok) {
+            const errorMsg = typeof registerResult.error === 'string'
+                ? registerResult.error
+                : 'Unknown error';
+            return err(`Failed to register pairing: ${errorMsg}`);
+        }
+        return ok(undefined);
+    }
+    /**
+     * Get pending nonce count (for debugging/monitoring).
+     */
+    getPendingNonceCount() {
+        return this.pendingNonces.size;
+    }
+}