@private.me/xbind 1.2.0

package/dist-standalone/pairing-manager.js

@@ -0,0 +1,219 @@
+/**
+ * @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;
+    }
+}

package/dist-standalone/policy.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @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).
+ */
+import type { Result } from '@private.me/shared';
+import { AgentError } from './agent-call.js';
+import type { PolicyConstraints } from './agent-call.js';
+/**
+ * Policy evaluation result
+ */
+export interface PolicyResult {
+    /** Whether the request is allowed */
+    allowed: boolean;
+    /** Reason for denial (if not allowed) */
+    reason?: string;
+    /** Which constraint was violated (if not allowed) */
+    violatedConstraint?: 'amount' | 'daily' | 'rate' | 'scope' | 'tool';
+}
+/**
+ * Detailed policy violation information for AI agents
+ */
+export interface PolicyViolationDetails extends Record<string, unknown> {
+    /** What was requested/denied */
+    requested: string | number;
+    /** What the limit/constraint is */
+    allowed: string | number | string[];
+    /** Which constraint type was violated */
+    constraint: 'amountPerTxn' | 'dailyAmount' | 'callsPerMinute' | 'scope' | 'tool';
+    /** How to fix the issue */
+    fix: string;
+    /** Additional context (optional) */
+    current?: number;
+    /** New total after this request (optional, for daily limits) */
+    newTotal?: number;
+}
+/**
+ * Policy limits with time-window tracking
+ */
+export interface PolicyLimits {
+    /** Maximum amount per transaction */
+    amountPerTxn?: number;
+    /** Maximum amount per day (24-hour window) */
+    dailyAmount?: number;
+    /** Maximum amount per month (30-day window) */
+    monthlyAmount?: number;
+    /** Maximum calls per minute */
+    callsPerMinute?: number;
+}
+/**
+ * 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.
+ */
+export declare class PolicyEngine {
+    /** Rate limit tracker by agent DID */
+    private readonly rateLimits;
+    /** Daily spending tracker by agent DID */
+    private readonly dailySpending;
+    /** Monthly spending tracker by agent DID */
+    private readonly monthlySpending;
+    /**
+     * 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: string, tool: string, params: unknown, constraints: PolicyConstraints): Result<void, AgentError>;
+    /**
+     * Record a successful call (for rate limiting)
+     *
+     * @param agentDID - Agent DID
+     */
+    recordCall(agentDID: string): void;
+    /**
+     * Record successful spending (for daily and monthly limits)
+     *
+     * @param agentDID - Agent DID
+     * @param amount - Amount spent
+     */
+    recordSpending(agentDID: string, amount: number): void;
+    /**
+     * Get current rate limit status for an agent
+     *
+     * @param agentDID - Agent DID
+     * @returns Calls in current minute
+     */
+    getCurrentRateLimit(agentDID: string): number;
+    /**
+     * Get current daily spending for an agent
+     *
+     * @param agentDID - Agent DID
+     * @returns Amount spent today
+     */
+    getDailySpending(agentDID: string): number;
+    /**
+     * Get current monthly spending for an agent
+     *
+     * @param agentDID - Agent DID
+     * @returns Amount spent this month
+     */
+    getMonthlySpending(agentDID: string): number;
+    /**
+     * Reset all limits for an agent (for testing)
+     *
+     * @param agentDID - Agent DID
+     */
+    reset(agentDID: string): void;
+    /**
+     * Check rate limit
+     */
+    private checkRateLimit;
+    /**
+     * Check daily spending limit
+     */
+    private checkDailyLimit;
+    /**
+     * Extract amount from params
+     */
+    private extractAmount;
+    /**
+     * Get current day identifier (YYYY-MM-DD in UTC)
+     */
+    private getCurrentDay;
+    /**
+     * Get current month identifier (YYYY-MM in UTC)
+     */
+    private getCurrentMonth;
+    /**
+     * Check monthly spending limit
+     */
+    private checkMonthlyLimit;
+}
+/**
+ * Get the global policy engine instance
+ *
+ * @returns PolicyEngine instance
+ */
+export declare function getGlobalPolicyEngine(): PolicyEngine;

package/dist-standalone/policy.js

@@ -0,0 +1,315 @@
+/**
+ * @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).
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { AgentError, AgentErrorCode } from './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.
+ */
+export 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 err(new AgentError(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 err(new AgentError(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 err(new AgentError(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 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 err(new AgentError(AgentErrorCode.POLICY_VIOLATION, `Rate limit exceeded: ${current}/${limit} calls per minute`, details));
+        }
+        return 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 err(new AgentError(AgentErrorCode.POLICY_VIOLATION, `Amount ${amount} would exceed daily limit: ${newTotal}/${limit} (current: ${current})`, details));
+        }
+        return 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 err(new AgentError(AgentErrorCode.POLICY_VIOLATION, `Amount ${amount} would exceed monthly limit: ${newTotal}/${limit} (current: ${current})`, details));
+        }
+        return ok(undefined);
+    }
+}
+/**
+ * Global policy engine instance (singleton)
+ */
+let globalPolicyEngine = null;
+/**
+ * Get the global policy engine instance
+ *
+ * @returns PolicyEngine instance
+ */
+export function getGlobalPolicyEngine() {
+    if (!globalPolicyEngine) {
+        globalPolicyEngine = new PolicyEngine();
+    }
+    return globalPolicyEngine;
+}