@private.me/xbind 1.2.0

package/dist-standalone/cjs/pairing-manager.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * @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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PairingManager = void 0;
+const shared_1 = require("../_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.
+ */
+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 (0, shared_1.err)(`Request expired (${Math.floor(age / 1000)}s old, max 60s)`);
+        }
+        if (age < 0) {
+            return (0, shared_1.err)('Request timestamp in the future (clock skew detected)');
+        }
+        // Check required fields
+        if (!request.device_a_did || !request.nonce || !request.timestamp) {
+            return (0, shared_1.err)('Missing required fields (device_a_did, nonce, timestamp)');
+        }
+        return (0, shared_1.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 (0, shared_1.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 (0, shared_1.err)(`Failed to register pairing: ${errorMsg}`);
+            }
+        }
+        // Return response (echo nonce to prevent MITM)
+        return (0, shared_1.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 (0, shared_1.err)('Nonce mismatch (possible MITM attack)');
+        }
+        // Check if pairing was accepted
+        if (!response.accepted) {
+            return (0, shared_1.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 (0, shared_1.err)(`Failed to register pairing: ${errorMsg}`);
+        }
+        return (0, shared_1.ok)(undefined);
+    }
+    /**
+     * Get pending nonce count (for debugging/monitoring).
+     */
+    getPendingNonceCount() {
+        return this.pendingNonces.size;
+    }
+}
+exports.PairingManager = PairingManager;

package/dist-standalone/cjs/policy.js

