@usesigil/kit 0.1.0

package/dist/vault-analytics.js

@@ -0,0 +1,175 @@
+/**
+ * Vault analytics — health assessment and one-call summary.
+ *
+ * getVaultHealth(): Pure function (no RPC) — derives health, cap metrics,
+ * security checks from already-resolved vault state.
+ *
+ * getVaultSummary(): Async function — parallel RPC calls for state, P&L,
+ * balances, pending policy. Returns everything a vault detail page needs.
+ */
+import { VaultStatus } from "./generated/types/vaultStatus.js";
+import { resolveVaultStateForOwner, getPendingPolicyForVault, } from "./state-resolver.js";
+import { getVaultPnL, getVaultTokenBalances, } from "./balance-tracker.js";
+import { getSpendingVelocity } from "./spending-analytics.js";
+import { FULL_PERMISSIONS, PROTOCOL_MODE_ALLOWLIST, EPOCH_DURATION, NUM_EPOCHS, } from "./types.js";
+// ─── getVaultHealth ──────────────────────────────────────────────────────────
+/**
+ * Single-call vault health assessment. Pure function — no RPC.
+ *
+ * Derives isHealthy, capUtilization, capResetsIn, security checks from
+ * already-resolved vault state. The dashboard vault card renders this directly.
+ */
+export function getVaultHealth(state, nowUnix) {
+    const { vault, policy, tracker, globalBudget, constraints } = state;
+    // VaultStatus is a numeric enum (Active=0, Frozen=1, Closed=2).
+    // Use reverse mapping for display string.
+    const STATUS_NAMES = {
+        [VaultStatus.Active]: "Active",
+        [VaultStatus.Frozen]: "Frozen",
+        [VaultStatus.Closed]: "Closed",
+    };
+    const status = STATUS_NAMES[vault.status] ?? "Closed";
+    const agentCount = vault.agents.length;
+    const pausedAgentCount = vault.agents.filter((a) => a.paused).length;
+    // Cap utilization
+    const capUtilization = globalBudget.cap > 0n
+        ? Number((globalBudget.spent24h * 10000n) / globalBudget.cap) / 100
+        : 0;
+    // Cap reset time: when does the oldest epoch in the window roll off?
+    let capResetsIn = 0;
+    if (tracker) {
+        const epochDuration = BigInt(EPOCH_DURATION);
+        const currentEpoch = nowUnix / epochDuration;
+        let oldestEpoch = currentEpoch;
+        for (const bucket of tracker.buckets) {
+            if (bucket.usdAmount > 0n && bucket.epochId > 0n) {
+                if (bucket.epochId >= currentEpoch - BigInt(NUM_EPOCHS) &&
+                    bucket.epochId < oldestEpoch) {
+                    oldestEpoch = bucket.epochId;
+                }
+            }
+        }
+        const expiresAt = (oldestEpoch + BigInt(NUM_EPOCHS)) * epochDuration;
+        capResetsIn = Math.max(0, Number(expiresAt - nowUnix));
+    }
+    // Velocity for time-to-cap
+    const velocity = getSpendingVelocity(tracker, nowUnix, globalBudget);
+    // Security checks
+    const securityChecks = [
+        {
+            id: "no-full-perms",
+            label: "No agent has full permissions",
+            passed: !vault.agents.some((a) => a.permissions === FULL_PERMISSIONS),
+            severity: "critical",
+        },
+        {
+            id: "cap-configured",
+            label: "Daily spending cap is configured",
+            passed: policy.dailySpendingCapUsd > 0n,
+            severity: "critical",
+        },
+        {
+            id: "agent-limits",
+            label: "All agents have spending limits",
+            passed: vault.agents.every((a) => a.spendingLimitUsd > 0n),
+            severity: "warning",
+        },
+        {
+            id: "protocol-allowlist",
+            label: "Protocol mode is allowlist",
+            passed: policy.protocolMode === PROTOCOL_MODE_ALLOWLIST,
+            severity: "warning",
+        },
+        {
+            id: "timelock-enabled",
+            label: "Policy timelock is enabled",
+            passed: policy.timelockDuration > 0n,
+            severity: "warning",
+        },
+        {
+            id: "slippage-reasonable",
+            label: "Max slippage below 10%",
+            passed: policy.maxSlippageBps < 1000,
+            severity: "warning",
+        },
+        {
+            id: "constraints-configured",
+            label: "Instruction constraints are set",
+            passed: constraints !== null,
+            severity: "info",
+        },
+    ];
+    const criticalFailures = securityChecks.filter((c) => c.severity === "critical" && !c.passed);
+    const isHealthy = status === "Active" &&
+        agentCount > 0 &&
+        pausedAgentCount < agentCount &&
+        capUtilization < 95 &&
+        criticalFailures.length === 0;
+    return {
+        status,
+        isHealthy,
+        agentCount,
+        pausedAgentCount,
+        openPositions: vault.openPositions,
+        activeEscrowCount: vault.activeEscrowCount,
+        capUtilization,
+        capRemaining: globalBudget.remaining,
+        capResetsIn,
+        timeToCapAtCurrentRate: velocity.timeToCapSeconds,
+        hasConstraints: constraints !== null,
+        hasTimelock: policy.timelockDuration > 0n,
+        timelockDuration: Number(policy.timelockDuration),
+        hasPendingPolicyChange: false, // Overridden by getVaultSummary()
+        lastActivityTimestamp: tracker && tracker.lastWriteEpoch > 0n
+            ? Number(tracker.lastWriteEpoch * BigInt(EPOCH_DURATION))
+            : 0,
+        securityChecks,
+    };
+}
+// ─── getVaultSummary ─────────────────────────────────────────────────────────
+/**
+ * Complete vault summary in one call. Parallel RPC for state, P&L, balances,
+ * pending policy. Returns everything the vault detail page header needs.
+ */
+export async function getVaultSummary(rpc, vault, network = "mainnet-beta") {
+    const [state, pnl, tokenBalances, pendingPolicy] = await Promise.all([
+        resolveVaultStateForOwner(rpc, vault, undefined, network),
+        getVaultPnL(rpc, vault, network),
+        getVaultTokenBalances(rpc, vault, network),
+        getPendingPolicyForVault(rpc, vault).catch(() => null),
+    ]);
+    const nowUnix = state.resolvedAtTimestamp;
+    const health = getVaultHealth(state, nowUnix);
+    health.hasPendingPolicyChange = pendingPolicy !== null;
+    const v = state.vault;
+    const createdAtSec = Number(v.createdAt);
+    const nowSec = Number(nowUnix);
+    const ageInDays = Math.max(1, Math.floor((nowSec - createdAtSec) / 86400));
+    const stats = {
+        totalTransactions: v.totalTransactions,
+        totalVolume: v.totalVolume,
+        totalFeesCollected: v.totalFeesCollected,
+        totalDeposited: v.totalDepositedUsd,
+        totalWithdrawn: v.totalWithdrawnUsd,
+        createdAt: v.createdAt,
+        ageInDays,
+        avgDailyVolume: ageInDays > 0 ? v.totalVolume / BigInt(ageInDays) : 0n,
+        avgTransactionSize: v.totalTransactions > 0n ? v.totalVolume / v.totalTransactions : 0n,
+        feeRate: v.totalVolume > 0n
+            ? Number((v.totalFeesCollected * 10000n) / v.totalVolume)
+            : 0,
+    };
+    const totalValueUsd = state.stablecoinBalances.usdc + state.stablecoinBalances.usdt;
+    return {
+        address: vault,
+        owner: v.owner,
+        vaultId: v.vaultId,
+        health,
+        pnl,
+        tokenBalances,
+        totalValueUsd,
+        state,
+        stats,
+    };
+}
+//# sourceMappingURL=vault-analytics.js.map

