veto-sdk 2.0.0 → 2.2.0

package/dist/economic/connectors/x402.js

@@ -0,0 +1,142 @@
+/**
+ * x402 protocol connector.
+ *
+ * Detects HTTP 402 Payment Required responses and parses the
+ * X-Payment header (Coinbase x402 V2 protocol) into EconomicContext.
+ *
+ * Timing mode: post-response — cost discovered from 402 response.
+ *
+ * @module economic/connectors/x402
+ */
+/**
+ * Stablecoin tokens treated as 1:1 USD parity.
+ * Non-stable tokens require developer-provided exchange rates (not supported in v1).
+ */
+const STABLECOIN_TOKENS = new Set(['USDC', 'USDT', 'DAI', 'BUSD']);
+function parseXPaymentHeader(header) {
+    // X-Payment header format: key=value pairs separated by semicolons
+    // e.g., "price=0.01;token=USDC;chain=base;recipient=0xabc..."
+    const parts = header.split(';').map(p => p.trim()).filter(Boolean);
+    const result = {};
+    for (const part of parts) {
+        const eqIdx = part.indexOf('=');
+        if (eqIdx === -1)
+            continue;
+        const key = part.slice(0, eqIdx).trim().toLowerCase();
+        const value = part.slice(eqIdx + 1).trim();
+        if (key && value) {
+            result[key] = value;
+        }
+    }
+    if (!result.price || !result.token || !result.chain || !result.recipient) {
+        return null;
+    }
+    return result;
+}
+function tokenToUsd(price, token) {
+    const amount = Number(price);
+    if (!Number.isFinite(amount) || amount < 0)
+        return null;
+    const upperToken = token.toUpperCase();
+    if (STABLECOIN_TOKENS.has(upperToken)) {
+        return amount; // 1:1 parity
+    }
+    // Non-stable tokens not supported in v1
+    return null;
+}
+/**
+ * Create an x402 protocol connector.
+ */
+export function createX402Connector() {
+    return {
+        protocol: 'x402',
+        protocolVersion: '2.0',
+        extract(response) {
+            // Handle fetch Response objects
+            if (response instanceof Response) {
+                if (response.status !== 402)
+                    return null;
+                const paymentHeader = response.headers.get('x-payment');
+                if (!paymentHeader)
+                    return null;
+                return parseFromHeader(paymentHeader);
+            }
+            // Handle plain objects (manual mode)
+            const status = response.status;
+            if (status !== 402)
+                return null;
+            const headers = response.headers;
+            if (!headers || typeof headers !== 'object')
+                return null;
+            // Support both Map-like and plain object headers
+            let paymentHeader;
+            if (headers instanceof Headers) {
+                paymentHeader = headers.get('x-payment') ?? undefined;
+            }
+            else {
+                const headerObj = headers;
+                paymentHeader = (headerObj['x-payment'] ?? headerObj['X-Payment']);
+            }
+            if (!paymentHeader)
+                return null;
+            return parseFromHeader(paymentHeader);
+        },
+        wrapFetch(fetchFn) {
+            return async (input, init) => {
+                const response = await fetchFn(input, init);
+                // Only intercept 402 responses — pass everything else through
+                if (response.status !== 402)
+                    return response;
+                // Clone to avoid consuming the body
+                const cloned = response.clone();
+                const paymentHeader = cloned.headers.get('x-payment');
+                if (!paymentHeader)
+                    return response;
+                const context = parseFromHeader(paymentHeader);
+                if (context) {
+                    // Attach economic context to response for downstream consumption
+                    response
+                        .__vetoEconomicContext = context;
+                }
+                return response;
+            };
+        },
+    };
+}
+function parseFromHeader(header) {
+    const instruction = parseXPaymentHeader(header);
+    if (!instruction)
+        return null;
+    const costUsd = tokenToUsd(instruction.price, instruction.token);
+    if (costUsd === null)
+        return null;
+    return {
+        cost: costUsd,
+        currency: 'USD',
+        payer: undefined, // Agent wallet set by caller
+        protocol: 'x402',
+        protocol_metadata: {
+            token: instruction.token,
+            chain: instruction.chain,
+            recipient: instruction.recipient,
+            raw_price: instruction.price,
+        },
+    };
+}
+/**
+ * Build a connector_error denial for x402 parse failures.
+ */
+export function buildX402ConnectorError(error) {
+    return {
+        reason: 'connector_error',
+        cost: 0,
+        currency: 'USD',
+        budget_scope: 'session',
+        budget_limit: 0,
+        budget_spent: 0,
+        budget_remaining: 0,
+        connector_name: 'x402',
+        raw_error: error,
+    };
+}
+//# sourceMappingURL=x402.js.map