@@ -0,0 +1,320 @@
+"use strict";
+/**
+ * @module policy
+ * PolicyEngine for agent.call() constraint enforcement
+ *
+ * Enforces spending limits, rate limits, scope restrictions, and data filters
+ * on agent tool calls. Separate from SecurityPolicy (risk classification).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyEngine = void 0;
+exports.getGlobalPolicyEngine = getGlobalPolicyEngine;
+const shared_1 = require("../_deps/shared/index.js");
+const agent_call_js_1 = require("./agent-call.js");
+/**
+ * PolicyEngine - Enforces constraints on agent.call() requests
+ *
+ * Tracks:
+ * - Per-transaction spending limits
+ * - Daily spending limits
+ * - Rate limits (calls per minute)
+ * - Allowed tools/scopes
+ *
+ * Thread-safe for concurrent requests from the same agent.
+ */
+class PolicyEngine {
+    /** Rate limit tracker by agent DID */
+    rateLimits = new Map();
+    /** Daily spending tracker by agent DID */
+    dailySpending = new Map();
+    /** Monthly spending tracker by agent DID */
+    monthlySpending = new Map();
+    /**
+     * Evaluate a policy against a request
+     *
+     * @param agentDID - Agent DID making the request
+     * @param tool - Tool being called (e.g., "stripe:createCharge")
+     * @param params - Tool parameters
+     * @param constraints - Policy constraints to enforce
+     * @returns Policy evaluation result
+     */
+    evaluate(agentDID, tool, params, constraints) {
+        // Check allowed tools
+        if (constraints.allowedTools && constraints.allowedTools.length > 0) {
+            const [service] = tool.split(':');
+            const isAllowed = constraints.allowedTools.some((allowed) => allowed === tool || allowed === `${service}:*` || allowed === '*');
+            if (!isAllowed) {
+                const details = {
+                    requested: tool,
+                    allowed: constraints.allowedTools,
+                    constraint: 'tool',
+                    fix: `Update policy.allowedTools to include "${tool}" or "${service}:*" or request approval`,
+                };
+                return (0, shared_1.err)(new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.POLICY_VIOLATION, `Tool "${tool}" is not allowed by policy`, details));
+            }
+        }
+        // Check scopes
+        if (constraints.scopes && constraints.scopes.length > 0) {
+            // Extract scope from params if present
+            const scope = typeof params === 'object' && params !== null && 'scope' in params
+                ? params.scope
+                : undefined;
+            if (scope && !constraints.scopes.includes(scope)) {
+                const details = {
+                    requested: scope,
+                    allowed: constraints.scopes,
+                    constraint: 'scope',
+                    fix: `Update policy.scopes to include "${scope}" or request additional permissions`,
+                };
+                return (0, shared_1.err)(new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.POLICY_VIOLATION, `Scope "${scope}" is not allowed by policy`, details));
+            }
+        }
+        // Check rate limits
+        if (constraints.limits?.callsPerMinute) {
+            const rateCheck = this.checkRateLimit(agentDID, constraints.limits.callsPerMinute);
+            if (!rateCheck.ok) {
+                return rateCheck;
+            }
+        }
+        // Check spending limits (if amount is in params)
+        const amount = this.extractAmount(params);
+        if (amount !== null) {
+            // Check per-transaction limit
+            if (constraints.limits?.amountPerTxn && amount > constraints.limits.amountPerTxn) {
+                const details = {
+                    requested: amount,
+                    allowed: constraints.limits.amountPerTxn,
+                    constraint: 'amountPerTxn',
+                    fix: `Reduce amount to ${constraints.limits.amountPerTxn} or less, or update policy.limits.amountPerTxn`,
+                };
+                return (0, shared_1.err)(new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.POLICY_VIOLATION, `Amount ${amount} exceeds per-transaction limit of ${constraints.limits.amountPerTxn}`, details));
+            }
+            // Check daily limit
+            if (constraints.limits?.dailyAmount) {
+                const dailyCheck = this.checkDailyLimit(agentDID, amount, constraints.limits.dailyAmount);
+                if (!dailyCheck.ok) {
+                    return dailyCheck;
+                }
+            }
+            // Check monthly limit
+            if (constraints.limits?.monthlyAmount) {
+                const monthlyCheck = this.checkMonthlyLimit(agentDID, amount, constraints.limits.monthlyAmount);
+                if (!monthlyCheck.ok) {
+                    return monthlyCheck;
+                }
+            }
+        }
+        // All checks passed
+        return (0, shared_1.ok)(undefined);
+    }
+    /**
+     * Record a successful call (for rate limiting)
+     *
+     * @param agentDID - Agent DID
+     */
+    recordCall(agentDID) {
+        const now = Date.now();
+        const entry = this.rateLimits.get(agentDID) ?? {
+            calls: [],
+            windowStart: now,
+        };
+        entry.calls.push(now);
+        // Clean up old calls (older than 1 minute)
+        const oneMinuteAgo = now - 60000;
+        entry.calls = entry.calls.filter((timestamp) => timestamp > oneMinuteAgo);
+        this.rateLimits.set(agentDID, entry);
+    }
+    /**
+     * Record successful spending (for daily and monthly limits)
+     *
+     * @param agentDID - Agent DID
+     * @param amount - Amount spent
+     */
+    recordSpending(agentDID, amount) {
+        const today = this.getCurrentDay();
+        const thisMonth = this.getCurrentMonth();
+        // Update daily spending
+        const dailyEntry = this.dailySpending.get(agentDID);
+        if (dailyEntry && dailyEntry.day === today) {
+            dailyEntry.amount += amount;
+        }
+        else {
+            this.dailySpending.set(agentDID, {
+                amount,
+                day: today,
+            });
+        }
+        // Update monthly spending
+        const monthlyEntry = this.monthlySpending.get(agentDID);
+        if (monthlyEntry && monthlyEntry.month === thisMonth) {
+            monthlyEntry.amount += amount;
+        }
+        else {
+            this.monthlySpending.set(agentDID, {
+                amount,
+                month: thisMonth,
+            });
+        }
+    }
+    /**
+     * Get current rate limit status for an agent
+     *
+     * @param agentDID - Agent DID
+     * @returns Calls in current minute
+     */
+    getCurrentRateLimit(agentDID) {
+        const entry = this.rateLimits.get(agentDID);
+        if (!entry)
+            return 0;
+        const now = Date.now();
+        const oneMinuteAgo = now - 60000;
+        // Count calls in last minute
+        return entry.calls.filter((timestamp) => timestamp > oneMinuteAgo).length;
+    }
+    /**
+     * Get current daily spending for an agent
+     *
+     * @param agentDID - Agent DID
+     * @returns Amount spent today
+     */
+    getDailySpending(agentDID) {
+        const today = this.getCurrentDay();
+        const entry = this.dailySpending.get(agentDID);
+        if (!entry || entry.day !== today)
+            return 0;
+        return entry.amount;
+    }
+    /**
+     * Get current monthly spending for an agent
+     *
+     * @param agentDID - Agent DID
+     * @returns Amount spent this month
+     */
+    getMonthlySpending(agentDID) {
+        const thisMonth = this.getCurrentMonth();
+        const entry = this.monthlySpending.get(agentDID);
+        if (!entry || entry.month !== thisMonth)
+            return 0;
+        return entry.amount;
+    }
+    /**
+     * Reset all limits for an agent (for testing)
+     *
+     * @param agentDID - Agent DID
+     */
+    reset(agentDID) {
+        this.rateLimits.delete(agentDID);
+        this.dailySpending.delete(agentDID);
+        this.monthlySpending.delete(agentDID);
+    }
+    /**
+     * Check rate limit
+     */
+    checkRateLimit(agentDID, limit) {
+        const current = this.getCurrentRateLimit(agentDID);
+        if (current >= limit) {
+            const details = {
+                requested: current + 1,
+                allowed: limit,
+                constraint: 'callsPerMinute',
+                current,
+                fix: `Wait before making additional calls, or update policy.limits.callsPerMinute to a higher value`,
+            };
+            return (0, shared_1.err)(new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.POLICY_VIOLATION, `Rate limit exceeded: ${current}/${limit} calls per minute`, details));
+        }
+        return (0, shared_1.ok)(undefined);
+    }
+    /**
+     * Check daily spending limit
+     */
+    checkDailyLimit(agentDID, amount, limit) {
+        const current = this.getDailySpending(agentDID);
+        const newTotal = current + amount;
+        if (newTotal > limit) {
+            const remaining = limit - current;
+            const details = {
+                requested: amount,
+                allowed: limit,
+                constraint: 'dailyAmount',
+                current,
+                newTotal,
+                fix: remaining > 0
+                    ? `Reduce amount to ${remaining} or less (remaining today), or update policy.limits.dailyAmount`
+                    : `Daily limit already reached. Wait until tomorrow or update policy.limits.dailyAmount`,
+            };
+            return (0, shared_1.err)(new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.POLICY_VIOLATION, `Amount ${amount} would exceed daily limit: ${newTotal}/${limit} (current: ${current})`, details));
+        }
+        return (0, shared_1.ok)(undefined);
+    }
+    /**
+     * Extract amount from params
+     */
+    extractAmount(params) {
+        if (typeof params !== 'object' || params === null)
+            return null;
+        const obj = params;
+        // Check common amount field names
+        if (typeof obj.amount === 'number')
+            return obj.amount;
+        if (typeof obj.value === 'number')
+            return obj.value;
+        if (typeof obj.price === 'number')
+            return obj.price;
+        if (typeof obj.total === 'number')
+            return obj.total;
+        return null;
+    }
+    /**
+     * Get current day identifier (YYYY-MM-DD in UTC)
+     */
+    getCurrentDay() {
+        const now = new Date();
+        return now.toISOString().split('T')[0] ?? '';
+    }
+    /**
+     * Get current month identifier (YYYY-MM in UTC)
+     */
+    getCurrentMonth() {
+        const now = new Date();
+        const iso = now.toISOString();
+        return iso.substring(0, 7); // YYYY-MM
+    }
+    /**
+     * Check monthly spending limit
+     */
+    checkMonthlyLimit(agentDID, amount, limit) {
+        const current = this.getMonthlySpending(agentDID);
+        const newTotal = current + amount;
+        if (newTotal > limit) {
+            const remaining = limit - current;
+            const details = {
+                requested: amount,
+                allowed: limit,
+                constraint: 'dailyAmount', // Reuse constraint type (will add monthlyAmount later)
+                current,
+                newTotal,
+                fix: remaining > 0
+                    ? `Reduce amount to ${remaining} or less (remaining this month), or update policy.limits.monthlyAmount`
+                    : `Monthly limit already reached. Wait until next month or update policy.limits.monthlyAmount`,
+            };
+            return (0, shared_1.err)(new agent_call_js_1.AgentError(agent_call_js_1.AgentErrorCode.POLICY_VIOLATION, `Amount ${amount} would exceed monthly limit: ${newTotal}/${limit} (current: ${current})`, details));
+        }
+        return (0, shared_1.ok)(undefined);
+    }
+}
+exports.PolicyEngine = PolicyEngine;
+/**
+ * Global policy engine instance (singleton)
+ */
+let globalPolicyEngine = null;
+/**
+ * Get the global policy engine instance
+ *
+ * @returns PolicyEngine instance
+ */
+function getGlobalPolicyEngine() {
+    if (!globalPolicyEngine) {
+        globalPolicyEngine = new PolicyEngine();
+    }
+    return globalPolicyEngine;
+}

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

