safehands-pharos 1.4.0 → 2.6.0

package/dist/lib/signer/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/signer/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAGpC,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,UAAU,CAAC;AAC7F,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,aAAa,CAAC;AAE3D,wBAAgB,eAAe,CAAC,CAAC,EAAE,eAAe,GAAG,CAAC,IAAI,aAAa,CAEtE;AAqDD;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,aAAa,CAAA;CAAO,GACxC,OAAO,CAAC,eAAe,CAAC,CA0B1B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/signer/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAIpC,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,UAAU,CAAC;AAC7F,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,aAAa,CAAC;AAE3D,wBAAgB,eAAe,CAAC,CAAC,EAAE,eAAe,GAAG,CAAC,IAAI,aAAa,CAEtE;AAmED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,aAAa,CAAA;CAAO,GACxC,OAAO,CAAC,eAAe,CAAC,CAmC1B"}

package/dist/lib/signer/index.js

@@ -1,89 +1,111 @@
-// ─── SignerProvider ─────────────────────────────────────────────────────
-// Abstraction layer for signing. Tools never read process.env.PRIVATE_KEY
-// directly — they request a signer through this provider.
-// ────────────────────────────────────────────────────────────────────────
-import { privateKeyToAccount } from "viem/accounts";
-import { walletStore, decryptKey, getEffectiveEncryptionKey } from "../wallet/index.js";
-export function isSignerFailure(r) {
-    return "error" in r;
-}
-function normalizePrivateKey(pk) {
-    return (pk.startsWith("0x") ? pk : `0x${pk}`);
-}
-function accountFromEnvKey(envName, mode) {
-    const pk = process.env[envName];
-    if (!pk)
-        return null;
-    try {
-        const account = privateKeyToAccount(normalizePrivateKey(pk));
-        return { account, address: account.address, mode };
-    }
-    catch {
-        return {
-            error: {
-                code: "INVALID_PRIVATE_KEY",
-                message: `${envName} is not a valid private key.`,
-            },
-        };
-    }
-}
-async function accountFromManagedWallet(agentId) {
-    const walletMode = process.env.WALLET_MODE || "none";
-    if (walletMode !== "managed-testnet" || !agentId)
-        return null;
-    if (process.env.WALLET_STORE_PATH && !process.env.WALLET_ENCRYPTION_KEY) {
-        return {
-            error: {
-                code: "WALLET_ENCRYPTION_KEY_REQUIRED",
-                message: "WALLET_ENCRYPTION_KEY is required when WALLET_STORE_PATH is used for persistent managed-testnet wallets.",
-            },
-        };
-    }
-    const stored = await walletStore.get(agentId);
-    if (!stored)
-        return null;
-    try {
-        const privateKey = decryptKey(stored.encryptedKey, getEffectiveEncryptionKey());
-        const account = privateKeyToAccount(normalizePrivateKey(privateKey));
-        return { account, address: account.address, mode: "managed-testnet" };
-    }
-    catch {
-        return {
-            error: {
-                code: "NO_SIGNER_AVAILABLE",
-                message: "Managed wallet key could not be decrypted for signing. Check WALLET_ENCRYPTION_KEY matches the key used when the wallet was created.",
-            },
-        };
-    }
-}
-/**
- * Get a signer for write/payment operations.
- * Priority for x402: managed wallet > X402_SIGNER_PRIVATE_KEY > PRIVATE_KEY fallback.
- * Priority for writes: managed wallet > PRIVATE_KEY fallback.
- */
-export async function getSigner(agentId, options = {}) {
-    const purpose = options.purpose || "write";
-    const managed = await accountFromManagedWallet(agentId);
-    if (managed)
-        return managed;
-    if (purpose === "x402") {
-        const x402Env = accountFromEnvKey("X402_SIGNER_PRIVATE_KEY", "x402-env");
-        if (x402Env)
-            return x402Env;
-    }
-    const walletMode = process.env.WALLET_MODE || "none";
-    if (walletMode === "env" || process.env.PRIVATE_KEY) {
-        const env = accountFromEnvKey("PRIVATE_KEY", "env");
-        if (env)
-            return env;
-    }
-    return {
-        error: {
-            code: "NO_SIGNER_AVAILABLE",
-            message: purpose === "x402"
-                ? "No x402 signer available. Use WALLET_MODE=managed-testnet with agentId, X402_SIGNER_PRIVATE_KEY, or PRIVATE_KEY as testnet developer fallback."
-                : "No signer available. Use WALLET_MODE=managed-testnet with agentId, or WALLET_MODE=env with PRIVATE_KEY for testnet developer mode.",
-        },
-    };
-}
+// ─── SignerProvider ─────────────────────────────────────────────────────
+// Abstraction layer for signing. Tools never read process.env.PRIVATE_KEY
+// directly — they request a signer through this provider.
+// ────────────────────────────────────────────────────────────────────────
+import { privateKeyToAccount } from "viem/accounts";
+import { walletStore, decryptKey, getEffectiveEncryptionKey } from "../wallet/index.js";
+import { managedWalletEnabled } from "../config.js";
+export function isSignerFailure(r) {
+    return "error" in r;
+}
+function normalizePrivateKey(pk) {
+    return (pk.startsWith("0x") ? pk : `0x${pk}`);
+}
+function accountFromEnvKey(envName, mode) {
+    const pk = process.env[envName];
+    if (!pk)
+        return null;
+    try {
+        const account = privateKeyToAccount(normalizePrivateKey(pk));
+        return { account, address: account.address, mode };
+    }
+    catch {
+        return {
+            error: {
+                code: "INVALID_PRIVATE_KEY",
+                message: `${envName} is not a valid private key.`,
+            },
+        };
+    }
+}
+async function accountFromManagedWallet(agentId) {
+    const walletMode = process.env.WALLET_MODE || "none";
+    if (walletMode !== "managed-mainnet" || !agentId)
+        return null;
+    // Managed custody must be explicitly opted into. WALLET_MODE=managed-mainnet
+    // selects the signer source; MANAGED_WALLET_ENABLED=true is the required second
+    // gate (mirrors the MCP bootstrap gate + capability flags). Without it the stored
+    // managed wallet is NEVER used to sign — fail closed with a clear reason.
+    if (!managedWalletEnabled()) {
+        return {
+            error: {
+                code: "MANAGED_WALLET_DISABLED",
+                message: "Managed-wallet signing requires MANAGED_WALLET_ENABLED=true in addition to WALLET_MODE=managed-mainnet. Enable it only for trusted managed execution.",
+            },
+        };
+    }
+    if (process.env.WALLET_STORE_PATH && !process.env.WALLET_ENCRYPTION_KEY) {
+        return {
+            error: {
+                code: "WALLET_ENCRYPTION_KEY_REQUIRED",
+                message: "WALLET_ENCRYPTION_KEY is required when WALLET_STORE_PATH is used for persistent managed-mainnet wallets.",
+            },
+        };
+    }
+    const stored = await walletStore.get(agentId);
+    if (!stored)
+        return null;
+    try {
+        const privateKey = decryptKey(stored.encryptedKey, getEffectiveEncryptionKey());
+        const account = privateKeyToAccount(normalizePrivateKey(privateKey));
+        return { account, address: account.address, mode: "managed-mainnet" };
+    }
+    catch {
+        return {
+            error: {
+                code: "NO_SIGNER_AVAILABLE",
+                message: "Managed wallet key could not be decrypted for signing. Check WALLET_ENCRYPTION_KEY matches the key used when the wallet was created.",
+            },
+        };
+    }
+}
+/**
+ * Get a signer for write/payment operations.
+ * Priority for x402: managed wallet > X402_SIGNER_PRIVATE_KEY > PRIVATE_KEY when WALLET_MODE=env.
+ * Priority for writes: managed wallet > PRIVATE_KEY only when WALLET_MODE=env.
+ */
+export async function getSigner(agentId, options = {}) {
+    const purpose = options.purpose || "write";
+    // x402 is permissionless-first: prefer the agent's OWN x402 signer
+    // (self-custody — no SafeHandsRegistry authorization required) over the
+    // managed/custodial wallet. To route x402 through the managed wallet instead,
+    // simply leave X402_SIGNER_PRIVATE_KEY unset.
+    if (purpose === "x402") {
+        const x402Env = accountFromEnvKey("X402_SIGNER_PRIVATE_KEY", "x402-env");
+        if (x402Env)
+            return x402Env;
+    }
+    const managed = await accountFromManagedWallet(agentId);
+    if (managed)
+        return managed;
+    if (!agentId && (process.env.WALLET_MODE === "managed-mainnet")) {
+        const defaultManaged = await accountFromManagedWallet("default");
+        if (defaultManaged)
+            return defaultManaged;
+    }
+    const walletMode = process.env.WALLET_MODE || "none";
+    if (walletMode === "env") {
+        const env = accountFromEnvKey("PRIVATE_KEY", "env");
+        if (env)
+            return env;
+    }
+    return {
+        error: {
+            code: "NO_SIGNER_AVAILABLE",
+            message: purpose === "x402"
+                ? "No x402 signer available. Use WALLET_MODE=managed-mainnet with agentId, X402_SIGNER_PRIVATE_KEY, or PRIVATE_KEY in explicit local self-hosted mode."
+                : "No signer available. Use WALLET_MODE=managed-mainnet with agentId, or WALLET_MODE=env with PRIVATE_KEY for explicit local self-hosted mode.",
+        },
+    };
+}
 //# sourceMappingURL=index.js.map