package/dist/vault-analytics.js.map

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

package/dist/velocity-tracker.d.ts

@@ -0,0 +1,79 @@
+/**
+ * VelocityTracker — Kit-native Agent Manipulation Defense
+ *
+ * Monitors transaction velocity (TX/min, TX/hr, USD/hr) and detects
+ * rapid-fire transaction patterns that may indicate agent manipulation.
+ *
+ * Integrates with ShieldState for unified spending tracking.
+ */
+import type { Address } from "@solana/kit";
+import type { ShieldState } from "./shield.js";
+export interface SpendStatus {
+    globalSpent24h: bigint;
+    globalCap: bigint | null;
+    globalRemaining: bigint | null;
+    agentSpent24h: bigint | null;
+    agentCap: bigint | null;
+    source: "on-chain" | "client-side";
+}
+export interface VelocityConfig {
+    /** Max transactions per minute (default: 10) */
+    maxTxPerMinute?: number;
+    /** Max transactions per hour (default: 60) */
+    maxTxPerHour?: number;
+    /** Max USD spend per hour in base units (default: 500_000_000n = $500) */
+    maxUsdPerHour?: bigint;
+    /** Rapid-fire detection: count transactions within windowMs */
+    rapidFireThreshold?: {
+        count: number;
+        windowMs: number;
+    };
+    /** Cooldown period in ms after velocity breach (default: 30_000 = 30s) */
+    cooldownMs?: number;
+}
+export declare class VelocityTracker {
+    private readonly state;
+    private readonly config;
+    private cooldownUntil;
+    private txTimestamps;
+    constructor(state: ShieldState, config?: VelocityConfig);
+    /**
+     * Check velocity constraints. Throws ShieldDeniedError (code 7022) on breach.
+     *
+     * @param signerAddress - The signer to check
+     * @param dryRun - S-6: When true, checks without incrementing the rapid-fire counter.
+     *                 Useful for precheck queries that shouldn't pollute velocity state.
+     */
+    check(signerAddress: Address, dryRun?: boolean): void;
+    /**
+     * Record a transaction after successful send.
+     */
+    recordTransaction(usdAmount?: bigint): void;
+    /**
+     * Whether the tracker is in a cooldown period after a velocity breach.
+     */
+    isInCooldown(): boolean;
+    /**
+     * Get remaining cooldown time in ms. Returns 0 if not in cooldown.
+     */
+    getCooldownRemainingMs(): number;
+    /**
+     * Reset the tracker (clears cooldown and timestamps).
+     */
+    reset(): void;
+    /**
+     * Get current spend status. Returns on-chain data when ShieldState is synced.
+     */
+    getSpendStatus(): SpendStatus;
+    /**
+     * Get current velocity stats.
+     */
+    getStats(): {
+        txPerMinute: number;
+        txPerHour: number;
+        usdPerHour: bigint;
+        inCooldown: boolean;
+        cooldownRemainingMs: number;
+    };
+}
+//# sourceMappingURL=velocity-tracker.d.ts.map