@@ -0,0 +1,76 @@
+"use strict";
+/* -- RedisNonceStore -- Cross-Node Replay Prevention -- */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisNonceStore = void 0;
+/** Default TTL for nonce entries: 600 seconds (10 minutes). */
+const DEFAULT_TTL_SECONDS = 600;
+/** Default key prefix for Redis nonce keys. */
+const DEFAULT_KEY_PREFIX = 'nonce:';
+/**
+ * Redis-backed nonce store for multi-node deployments.
+ *
+ * Uses Redis SET NX with TTL for atomic, distributed nonce deduplication.
+ * Nonce expiry is handled by Redis TTL -- no manual cleanup needed.
+ * Zero npm dependencies: users provide their own RedisClient implementation.
+ *
+ * @example
+ * ```typescript
+ * import { RedisNonceStore } from '@private.me/xbind';
+ * import Redis from 'ioredis';
+ *
+ * const redis = new Redis();
+ * const store = new RedisNonceStore({
+ *   client: {
+ *     setNX: (key, value, ttl) =>
+ *       redis.set(key, value, 'EX', ttl, 'NX'),
+ *     del: (key) => redis.del(key),
+ *     quit: () => redis.quit(),
+ *   },
+ * });
+ * ```
+ */
+class RedisNonceStore {
+    client;
+    ttlSeconds;
+    keyPrefix;
+    constructor(opts) {
+        this.client = opts.client;
+        this.ttlSeconds = opts.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+        this.keyPrefix = opts.keyPrefix ?? DEFAULT_KEY_PREFIX;
+    }
+    /**
+     * Check if a nonce is fresh and record it atomically via Redis SET NX.
+     *
+     * Uses Redis SET with NX (set-if-not-exists) and EX (TTL in seconds)
+     * for atomic, distributed deduplication. If the key already exists in
+     * any Redis-connected node, the nonce is rejected as a duplicate.
+     *
+     * @param nonce - The nonce string to check.
+     * @param senderDid - The DID of the sender.
+     * @returns true if the nonce is new (accepted), false if duplicate (rejected).
+     */
+    async check(nonce, senderDid) {
+        const key = `${this.keyPrefix}${senderDid}:${nonce}`;
+        const result = await this.client.setNX(key, '1', this.ttlSeconds);
+        return result === 'OK';
+    }
+    /**
+     * No-op for Redis store -- TTL-based expiry is handled automatically.
+     *
+     * This method exists to satisfy the NonceStore interface. Redis keys
+     * expire based on the TTL set during setNX, so no manual cleanup is needed.
+     */
+    cleanup() {
+        // No-op: Redis TTL handles expiry automatically
+    }
+    /**
+     * Disconnect from Redis gracefully.
+     *
+     * Calls the underlying RedisClient quit() method to close the connection.
+     * After calling dispose(), the store should not be used.
+     */
+    dispose() {
+        void this.client.quit();
+    }
+}
+exports.RedisNonceStore = RedisNonceStore;