package/dist/lib/signer/index.js.map

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

package/dist/lib/spendAccumulator.d.ts

@@ -1,5 +1,13 @@
 export declare function getMaxDailySpendUsd(): number;
-export declare function estimateUsd(amount: string, token: "PHRS" | "USDC" | "USDT" | string): number;
+export type PriceableSpendToken = "PROS" | "WPROS" | "USDC" | "USDT";
+/**
+ * Resolve a token symbol OR address to a priceable spend token, or `null` when the
+ * token cannot be priced in USD. Addresses are matched against the official
+ * active-network token registry so registry USDC passed by address still counts
+ * toward the caps instead of slipping past them.
+ */
+export declare function resolvePriceableToken(token: string): PriceableSpendToken | null;
+export declare function estimateUsd(amount: string, token: "PROS" | "USDC" | "USDT" | string): number;
 export declare function checkDailyLimit(walletAddress: string, amountUsd: number): {
     allowed: boolean;
     currentUsd: number;
@@ -7,4 +15,19 @@ export declare function checkDailyLimit(walletAddress: string, amountUsd: number
     remainingUsd: number;
 };
 export declare function recordSpend(walletAddress: string, amountUsd: number): void;
+/**
+ * Atomic check-and-reserve. `checkDailyLimit` + `recordSpend` run with NO
+ * `await` between them, so within Node's single-threaded event loop the reserve is
+ * atomic: two concurrent tool calls can no longer both pass the cap by reading the
+ * pre-spend bucket. Reserve immediately BEFORE broadcasting, then `releaseReservation`
+ * on any failure so a reverted/failed tx does not permanently consume the cap.
+ */
+export declare function reserveDailyLimit(walletAddress: string, amountUsd: number): {
+    allowed: boolean;
+    currentUsd: number;
+    limitUsd: number;
+    remainingUsd: number;
+};
+/** Release a previously reserved amount (call when a reserved tx fails/reverts). */
+export declare function releaseReservation(walletAddress: string, amountUsd: number): void;
 //# sourceMappingURL=spendAccumulator.d.ts.map

package/dist/lib/spendAccumulator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spendAccumulator.d.ts","sourceRoot":"","sources":["../../src/lib/spendAccumulator.ts"],"names":[],"mappings":"AAqBA,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAO5F;AAED,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAalF;AAED,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAU1E"}
+{"version":3,"file":"spendAccumulator.d.ts","sourceRoot":"","sources":["../../src/lib/spendAccumulator.ts"],"names":[],"mappings":"AA6CA,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAErE;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAY/E;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAS5F;AAED,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAalF;AAED,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAW1E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAMlF;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAQjF"}

package/dist/lib/spendAccumulator.js

@@ -1,28 +1,72 @@
 // ─── Daily Spend Accumulator ────────────────────────────────────────────
 // In-memory per-wallet daily spend tracker. Resets at UTC midnight.
 // Enforces MAX_DAILY_SPEND_USD across sendPayment and executeSwap.
-// PHRS → USD conversion uses PHRS_USD_PRICE env var (default 1.0).
+// PROS/WPROS → USD conversion uses PROS_USD_PRICE env var (default 1.0).
 // ────────────────────────────────────────────────────────────────────────
+import path from "path";
+import { readJsonFile, writeJsonFileAtomic } from "./persistentJsonStore.js";
+import { activeTokenMap } from "./constants.js";
 const buckets = new Map();
+const SPEND_FILE = process.env.SAFEHANDS_SPEND_HISTORY_PATH || path.join(process.env.SAFEHANDS_STATE_DIR || process.env.STATE_DIR || ".safehands", "spend_history.json");
+function loadBuckets() {
+    const data = readJsonFile(SPEND_FILE, {});
+    for (const [k, v] of Object.entries(data)) {
+        buckets.set(k, v);
+    }
+}
+function saveBuckets() {
+    try {
+        // Atomic write (temp file + rename) — a crash mid-write can no longer
+        // truncate the spend history and silently reset the daily caps.
+        writeJsonFileAtomic(SPEND_FILE, Object.fromEntries(buckets));
+    }
+    catch (e) {
+        console.error("Failed to save spend history:", e);
+    }
+}
+loadBuckets();
 function todayUtc() {
     return new Date().toISOString().slice(0, 10);
 }
 function getPhrsUsdPrice() {
-    return parseFloat(process.env.PHRS_USD_PRICE || "1.0");
+    return parseFloat(process.env.PROS_USD_PRICE || "1.0");
 }
 export function getMaxDailySpendUsd() {
     return parseFloat(process.env.MAX_DAILY_SPEND_USD || "10");
 }
+/**
+ * Resolve a token symbol OR address to a priceable spend token, or `null` when the
+ * token cannot be priced in USD. Addresses are matched against the official
+ * active-network token registry so registry USDC passed by address still counts
+ * toward the caps instead of slipping past them.
+ */
+export function resolvePriceableToken(token) {
+    const trimmed = token.trim();
+    const upper = trimmed.toUpperCase();
+    if (upper === "PROS" || upper === "WPROS" || upper === "USDC" || upper === "USDT")
+        return upper;
+    const lower = trimmed.toLowerCase();
+    for (const [symbol, addr] of Object.entries(activeTokenMap())) {
+        if (typeof addr === "string" && addr.toLowerCase() === lower) {
+            const s = symbol.toUpperCase();
+            if (s === "PROS" || s === "WPROS" || s === "USDC" || s === "USDT")
+                return s;
+        }
+    }
+    return null;
+}
 export function estimateUsd(amount, token) {
     const n = parseFloat(amount);
     if (isNaN(n))
         return 0;
-    const upper = token.toUpperCase();
-    if (upper === "PHRS")
+    const resolved = resolvePriceableToken(token);
+    if (resolved === "PROS" || resolved === "WPROS")
         return n * getPhrsUsdPrice();
-    if (upper === "USDC" || upper === "USDT")
+    if (resolved === "USDC" || resolved === "USDT")
         return n;
-    return 0; // unknown token — do not count to avoid false blocks
+    // Unpriceable token — the policy engine DENIES execute_swap on these upstream
+    // (swap_notional_unpriceable → BLOCK), so this 0 is never a silent cap escape.
+    return 0;
 }
 export function checkDailyLimit(walletAddress, amountUsd) {
     const key = walletAddress.toLowerCase();
@@ -50,5 +94,31 @@ export function recordSpend(walletAddress, amountUsd) {
     else {
         bucket.totalUsd += amountUsd;
     }
+    saveBuckets();
+}
+/**
+ * Atomic check-and-reserve. `checkDailyLimit` + `recordSpend` run with NO
+ * `await` between them, so within Node's single-threaded event loop the reserve is
+ * atomic: two concurrent tool calls can no longer both pass the cap by reading the
+ * pre-spend bucket. Reserve immediately BEFORE broadcasting, then `releaseReservation`
+ * on any failure so a reverted/failed tx does not permanently consume the cap.
+ */
+export function reserveDailyLimit(walletAddress, amountUsd) {
+    const check = checkDailyLimit(walletAddress, amountUsd);
+    if (check.allowed && amountUsd > 0) {
+        recordSpend(walletAddress, amountUsd);
+    }
+    return check;
+}
+/** Release a previously reserved amount (call when a reserved tx fails/reverts). */
+export function releaseReservation(walletAddress, amountUsd) {
+    if (amountUsd <= 0)
+        return;
+    const key = walletAddress.toLowerCase();
+    const bucket = buckets.get(key);
+    if (bucket && bucket.dateUtc === todayUtc()) {
+        bucket.totalUsd = Math.max(0, bucket.totalUsd - amountUsd);
+        saveBuckets();
+    }
 }
 //# sourceMappingURL=spendAccumulator.js.map

package/dist/lib/spendAccumulator.js.map

@@ -1 +1 @@
-{"version":3,"file":"spendAccumulator.js","sourceRoot":"","sources":["../../src/lib/spendAccumulator.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,oEAAoE;AACpE,mEAAmE;AACnE,mEAAmE;AACnE,2EAA2E;AAO3E,MAAM,OAAO,GAAG,IAAI,GAAG,EAAqB,CAAC;AAE7C,SAAS,QAAQ;IACf,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,eAAe;IACtB,OAAO,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,KAAK,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,IAAI,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,KAAwC;IAClF,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAC7B,IAAI,KAAK,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACvB,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAClC,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,CAAC,GAAG,eAAe,EAAE,CAAC;IACnD,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,CAAC,CAAC;IACnD,OAAO,CAAC,CAAC,CAAC,qDAAqD;AACjE,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,aAAqB,EACrB,SAAiB;IAEjB,MAAM,GAAG,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC;IACxC,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,UAAU,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC7E,MAAM,QAAQ,GAAG,mBAAmB,EAAE,CAAC;IACvC,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC,CAAC;IACxD,OAAO;QACL,OAAO,EAAE,UAAU,GAAG,SAAS,IAAI,QAAQ;QAC3C,UAAU;QACV,QAAQ;QACR,YAAY;KACb,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,aAAqB,EAAE,SAAiB;IAClE,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO;IAC3B,MAAM,GAAG,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC;IACxC,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;IAC5D,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,QAAQ,IAAI,SAAS,CAAC;IAC/B,CAAC;AACH,CAAC"}
+{"version":3,"file":"spendAccumulator.js","sourceRoot":"","sources":["../../src/lib/spendAccumulator.ts"],"names":[],"mappings":"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"}

package/dist/lib/toolResponse.d.ts

@@ -1,26 +1,31 @@
-export interface ToolError {
-    code: string;
-    message: string;
-    retryable: boolean;
-    source?: string;
-}
-export interface ToolSuccess<T> {
-    success: true;
-    data: T;
-    error: null;
-    timestamp: string;
-}
-export interface ToolFailure {
-    success: false;
-    data: null;
-    error: ToolError;
-    timestamp: string;
-}
-export type ToolResponse<T> = ToolSuccess<T> | ToolFailure;
-export declare function ok<T>(data: T, timestamp?: string): ToolSuccess<T>;
-export declare function fail(code: string, message: string, retryable?: boolean, source?: string, timestamp?: string): ToolFailure;
-export declare function errorMessage(err: unknown): string;
-export declare function classifyExternalError(source: string, err: unknown): ToolFailure;
-export declare function requireWriteToolsEnabled(toolName: string): ToolFailure | null;
-export declare function requireEnv(name: string, source: string): string | ToolFailure;
+export interface ToolError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    source?: string;
+}
+export interface ToolSuccess<T> {
+    success: true;
+    data: T;
+    error: null;
+    timestamp: string;
+}
+export interface ToolFailure {
+    success: false;
+    data: null;
+    error: ToolError;
+    timestamp: string;
+}
+export type ToolResponse<T> = ToolSuccess<T> | ToolFailure;
+export declare function ok<T>(data: T, timestamp?: string): ToolSuccess<T>;
+export declare function fail(code: string, message: string, retryable?: boolean, source?: string, timestamp?: string): ToolFailure;
+export declare function errorMessage(err: unknown): string;
+/**
+ * In production, never echo raw internal error text (DODO/RPC/viem internals) to
+ * clients — return a generic message instead. Outside production, keep the real
+ * message for debuggability. (`/paid/*` + `/tools/*` info-leak fix.)
+ */
+export declare function productionSafeMessage(message: string, fallback?: string): string;
+export declare function classifyExternalError(source: string, err: unknown): ToolFailure;
+export declare function requireWriteToolsEnabled(toolName: string): ToolFailure | null;
 //# sourceMappingURL=toolResponse.d.ts.map

package/dist/lib/toolResponse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolResponse.d.ts","sourceRoot":"","sources":["../../src/lib/toolResponse.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,IAAI,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,KAAK,CAAC;IACf,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC;AAE3D,wBAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,SAA2B,GAAG,WAAW,CAAC,CAAC,CAAC,CAEnF;AAED,wBAAgB,IAAI,CAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,UAAQ,EACjB,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,SAA2B,GACnC,WAAW,CAOb;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAEjD;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,WAAW,CAqB/E;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAU7E;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,CAM7E"}
+{"version":3,"file":"toolResponse.d.ts","sourceRoot":"","sources":["../../src/lib/toolResponse.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,IAAI,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,KAAK,CAAC;IACf,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC;AAE3D,wBAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,SAA2B,GAAG,WAAW,CAAC,CAAC,CAAC,CAEnF;AAED,wBAAgB,IAAI,CAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,UAAQ,EACjB,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,SAA2B,GACnC,WAAW,CAOb;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAoE,GAAG,MAAM,CAE3I;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,WAAW,CAwB/E;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAU7E"}

package/dist/lib/toolResponse.js

@@ -1,54 +1,58 @@
-// ─── Structured Tool Responses ─────────────────────────────────────────
-// Shared response helpers so MCP tools are predictable for AI agents.
-export function ok(data, timestamp = new Date().toISOString()) {
-    return { success: true, data, error: null, timestamp };
-}
-export function fail(code, message, retryable = false, source, timestamp = new Date().toISOString()) {
-    return {
-        success: false,
-        data: null,
-        error: { code, message, retryable, ...(source ? { source } : {}) },
-        timestamp,
-    };
-}
-export function errorMessage(err) {
-    return err instanceof Error ? err.message : String(err);
-}
-export function classifyExternalError(source, err) {
-    const message = errorMessage(err);
-    const lower = message.toLowerCase();
-    const isTimeout = lower.includes("timeout") || lower.includes("aborted");
-    const isRetryable = isTimeout ||
-        lower.includes("fetch failed") ||
-        lower.includes("network") ||
-        lower.includes("503") ||
-        lower.includes("502") ||
-        lower.includes("504") ||
-        lower.includes("429");
-    let code = "EXTERNAL_SERVICE_UNAVAILABLE";
-    if (source === "pharos_rpc")
-        code = isTimeout ? "RPC_TIMEOUT" : "RPC_UNAVAILABLE";
-    if (source === "dodo_api")
-        code = isTimeout ? "DODO_API_TIMEOUT" : "DODO_API_UNAVAILABLE";
-    if (source === "faroswap_api")
-        code = isTimeout ? "FAROSWAP_API_TIMEOUT" : "FAROSWAP_API_UNAVAILABLE";
-    if (source === "goplus_api")
-        code = isTimeout ? "GOPLUS_API_TIMEOUT" : "GOPLUS_API_UNAVAILABLE";
-    if (source === "x402_fetch")
-        code = isTimeout ? "X402_FETCH_TIMEOUT" : "X402_FETCH_FAILED";
-    return fail(code, message, isRetryable, source);
-}
-export function requireWriteToolsEnabled(toolName) {
-    if (process.env.WRITE_TOOLS_ENABLED !== "true") {
-        return fail("WRITE_TOOLS_DISABLED", `${toolName} is disabled by default. Set WRITE_TOOLS_ENABLED=true only for trusted testnet execution.`, false, toolName);
-    }
-    return null;
-}
-export function requireEnv(name, source) {
-    const value = process.env[name];
-    if (!value) {
-        return fail("MISSING_ENV", `${name} is not configured.`, false, source);
-    }
-    return value;
-}
+// ─── Structured Tool Responses ─────────────────────────────────────────
+// Shared response helpers so MCP tools are predictable for AI agents.
+export function ok(data, timestamp = new Date().toISOString()) {
+    return { success: true, data, error: null, timestamp };
+}
+export function fail(code, message, retryable = false, source, timestamp = new Date().toISOString()) {
+    return {
+        success: false,
+        data: null,
+        error: { code, message, retryable, ...(source ? { source } : {}) },
+        timestamp,
+    };
+}
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * In production, never echo raw internal error text (DODO/RPC/viem internals) to
+ * clients — return a generic message instead. Outside production, keep the real
+ * message for debuggability. (`/paid/*` + `/tools/*` info-leak fix.)
+ */
+export function productionSafeMessage(message, fallback = "Request could not be processed. Check parameters and try again.") {
+    return (process.env.NODE_ENV || "").toLowerCase() === "production" ? fallback : message;
+}
+export function classifyExternalError(source, err) {
+    const message = errorMessage(err);
+    const lower = message.toLowerCase();
+    const isTimeout = lower.includes("timeout") || lower.includes("aborted");
+    const isRetryable = isTimeout ||
+        lower.includes("fetch failed") ||
+        lower.includes("network") ||
+        lower.includes("503") ||
+        lower.includes("502") ||
+        lower.includes("504") ||
+        lower.includes("429");
+    let code = "EXTERNAL_SERVICE_UNAVAILABLE";
+    if (source === "pharos_rpc")
+        code = isTimeout ? "RPC_TIMEOUT" : "RPC_UNAVAILABLE";
+    if (source === "dodo_api")
+        code = isTimeout ? "DODO_API_TIMEOUT" : "DODO_API_UNAVAILABLE";
+    if (source === "faroswap_api")
+        code = isTimeout ? "FAROSWAP_API_TIMEOUT" : "FAROSWAP_API_UNAVAILABLE";
+    if (source === "goplus_api")
+        code = isTimeout ? "GOPLUS_API_TIMEOUT" : "GOPLUS_API_UNAVAILABLE";
+    if (source === "x402_fetch")
+        code = isTimeout ? "X402_FETCH_TIMEOUT" : "X402_FETCH_FAILED";
+    // In production, never echo raw DODO/RPC/viem internals to the caller — keep
+    // the specific error CODE (RPC_TIMEOUT, DODO_API_UNAVAILABLE, …) but genericize the
+    // human message. Outside production the real message is retained for debuggability.
+    return fail(code, productionSafeMessage(message), isRetryable, source);
+}
+export function requireWriteToolsEnabled(toolName) {
+    if (process.env.WRITE_TOOLS_ENABLED !== "true") {
+        return fail("WRITE_TOOLS_DISABLED", `${toolName} is disabled by default. Set WRITE_TOOLS_ENABLED=true only for trusted mainnet execution.`, false, toolName);
+    }
+    return null;
+}
 //# sourceMappingURL=toolResponse.js.map

package/dist/lib/toolResponse.js.map

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

package/dist/lib/validation.d.ts

@@ -0,0 +1,7 @@
+export declare function isValidPositiveAmount(value: unknown): boolean;
+export declare function validatePositiveAmount(value: unknown, fieldName: string): string | null;
+export declare function validateAddress(value: unknown, fieldName: string): string | null;
+export declare function validateNonZeroAddress(value: unknown, fieldName: string): string | null;
+export declare function validateTokenIdentifier(value: unknown, fieldName: string): string | null;
+export declare function collectErrors(errors: (string | null)[]): string[];
+//# sourceMappingURL=validation.d.ts.map

package/dist/lib/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/lib/validation.ts"],"names":[],"mappings":"AAOA,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM7D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUvF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOhF;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOvF;AAID,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQxF;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,CAEjE"}