package/dist/velocity-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"velocity-tracker.d.ts","sourceRoot":"","sources":["../src/velocity-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK/C,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC;CACpC;AAID,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAYD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,YAAY,CAAgB;gBAExB,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,cAAc;IAYvD;;;;;;OAMG;IACH,KAAK,CAAC,aAAa,EAAE,OAAO,EAAE,MAAM,UAAQ,GAAG,IAAI;IAuFnD;;OAEG;IACH,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAO3C;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;IACH,sBAAsB,IAAI,MAAM;IAKhC;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,cAAc,IAAI,WAAW;IAuB7B;;OAEG;IACH,QAAQ,IAAI;QACV,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,OAAO,CAAC;QACpB,mBAAmB,EAAE,MAAM,CAAC;KAC7B;CASF"}

package/dist/velocity-tracker.js

@@ -0,0 +1,183 @@
+/**
+ * VelocityTracker — Kit-native Agent Manipulation Defense
+ *
+ * Monitors transaction velocity (TX/min, TX/hr, USD/hr) and detects
+ * rapid-fire transaction patterns that may indicate agent manipulation.
+ *
+ * Integrates with ShieldState for unified spending tracking.
+ */
+import { ShieldDeniedError } from "./shield.js";
+const DEFAULT_CONFIG = {
+    maxTxPerMinute: 10,
+    maxTxPerHour: 60,
+    maxUsdPerHour: 500000000n,
+    rapidFireThreshold: { count: 5, windowMs: 10_000 },
+    cooldownMs: 30_000,
+};
+// ─── VelocityTracker ────────────────────────────────────────────────────────
+export class VelocityTracker {
+    state;
+    config;
+    cooldownUntil = 0;
+    txTimestamps = [];
+    constructor(state, config) {
+        this.state = state;
+        this.config = {
+            maxTxPerMinute: config?.maxTxPerMinute ?? DEFAULT_CONFIG.maxTxPerMinute,
+            maxTxPerHour: config?.maxTxPerHour ?? DEFAULT_CONFIG.maxTxPerHour,
+            maxUsdPerHour: config?.maxUsdPerHour ?? DEFAULT_CONFIG.maxUsdPerHour,
+            rapidFireThreshold: config?.rapidFireThreshold ?? DEFAULT_CONFIG.rapidFireThreshold,
+            cooldownMs: config?.cooldownMs ?? DEFAULT_CONFIG.cooldownMs,
+        };
+    }
+    /**
+     * Check velocity constraints. Throws ShieldDeniedError (code 7022) on breach.
+     *
+     * @param signerAddress - The signer to check
+     * @param dryRun - S-6: When true, checks without incrementing the rapid-fire counter.
+     *                 Useful for precheck queries that shouldn't pollute velocity state.
+     */
+    check(signerAddress, dryRun = false) {
+        const violations = [];
+        // 0. Cooldown check
+        if (this.isInCooldown()) {
+            const remainingMs = this.cooldownUntil - Date.now();
+            throw new ShieldDeniedError([
+                {
+                    rule: "velocity_cooldown",
+                    message: `Velocity cooldown active — ${Math.ceil(remainingMs / 1000)}s remaining`,
+                    suggestion: "Wait for the cooldown period to expire",
+                },
+            ]);
+        }
+        // 1. TX/minute check
+        const txPerMinute = this.state.getTransactionCountInWindow(60_000);
+        if (txPerMinute >= this.config.maxTxPerMinute) {
+            violations.push({
+                rule: "velocity_tx_per_minute",
+                message: `Transaction rate ${txPerMinute}/${this.config.maxTxPerMinute} per minute exceeded`,
+                suggestion: "Wait before sending more transactions",
+            });
+        }
+        // 2. TX/hour check
+        const txPerHour = this.state.getTransactionCountInWindow(3_600_000);
+        if (txPerHour >= this.config.maxTxPerHour) {
+            violations.push({
+                rule: "velocity_tx_per_hour",
+                message: `Transaction rate ${txPerHour}/${this.config.maxTxPerHour} per hour exceeded`,
+                suggestion: "Wait before sending more transactions",
+            });
+        }
+        // 3. USD/hour check (cross-mint aggregation — BUG-3 fix)
+        const usdPerHour = this.state.getTotalSpendInWindow(3_600_000);
+        if (usdPerHour >= this.config.maxUsdPerHour) {
+            violations.push({
+                rule: "velocity_usd_per_hour",
+                message: `Hourly USD spend ${usdPerHour} exceeds ceiling ${this.config.maxUsdPerHour}`,
+                suggestion: "Reduce transaction amounts or wait for the window to reset",
+            });
+        }
+        // 3b. On-chain 24h cap check (when synced)
+        const rs = this.state.resolvedState;
+        if (rs) {
+            const effectiveSpent = this.state.getEffectiveGlobalSpent24h();
+            if (effectiveSpent >= rs.globalBudget.cap) {
+                violations.push({
+                    rule: "velocity_on_chain_cap",
+                    message: `On-chain daily cap reached: ${effectiveSpent} >= ${rs.globalBudget.cap}`,
+                    suggestion: "Wait for the 24h rolling window to expire some spend",
+                });
+            }
+        }
+        // 4. Rapid-fire detection
+        const now = Date.now();
+        // S-6: Filter existing timestamps regardless of dryRun
+        const cutoff = now - this.config.rapidFireThreshold.windowMs;
+        this.txTimestamps = this.txTimestamps.filter((t) => t >= cutoff);
+        // Compute what the count would be if we added this check
+        const wouldBeCount = this.txTimestamps.length + 1;
+        if (wouldBeCount >= this.config.rapidFireThreshold.count) {
+            violations.push({
+                rule: "velocity_rapid_fire",
+                message: `Rapid-fire detected: ${wouldBeCount} transactions in ${this.config.rapidFireThreshold.windowMs}ms`,
+                suggestion: "Possible agent manipulation — transactions blocked",
+            });
+        }
+        if (violations.length > 0) {
+            // Trigger cooldown
+            this.cooldownUntil = now + this.config.cooldownMs;
+            throw new ShieldDeniedError(violations);
+        }
+        // S-6: Only push timestamp if not a dry run
+        if (!dryRun) {
+            this.txTimestamps.push(now);
+        }
+    }
+    /**
+     * Record a transaction after successful send.
+     */
+    recordTransaction(usdAmount) {
+        this.state.recordTransaction();
+        if (usdAmount !== undefined) {
+            this.state.recordSpend("", usdAmount);
+        }
+    }
+    /**
+     * Whether the tracker is in a cooldown period after a velocity breach.
+     */
+    isInCooldown() {
+        return Date.now() < this.cooldownUntil;
+    }
+    /**
+     * Get remaining cooldown time in ms. Returns 0 if not in cooldown.
+     */
+    getCooldownRemainingMs() {
+        const remaining = this.cooldownUntil - Date.now();
+        return remaining > 0 ? remaining : 0;
+    }
+    /**
+     * Reset the tracker (clears cooldown and timestamps).
+     */
+    reset() {
+        this.cooldownUntil = 0;
+        this.txTimestamps = [];
+    }
+    /**
+     * Get current spend status. Returns on-chain data when ShieldState is synced.
+     */
+    getSpendStatus() {
+        const rs = this.state.resolvedState;
+        if (rs) {
+            return {
+                globalSpent24h: this.state.getEffectiveGlobalSpent24h(),
+                globalCap: rs.globalBudget.cap,
+                globalRemaining: this.state.getEffectiveGlobalRemaining(),
+                agentSpent24h: this.state.getEffectiveAgentSpent24h(),
+                agentCap: rs.agentBudget?.cap ?? null,
+                source: "on-chain",
+            };
+        }
+        const clientSpend = this.state.getTotalSpendInWindow(86_400_000);
+        return {
+            globalSpent24h: clientSpend,
+            globalCap: null,
+            globalRemaining: null,
+            agentSpent24h: null,
+            agentCap: null,
+            source: "client-side",
+        };
+    }
+    /**
+     * Get current velocity stats.
+     */
+    getStats() {
+        return {
+            txPerMinute: this.state.getTransactionCountInWindow(60_000),
+            txPerHour: this.state.getTransactionCountInWindow(3_600_000),
+            usdPerHour: this.state.getTotalSpendInWindow(3_600_000),
+            inCooldown: this.isInCooldown(),
+            cooldownRemainingMs: this.getCooldownRemainingMs(),
+        };
+    }
+}
+//# sourceMappingURL=velocity-tracker.js.map