package/dist/economic/connectors/x402.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.js","sourceRoot":"","sources":["../../../src/economic/connectors/x402.ts"],"names":[],"mappings":"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"}

package/dist/economic/evaluator.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Economic policy evaluator.
+ *
+ * Evaluates economic authorization policies against an EconomicContext.
+ * Runs payer checks, currency checks, and budget checks in order.
+ * Returns a result that composes with the behavioral guard() flow.
+ *
+ *   EconomicContext (from connector)
+ *        │
+ *        ▼
+ *   ┌─────────────────────────────────────┐
+ *   │         Economic Evaluator           │
+ *   │                                      │
+ *   │  1. Payer check                      │
+ *   │     ├── payer present? ──N──▶ deny   │
+ *   │     └── payer in approved? ──N──▶ deny│
+ *   │                                      │
+ *   │  2. Currency check                   │
+ *   │     └── matches budget? ──N──▶ deny  │
+ *   │                                      │
+ *   │  3. Budget check (BudgetEngine)      │
+ *   │     ├── exceeded ──▶ deny            │
+ *   │     ├── threshold ──▶ require_approval│
+ *   │     └── within ──▶ allow             │
+ *   └─────────────────────────────────────┘
+ *
+ * @module economic/evaluator
+ */
+import type { BudgetEngine, EconomicContext, EconomicDenialDetails, EconomicPolicyConfig } from './types.js';
+import type { Logger } from '../utils/logger.js';
+/**
+ * Result of economic evaluation.
+ */
+export interface EconomicEvaluationResult {
+    decision: 'allow' | 'deny' | 'require_approval';
+    denial?: EconomicDenialDetails;
+}
+export interface EconomicEvaluatorOptions {
+    policy: EconomicPolicyConfig;
+    budgetEngine: BudgetEngine;
+    logger: Logger;
+}
+export declare class EconomicEvaluator {
+    private readonly policy;
+    private readonly budgetEngine;
+    private readonly logger;
+    constructor(options: EconomicEvaluatorOptions);
+    /**
+     * Evaluate economic policies against the given context.
+     *
+     * Checks run in order: cost validation → payer → currency → budget.
+     * First failure short-circuits.
+     */
+    evaluate(economicContext: EconomicContext): EconomicEvaluationResult;
+    /**
+     * Resolve cost from tool call arguments using cost_extraction config.
+     *
+     * Reuses resolveFieldPath from the condition evaluator (DRY).
+     */
+    resolveCost(toolName: string, args: Record<string, unknown>): number | undefined;
+    /**
+     * Reserve budget for a cost (atomic check + deduct).
+     * Rolls back previously reserved scopes if a later scope fails.
+     */
+    reserveBudget(cost: number, currency: string): EconomicEvaluationResult;
+    /**
+     * Refund budget across all configured scopes.
+     */
+    refundBudget(amount: number): void;
+    /**
+     * Render a denial message template with context variables.
+     * Templates use {variable} syntax: "Would exceed {scope} budget ({spent}/{limit} {currency})"
+     */
+    renderDenialMessage(denial: EconomicDenialDetails): string | undefined;
+    private checkPayer;
+}
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/economic/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/economic/evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EACV,YAAY,EAGZ,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EAErB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGjD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,kBAAkB,CAAC;IAChD,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,YAAY,EAAE,YAAY,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,OAAO,EAAE,wBAAwB;IAM7C;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,eAAe,GAAG,wBAAwB;IAkEpE;;;;OAIG;IACH,WAAW,CACT,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,MAAM,GAAG,SAAS;IAiBrB;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,wBAAwB;IAkBvE;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAOlC;;;OAGG;IACH,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,GAAG,SAAS;IAkBtE,OAAO,CAAC,UAAU;CA+DnB"}

