@private.me/xbind 1.3.5 → 3.0.0

package/dist-standalone/policy.js

@@ -1,315 +1 @@
-/**
- * @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;
-}
+import{ok,err}from"./_deps/shared/index.js";import{AgentError,AgentErrorCode}from"./agent-call.js";export class PolicyEngine{rateLimits=new Map;dailySpending=new Map;monthlySpending=new Map;evaluate(t,e,n,o){if(o.allowedTools&&o.allowedTools.length>0){const[t]=e.split(":");if(!o.allowedTools.some(n=>n===e||n===`${t}:*`||"*"===n)){const n={requested:e,allowed:o.allowedTools,constraint:"tool",fix:`Update policy.allowedTools to include "${e}" or "${t}:*" or request approval`};return err(new AgentError(AgentErrorCode.POLICY_VIOLATION,`Tool "${e}" is not allowed by policy`,n))}}if(o.scopes&&o.scopes.length>0){const t="object"==typeof n&&null!==n&&"scope"in n?n.scope:void 0;if(t&&!o.scopes.includes(t)){const e={requested:t,allowed:o.scopes,constraint:"scope",fix:`Update policy.scopes to include "${t}" or request additional permissions`};return err(new AgentError(AgentErrorCode.POLICY_VIOLATION,`Scope "${t}" is not allowed by policy`,e))}}if(o.limits?.callsPerMinute){const e=this.checkRateLimit(t,o.limits.callsPerMinute);if(!e.ok)return e}const i=this.extractAmount(n);if(null!==i){if(o.limits?.amountPerTxn&&i>o.limits.amountPerTxn){const t={requested:i,allowed:o.limits.amountPerTxn,constraint:"amountPerTxn",fix:`Reduce amount to ${o.limits.amountPerTxn} or less, or update policy.limits.amountPerTxn`};return err(new AgentError(AgentErrorCode.POLICY_VIOLATION,`Amount ${i} exceeds per-transaction limit of ${o.limits.amountPerTxn}`,t))}if(o.limits?.dailyAmount){const e=this.checkDailyLimit(t,i,o.limits.dailyAmount);if(!e.ok)return e}if(o.limits?.monthlyAmount){const e=this.checkMonthlyLimit(t,i,o.limits.monthlyAmount);if(!e.ok)return e}}return ok(void 0)}recordCall(t){const e=Date.now(),n=this.rateLimits.get(t)??{calls:[],windowStart:e};n.calls.push(e);const o=e-6e4;n.calls=n.calls.filter(t=>t>o),this.rateLimits.set(t,n)}recordSpending(t,e){const n=this.getCurrentDay(),o=this.getCurrentMonth(),i=this.dailySpending.get(t);i&&i.day===n?i.amount+=e:this.dailySpending.set(t,{amount:e,day:n});const r=this.monthlySpending.get(t);r&&r.month===o?r.amount+=e:this.monthlySpending.set(t,{amount:e,month:o})}getCurrentRateLimit(t){const e=this.rateLimits.get(t);if(!e)return 0;const n=Date.now()-6e4;return e.calls.filter(t=>t>n).length}getDailySpending(t){const e=this.getCurrentDay(),n=this.dailySpending.get(t);return n&&n.day===e?n.amount:0}getMonthlySpending(t){const e=this.getCurrentMonth(),n=this.monthlySpending.get(t);return n&&n.month===e?n.amount:0}reset(t){this.rateLimits.delete(t),this.dailySpending.delete(t),this.monthlySpending.delete(t)}checkRateLimit(t,e){const n=this.getCurrentRateLimit(t);if(n>=e){const t={requested:n+1,allowed:e,constraint:"callsPerMinute",current:n,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: ${n}/${e} calls per minute`,t))}return ok(void 0)}checkDailyLimit(t,e,n){const o=this.getDailySpending(t),i=o+e;if(i>n){const t=n-o,r={requested:e,allowed:n,constraint:"dailyAmount",current:o,newTotal:i,fix:t>0?`Reduce amount to ${t} 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 ${e} would exceed daily limit: ${i}/${n} (current: ${o})`,r))}return ok(void 0)}extractAmount(t){if("object"!=typeof t||null===t)return null;const e=t;return"number"==typeof e.amount?e.amount:"number"==typeof e.value?e.value:"number"==typeof e.price?e.price:"number"==typeof e.total?e.total:null}getCurrentDay(){return(new Date).toISOString().split("T")[0]??""}getCurrentMonth(){return(new Date).toISOString().substring(0,7)}checkMonthlyLimit(t,e,n){const o=this.getMonthlySpending(t),i=o+e;if(i>n){const t=n-o,r={requested:e,allowed:n,constraint:"dailyAmount",current:o,newTotal:i,fix:t>0?`Reduce amount to ${t} 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 ${e} would exceed monthly limit: ${i}/${n} (current: ${o})`,r))}return ok(void 0)}}let globalPolicyEngine=null;export function getGlobalPolicyEngine(){return globalPolicyEngine||(globalPolicyEngine=new PolicyEngine),globalPolicyEngine}