package/dist/velocity-tracker.js.map

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

package/dist/x402/amount-guard.d.ts

@@ -0,0 +1,26 @@
+/**
+ * x402 Amount Guard — Kit-native
+ *
+ * Validates payment amounts beyond simple maxPayment ceiling.
+ * Detects zero, negative, NaN, per-request ceiling, and spike anomalies.
+ */
+import type { X402Config } from "./types.js";
+/**
+ * Validate a payment amount against sanity checks.
+ *
+ * @throws X402PaymentError on invalid or suspicious amounts
+ */
+export declare function validatePaymentAmount(amount: string, config?: X402Config): bigint;
+/**
+ * Record a successful payment amount for spike detection.
+ */
+export declare function recordPaymentAmount(amount: bigint): void;
+/**
+ * Reset the recent payments history (for testing).
+ */
+export declare function resetPaymentHistory(): void;
+/**
+ * Get the current payment history length (for testing).
+ */
+export declare function getPaymentHistoryLength(): number;
+//# sourceMappingURL=amount-guard.d.ts.map

package/dist/x402/amount-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount-guard.d.ts","sourceRoot":"","sources":["../../src/x402/amount-guard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAe7C;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,UAAU,GAClB,MAAM,CAuCR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAKxD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD"}

package/dist/x402/amount-guard.js