package/dist-standalone/cjs/registry-middleware.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Express middleware for protecting trust registry endpoints with bearer auth.
+ *
+ * GET/HEAD requests pass through (public reads). POST/PUT/DELETE require
+ * a valid Bearer token matching the configured admin token.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { createRegistryAuthMiddleware } from '@private.me/xbind';
+ *
+ * const app = express();
+ * app.use('/registry', createRegistryAuthMiddleware(process.env.REGISTRY_ADMIN_TOKEN!));
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRegistryAuthMiddleware = createRegistryAuthMiddleware;
+/**
+ * Create an Express-compatible middleware that protects write operations
+ * on registry endpoints with bearer token authentication.
+ *
+ * GET and HEAD requests pass through without authentication.
+ * POST, PUT, and DELETE require `Authorization: Bearer <token>`.
+ *
+ * @param token - The admin token to validate against.
+ * @returns Express middleware function.
+ */
+function createRegistryAuthMiddleware(token) {
+    return (req, res, next) => {
+        const method = req.method.toUpperCase();
+        if (method === 'GET' || method === 'HEAD') {
+            next();
+            return;
+        }
+        const authHeader = typeof req.headers['authorization'] === 'string'
+            ? req.headers['authorization']
+            : undefined;
+        if (!authHeader || !authHeader.startsWith('Bearer ')) {
+            res.status(401).json({ error: 'UNAUTHORIZED' });
+            return;
+        }
+        const provided = authHeader.slice('Bearer '.length);
+        if (provided !== token) {
+            res.status(401).json({ error: 'UNAUTHORIZED' });
+            return;
+        }
+        next();
+    };
+}