package/dist/economic/evaluator.js

@@ -0,0 +1,231 @@
+/**
+ * Economic policy evaluator.
+ *
+ * Evaluates economic authorization policies against an EconomicContext.
+ * Runs payer checks, currency checks, and budget checks in order.
+ * Returns a result that composes with the behavioral guard() flow.
+ *
+ *   EconomicContext (from connector)
+ *        │
+ *        ▼
+ *   ┌─────────────────────────────────────┐
+ *   │         Economic Evaluator           │
+ *   │                                      │
+ *   │  1. Payer check                      │
+ *   │     ├── payer present? ──N──▶ deny   │
+ *   │     └── payer in approved? ──N──▶ deny│
+ *   │                                      │
+ *   │  2. Currency check                   │
+ *   │     └── matches budget? ──N──▶ deny  │
+ *   │                                      │
+ *   │  3. Budget check (BudgetEngine)      │
+ *   │     ├── exceeded ──▶ deny            │
+ *   │     ├── threshold ──▶ require_approval│
+ *   │     └── within ──▶ allow             │
+ *   └─────────────────────────────────────┘
+ *
+ * @module economic/evaluator
+ */
+import { resolveFieldPath } from '../rules/condition-evaluator.js';
+export class EconomicEvaluator {
+    policy;
+    budgetEngine;
+    logger;
+    constructor(options) {
+        this.policy = options.policy;
+        this.budgetEngine = options.budgetEngine;
+        this.logger = options.logger;
+    }
+    /**
+     * Evaluate economic policies against the given context.
+     *
+     * Checks run in order: cost validation → payer → currency → budget.
+     * First failure short-circuits.
+     */
+    evaluate(economicContext) {
+        // 0. Cost validation — reject non-finite/negative costs hard
+        if (!Number.isFinite(economicContext.cost) || economicContext.cost < 0) {
+            this.logger.warn('Economic context has invalid cost', {
+                cost: economicContext.cost,
+                protocol: economicContext.protocol,
+            });
+            const firstBudget = this.policy.budgets?.[0];
+            const status = firstBudget
+                ? this.budgetEngine.getStatus(firstBudget.scope)
+                : null;
+            return {
+                decision: 'deny',
+                denial: {
+                    reason: 'invalid_cost',
+                    cost: economicContext.cost,
+                    currency: economicContext.currency,
+                    budget_scope: firstBudget?.scope ?? 'session',
+                    budget_limit: status?.limit ?? 0,
+                    budget_spent: status?.spent ?? 0,
+                    budget_remaining: status?.remaining ?? 0,
+                    protocol: economicContext.protocol,
+                    message: 'Invalid cost: must be a finite non-negative number',
+                },
+            };
+        }
+        // 1. Payer check
+        if (this.policy.payer) {
+            const payerResult = this.checkPayer(economicContext, this.policy.payer);
+            if (payerResult)
+                return payerResult;
+        }
+        // 2. Budget checks (one per configured budget scope)
+        const budgets = this.policy.budgets ?? [];
+        for (const budgetConfig of budgets) {
+            const result = this.budgetEngine.check(economicContext.cost, economicContext.currency, budgetConfig.scope);
+            if (!result.allowed) {
+                this.logger.warn('Economic budget check failed', {
+                    scope: budgetConfig.scope,
+                    decision: result.decision,
+                    cost: economicContext.cost,
+                    reason: result.denial?.reason,
+                });
+                const denial = result.denial;
+                if (denial) {
+                    const message = this.renderDenialMessage(denial);
+                    if (message)
+                        denial.message = message;
+                }
+                return {
+                    decision: result.decision,
+                    denial,
+                };
+            }
+        }
+        return { decision: 'allow' };
+    }
+    /**
+     * Resolve cost from tool call arguments using cost_extraction config.
+     *
+     * Reuses resolveFieldPath from the condition evaluator (DRY).
+     */
+    resolveCost(toolName, args) {
+        const extraction = this.policy.cost_extraction;
+        if (!extraction)
+            return undefined;
+        // Per-tool override or default path
+        const path = extraction.overrides?.[toolName] ?? extraction.default;
+        if (!path)
+            return undefined;
+        // Use the condition evaluator's field resolver
+        const value = resolveFieldPath(path, { arguments: args });
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+            return value;
+        }
+        return undefined;
+    }
+    /**
+     * Reserve budget for a cost (atomic check + deduct).
+     * Rolls back previously reserved scopes if a later scope fails.
+     */
+    reserveBudget(cost, currency) {
+        const budgets = this.policy.budgets ?? [];
+        const reservedScopes = [];
+        for (const budgetConfig of budgets) {
+            const result = this.budgetEngine.reserve(cost, currency, budgetConfig.scope);
+            if (!result.allowed) {
+                // Rollback all previously reserved scopes
+                for (const scope of reservedScopes) {
+                    this.budgetEngine.refund(cost, scope);
+                }
+                return { decision: result.decision, denial: result.denial };
+            }
+            reservedScopes.push(budgetConfig.scope);
+        }
+        return { decision: 'allow' };
+    }
+    /**
+     * Refund budget across all configured scopes.
+     */
+    refundBudget(amount) {
+        const budgets = this.policy.budgets ?? [];
+        for (const budgetConfig of budgets) {
+            this.budgetEngine.refund(amount, budgetConfig.scope);
+        }
+    }
+    /**
+     * Render a denial message template with context variables.
+     * Templates use {variable} syntax: "Would exceed {scope} budget ({spent}/{limit} {currency})"
+     */
+    renderDenialMessage(denial) {
+        const templates = this.policy.denial_reasons;
+        if (!templates)
+            return undefined;
+        const template = templates[denial.reason];
+        if (!template)
+            return undefined;
+        return template
+            .replace(/\{cost\}/g, String(denial.cost))
+            .replace(/\{currency\}/g, denial.currency)
+            .replace(/\{scope\}/g, denial.budget_scope)
+            .replace(/\{limit\}/g, String(denial.budget_limit))
+            .replace(/\{spent\}/g, String(denial.budget_spent))
+            .replace(/\{remaining\}/g, String(denial.budget_remaining))
+            .replace(/\{payer\}/g, denial.payer ?? 'unknown')
+            .replace(/\{threshold\}/g, String(denial.approval_threshold ?? denial.budget_limit));
+    }
+    checkPayer(context, payerConfig) {
+        // Payer required but missing
+        if (payerConfig.required && !context.payer) {
+            this.logger.warn('Payer required but missing', {
+                protocol: context.protocol,
+            });
+            // Use first budget's state for denial details, or zeros if no budgets
+            const firstBudget = this.policy.budgets?.[0];
+            const status = firstBudget
+                ? this.budgetEngine.getStatus(firstBudget.scope)
+                : null;
+            const payerMissingDenial = {
+                reason: 'payer_missing',
+                cost: context.cost,
+                currency: context.currency,
+                budget_scope: firstBudget?.scope ?? 'session',
+                budget_limit: status?.limit ?? 0,
+                budget_spent: status?.spent ?? 0,
+                budget_remaining: status?.remaining ?? 0,
+                payer: undefined,
+                protocol: context.protocol,
+            };
+            const payerMissingMsg = this.renderDenialMessage(payerMissingDenial);
+            if (payerMissingMsg)
+                payerMissingDenial.message = payerMissingMsg;
+            return { decision: 'deny', denial: payerMissingDenial };
+        }
+        // Payer not in approved list
+        if (payerConfig.approved
+            && payerConfig.approved.length > 0
+            && context.payer
+            && !payerConfig.approved.includes(context.payer)) {
+            this.logger.warn('Payer not in approved list', {
+                payer: context.payer,
+                protocol: context.protocol,
+            });
+            const firstBudget = this.policy.budgets?.[0];
+            const status = firstBudget
+                ? this.budgetEngine.getStatus(firstBudget.scope)
+                : null;
+            const payerUnauthorizedDenial = {
+                reason: 'payer_unauthorized',
+                cost: context.cost,
+                currency: context.currency,
+                budget_scope: firstBudget?.scope ?? 'session',
+                budget_limit: status?.limit ?? 0,
+                budget_spent: status?.spent ?? 0,
+                budget_remaining: status?.remaining ?? 0,
+                payer: context.payer,
+                protocol: context.protocol,
+            };
+            const payerUnauthorizedMsg = this.renderDenialMessage(payerUnauthorizedDenial);
+            if (payerUnauthorizedMsg)
+                payerUnauthorizedDenial.message = payerUnauthorizedMsg;
+            return { decision: 'deny', denial: payerUnauthorizedDenial };
+        }
+        return null; // Payer OK
+    }
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/economic/evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../src/economic/evaluator.ts"],"names":[],"mappings":"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"}