@@ -0,0 +1,80 @@
+/**
+ * x402 Amount Guard — Kit-native
+ *
+ * Validates payment amounts beyond simple maxPayment ceiling.
+ * Detects zero, negative, NaN, per-request ceiling, and spike anomalies.
+ */
+import { X402PaymentError } from "./errors.js";
+/**
+ * Recent payment amounts for spike detection.
+ * Intentionally module-level (global): all shieldedFetch instances share spike
+ * history so cross-instance spike detection catches manipulation attempts.
+ * Use resetPaymentHistory() in tests to clear between suites.
+ */
+const recentPayments = [];
+const MAX_RECENT = 20;
+/** Spike detection threshold: payment > 10x median = suspicious */
+const SPIKE_MULTIPLIER = 10n;
+/**
+ * Validate a payment amount against sanity checks.
+ *
+ * @throws X402PaymentError on invalid or suspicious amounts
+ */
+export function validatePaymentAmount(amount, config) {
+    // 1. Parse and validate
+    let parsed;
+    try {
+        parsed = BigInt(amount);
+    }
+    catch {
+        throw new X402PaymentError(`Invalid payment amount: "${amount}" is not a valid integer`);
+    }
+    // 2. Reject zero and negative
+    if (parsed <= 0n) {
+        throw new X402PaymentError(`Invalid payment amount: ${amount} must be positive`);
+    }
+    // 3. Per-request ceiling
+    if (config?.maxPaymentPerRequest !== undefined &&
+        parsed > config.maxPaymentPerRequest) {
+        throw new X402PaymentError(`Payment amount ${amount} exceeds per-request ceiling ${config.maxPaymentPerRequest}`);
+    }
+    // 4. Spike detection: if payment > 10x median of recent payments
+    if (recentPayments.length >= 3) {
+        const median = getMedian(recentPayments);
+        if (median > 0n && parsed > median * SPIKE_MULTIPLIER) {
+            throw new X402PaymentError(`Suspicious payment spike: ${amount} is > 10x the median of recent payments (${median})`);
+        }
+    }
+    return parsed;
+}
+/**
+ * Record a successful payment amount for spike detection.
+ */
+export function recordPaymentAmount(amount) {
+    recentPayments.push(amount);
+    if (recentPayments.length > MAX_RECENT) {
+        recentPayments.shift();
+    }
+}
+/**
+ * Reset the recent payments history (for testing).
+ */
+export function resetPaymentHistory() {
+    recentPayments.length = 0;
+}
+/**
+ * Get the current payment history length (for testing).
+ */
+export function getPaymentHistoryLength() {
+    return recentPayments.length;
+}
+/** Compute median of a bigint array. */
+function getMedian(arr) {
+    const sorted = [...arr].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const mid = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 0) {
+        return (sorted[mid - 1] + sorted[mid]) / 2n;
+    }
+    return sorted[mid];
+}
+//# sourceMappingURL=amount-guard.js.map

package/dist/x402/amount-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount-guard.js","sourceRoot":"","sources":["../../src/x402/amount-guard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,cAAc,GAAa,EAAE,CAAC;AACpC,MAAM,UAAU,GAAG,EAAE,CAAC;AAEtB,mEAAmE;AACnE,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAc,EACd,MAAmB;IAEnB,wBAAwB;IACxB,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,gBAAgB,CACxB,4BAA4B,MAAM,0BAA0B,CAC7D,CAAC;IACJ,CAAC;IAED,8BAA8B;IAC9B,IAAI,MAAM,IAAI,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,gBAAgB,CACxB,2BAA2B,MAAM,mBAAmB,CACrD,CAAC;IACJ,CAAC;IAED,yBAAyB;IACzB,IACE,MAAM,EAAE,oBAAoB,KAAK,SAAS;QAC1C,MAAM,GAAG,MAAM,CAAC,oBAAoB,EACpC,CAAC;QACD,MAAM,IAAI,gBAAgB,CACxB,kBAAkB,MAAM,gCAAgC,MAAM,CAAC,oBAAoB,EAAE,CACtF,CAAC;IACJ,CAAC;IAED,iEAAiE;IACjE,IAAI,cAAc,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC;QACzC,IAAI,MAAM,GAAG,EAAE,IAAI,MAAM,GAAG,MAAM,GAAG,gBAAgB,EAAE,CAAC;YACtD,MAAM,IAAI,gBAAgB,CACxB,6BAA6B,MAAM,4CAA4C,MAAM,GAAG,CACzF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,IAAI,cAAc,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;QACvC,cAAc,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB;IACjC,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,cAAc,CAAC,MAAM,CAAC;AAC/B,CAAC;AAED,wCAAwC;AACxC,SAAS,SAAS,CAAC,GAAa;IAC9B,MAAM,MAAM,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC1C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;IAC9C,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC"}