package/dist/economic/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Economic authorization module.
+ *
+ * Protocol-agnostic economic policy enforcement for agent payments
+ * across x402, Stripe MPP, Google AP2, and custom protocols.
+ *
+ * @module economic
+ */
+export type { EconomicProtocol, EconomicContext, EconomicDenialReason, EconomicDenialDetails, BudgetScope, EconomicBudgetConfig, CostExtractionConfig, PayerConfig, DenialReasonTemplates, EconomicPolicyConfig, BudgetCheckResult, EconomicBudgetStatus, BudgetEngine, ProtocolConnector, EconomicWebhookEventType, } from './types.js';
+export { LocalBudgetEngine, type LocalBudgetEngineOptions, } from './budget-engine.js';
+export { EconomicEvaluator, type EconomicEvaluatorOptions, type EconomicEvaluationResult, } from './evaluator.js';
+export { createX402Connector, createMPPConnector, createAP2Connector, buildX402ConnectorError, buildMPPConnectorError, buildAP2ConnectorError, type MPPSessionData, type AP2MandateData, } from './connectors/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/economic/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/economic/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,oBAAoB,EACpB,oBAAoB,EACpB,WAAW,EACX,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,GAC9B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,GAC9B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,uBAAuB,CAAC"}

package/dist/economic/index.js

@@ -0,0 +1,15 @@
+/**
+ * Economic authorization module.
+ *
+ * Protocol-agnostic economic policy enforcement for agent payments
+ * across x402, Stripe MPP, Google AP2, and custom protocols.
+ *
+ * @module economic
+ */
+// Budget engine
+export { LocalBudgetEngine, } from './budget-engine.js';
+// Evaluator
+export { EconomicEvaluator, } from './evaluator.js';
+// Connectors
+export { createX402Connector, createMPPConnector, createAP2Connector, buildX402ConnectorError, buildMPPConnectorError, buildAP2ConnectorError, } from './connectors/index.js';
+//# sourceMappingURL=index.js.map

package/dist/economic/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/economic/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAqBH,gBAAgB;AAChB,OAAO,EACL,iBAAiB,GAElB,MAAM,oBAAoB,CAAC;AAE5B,YAAY;AACZ,OAAO,EACL,iBAAiB,GAGlB,MAAM,gBAAgB,CAAC;AAExB,aAAa;AACb,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,GAGvB,MAAM,uBAAuB,CAAC"}