package/dist/x402/audit-trail.d.ts

@@ -0,0 +1,26 @@
+/**
+ * x402 Audit Trail — Kit-native
+ *
+ * Structured X402PaymentEvent emitter.
+ * Calls config.onPayment() if configured.
+ */
+import type { X402Config, X402PaymentEvent, SettleResponse } from "./types.js";
+/**
+ * Emit a structured payment event through the audit callback.
+ */
+export declare function emitPaymentEvent(config: X402Config | undefined, event: X402PaymentEvent): void;
+/**
+ * Create a payment event from the flow parameters.
+ */
+export declare function createPaymentEvent(params: {
+    url: string;
+    payTo: string;
+    asset: string;
+    amount: string;
+    paid: boolean;
+    deniedReason?: string;
+    settlement?: SettleResponse;
+    startTime: number;
+    nonce?: string;
+}): X402PaymentEvent;
+//# sourceMappingURL=audit-trail.d.ts.map

package/dist/x402/audit-trail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-trail.d.ts","sourceRoot":"","sources":["../../src/x402/audit-trail.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE/E;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,KAAK,EAAE,gBAAgB,GACtB,IAAI,CAIN;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,gBAAgB,CAanB"}

package/dist/x402/audit-trail.js

@@ -0,0 +1,32 @@
+/**
+ * x402 Audit Trail — Kit-native
+ *
+ * Structured X402PaymentEvent emitter.
+ * Calls config.onPayment() if configured.
+ */
+/**
+ * Emit a structured payment event through the audit callback.
+ */
+export function emitPaymentEvent(config, event) {
+    if (config?.onPayment) {
+        config.onPayment(event);
+    }
+}
+/**
+ * Create a payment event from the flow parameters.
+ */
+export function createPaymentEvent(params) {
+    return {
+        timestamp: Date.now(),
+        url: params.url,
+        payTo: params.payTo,
+        asset: params.asset,
+        amount: params.amount,
+        paid: params.paid,
+        deniedReason: params.deniedReason,
+        settlement: params.settlement,
+        nonce: params.nonce,
+        durationMs: Date.now() - params.startTime,
+    };
+}
+//# sourceMappingURL=audit-trail.js.map

package/dist/x402/audit-trail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-trail.js","sourceRoot":"","sources":["../../src/x402/audit-trail.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAA8B,EAC9B,KAAuB;IAEvB,IAAI,MAAM,EAAE,SAAS,EAAE,CAAC;QACtB,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAUlC;IACC,OAAO;QACL,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS;KAC1C,CAAC;AACJ,CAAC"}