safehands-pharos 1.5.0 → 2.8.0

package/dist/lib/riskInclusion.js

@@ -0,0 +1,252 @@
+// ─── L1 Merkle inclusion read-path ─────────────────────────────────────
+// The keyless consumer that closes the L1 on-chain-memory loop. commitRiskRoot
+// publishes a Merkle root (on-chain) + a data-availability pointer to the batch
+// JSON (off-chain). This module reads that root, fetches the batch, and proves a
+// single risk record is included — both locally and, for trustlessness, through
+// the contract's own verifyRiskRecord view. No private key is ever touched: this
+// is a pure read/verify path, safe for the zero-custody public profile.
+// ────────────────────────────────────────────────────────────────────────
+import { isAddress, keccak256 } from "viem";
+import { MerkleTree } from "merkletreejs";
+import { publicClient } from "./pharosClient.js";
+import { fetchWithTimeoutAndRetry } from "./http.js";
+import { buildMerkleTree, computeRiskLeaf } from "./merkleBatcher.js";
+import { SAFEHANDS_REGISTRY_ADDRESS, SAFEHANDS_REGISTRY_ABI } from "./constants.js";
+const ZERO_ROOT = "0x0000000000000000000000000000000000000000000000000000000000000000";
+function registryAddress() {
+    return SAFEHANDS_REGISTRY_ADDRESS && isAddress(SAFEHANDS_REGISTRY_ADDRESS)
+        ? SAFEHANDS_REGISTRY_ADDRESS
+        : null;
+}
+/** Coerce expiresAt from any serialized form ("123n" suffixed, numeric string, number, bigint). */
+function toBigInt(value) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number")
+        return BigInt(Math.trunc(value));
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        const digits = /n$/.test(trimmed) ? trimmed.slice(0, -1) : trimmed;
+        if (/^\d+$/.test(digits))
+            return BigInt(digits);
+    }
+    return 0n;
+}
+/**
+ * Normalize the DA batch JSON into typed RiskRecordInput[]. The writer may
+ * serialize expiresAt as a bigint-tagged string or a plain number, so we coerce
+ * defensively rather than trusting a single encoding.
+ */
+export function normalizeRiskRecords(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((r) => r && typeof r === "object")
+        .map((r) => ({
+        target: String(r.target ?? ""),
+        actionHash: String(r.actionHash ?? ""),
+        score: Number(r.score ?? 0),
+        level: Number(r.level ?? 0),
+        recommendation: Number(r.recommendation ?? 0),
+        policyVersionHash: String(r.policyVersionHash ?? ""),
+        evidenceHash: String(r.evidenceHash ?? ""),
+        expiresAt: toBigInt(r.expiresAt),
+    }));
+}
+/**
+ * Pure inclusion proof: find the record matching `match` in `records`, rebuild
+ * the tree, and produce the Merkle proof for its leaf. No network, no chain —
+ * fully unit-testable. Returns null when no record matches.
+ */
+export function proveInclusion(records, match) {
+    const target = match.target.toLowerCase();
+    const actionHash = match.actionHash?.toLowerCase();
+    const record = records.find((r) => r.target.toLowerCase() === target &&
+        (actionHash === undefined || r.actionHash.toLowerCase() === actionHash));
+    if (!record)
+        return null;
+    const tree = buildMerkleTree(records);
+    const leaf = computeRiskLeaf(record);
+    const proof = tree.getHexProof(leaf);
+    const computedRoot = tree.getHexRoot();
+    const verifiedLocal = MerkleTree.verify(proof, leaf, computedRoot, keccak256, { sortPairs: true });
+    return { record, leaf, proof, computedRoot, verifiedLocal };
+}
+function neutral(partial) {
+    return {
+        configured: false,
+        committed: false,
+        onchainMerkleRoot: null,
+        dataURI: null,
+        found: false,
+        rootMatches: false,
+        verifiedLocal: false,
+        verifiedOnchain: null,
+        expired: false,
+        proof: null,
+        record: null,
+        source: "unconfigured",
+        ...partial,
+    };
+}
+async function fetchBatch(dataURI) {
+    if (!/^https?:\/\//i.test(dataURI)) {
+        throw new Error(`Unsupported data-availability URI scheme: ${dataURI}. Only http(s) batch pointers are resolvable by this read-path.`);
+    }
+    // dataURI is operator-controlled (read from chain), so fetch through the
+    // SSRF-guarded layer (DNS-pinned lookup, blocked internal ranges, redirect
+    // re-validation) — a malicious/compromised operator must not be able to point
+    // this read-path at internal endpoints. The Merkle-root comparison downstream
+    // already detects content tampering; this guards the request itself.
+    const res = await fetchWithTimeoutAndRetry(dataURI, { timeoutMs: 10_000, retries: 0 });
+    if (!res.ok)
+        throw new Error(`DA fetch failed: HTTP ${res.status} for ${dataURI}`);
+    return res.json();
+}
+/**
+ * End-to-end keyless inclusion check for a target's risk record against the
+ * currently committed on-chain Merkle root. Fail-closed and neutral on every
+ * missing precondition (unconfigured, uncommitted, unreachable DA, not found).
+ * When `verifyOnchain` is true (default) it additionally calls the contract's
+ * verifyRiskRecord view so the "yes, this verdict is in the on-chain root" claim
+ * is proven trustlessly rather than only in-process.
+ */
+export async function verifyRiskInclusion(match, opts = {}) {
+    // An explicit registryAddress override (incl. "") lets callers/tests exercise the
+    // fail-closed branch deterministically without touching env or the network.
+    const address = opts.registryAddress !== undefined
+        ? (opts.registryAddress && isAddress(opts.registryAddress) ? opts.registryAddress : null)
+        : registryAddress();
+    if (!address) {
+        return neutral({ source: "unconfigured", error: "SAFEHANDS_REGISTRY_ADDRESS not configured." });
+    }
+    let onchainMerkleRoot;
+    let dataURI;
+    try {
+        [onchainMerkleRoot, dataURI] = (await Promise.all([
+            publicClient.readContract({ address, abi: SAFEHANDS_REGISTRY_ABI, functionName: "currentMerkleRoot", args: [] }),
+            publicClient.readContract({ address, abi: SAFEHANDS_REGISTRY_ABI, functionName: "currentDataURI", args: [] }),
+        ]));
+    }
+    catch (err) {
+        return neutral({ configured: true, source: "error", error: `Registry read failed: ${err.message}` });
+    }
+    if (!onchainMerkleRoot || onchainMerkleRoot === ZERO_ROOT) {
+        return neutral({ configured: true, onchainMerkleRoot, dataURI, source: "not-committed" });
+    }
+    let records;
+    try {
+        records = normalizeRiskRecords(await fetchBatch(dataURI));
+    }
+    catch (err) {
+        return neutral({
+            configured: true,
+            committed: true,
+            onchainMerkleRoot,
+            dataURI,
+            source: "error",
+            error: err.message,
+        });
+    }
+    const proven = proveInclusion(records, match);
+    if (!proven) {
+        return neutral({
+            configured: true,
+            committed: true,
+            onchainMerkleRoot,
+            dataURI,
+            source: "not-found",
+        });
+    }
+    const rootMatches = proven.computedRoot.toLowerCase() === onchainMerkleRoot.toLowerCase();
+    const now = BigInt(Math.floor(Date.now() / 1000));
+    const expired = proven.record.expiresAt !== 0n && proven.record.expiresAt < now;
+    const record = {
+        target: proven.record.target,
+        actionHash: proven.record.actionHash,
+        score: proven.record.score,
+        level: proven.record.level,
+        recommendation: proven.record.recommendation,
+        policyVersionHash: proven.record.policyVersionHash,
+        evidenceHash: proven.record.evidenceHash,
+        expiresAt: proven.record.expiresAt === 0n ? "never" : proven.record.expiresAt.toString(),
+    };
+    // If the batch we fetched does not hash to the committed root, the DA content is
+    // stale or tampered — the proof is meaningless. Fail loudly rather than half-pass.
+    if (!rootMatches) {
+        return {
+            ...neutral({}),
+            configured: true,
+            committed: true,
+            onchainMerkleRoot,
+            dataURI,
+            found: true,
+            rootMatches: false,
+            verifiedLocal: proven.verifiedLocal,
+            verifiedOnchain: null,
+            expired,
+            proof: proven.proof,
+            record,
+            source: "root-mismatch",
+            error: "Recomputed batch root does not match the on-chain committed root (stale or tampered data availability).",
+        };
+    }
+    let verifiedOnchain = null;
+    const shouldVerifyOnchain = opts.verifyOnchain !== false;
+    if (shouldVerifyOnchain) {
+        try {
+            verifiedOnchain = (await publicClient.readContract({
+                address,
+                abi: SAFEHANDS_REGISTRY_ABI,
+                functionName: "verifyRiskRecord",
+                args: [
+                    proven.record.target,
+                    proven.record.actionHash,
+                    proven.record.score,
+                    proven.record.level,
+                    proven.record.recommendation,
+                    proven.record.policyVersionHash,
+                    proven.record.evidenceHash,
+                    proven.record.expiresAt,
+                    proven.proof,
+                ],
+            }));
+        }
+        catch (err) {
+            // Expired() revert is a legitimate on-chain answer, not an infra failure.
+            verifiedOnchain = false;
+            if (!expired) {
+                return {
+                    configured: true,
+                    committed: true,
+                    onchainMerkleRoot,
+                    dataURI,
+                    found: true,
+                    rootMatches: true,
+                    verifiedLocal: proven.verifiedLocal,
+                    verifiedOnchain: false,
+                    expired,
+                    proof: proven.proof,
+                    record,
+                    source: "error",
+                    error: `On-chain verifyRiskRecord failed: ${err.message}`,
+                };
+            }
+        }
+    }
+    return {
+        configured: true,
+        committed: true,
+        onchainMerkleRoot,
+        dataURI,
+        found: true,
+        rootMatches: true,
+        verifiedLocal: proven.verifiedLocal,
+        verifiedOnchain,
+        expired,
+        proof: proven.proof,
+        record,
+        source: shouldVerifyOnchain ? "onchain-view" : "local-only",
+    };
+}
+//# sourceMappingURL=riskInclusion.js.map

package/dist/lib/riskInclusion.js.map

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

package/dist/lib/safeHandsRegistry.d.ts

@@ -0,0 +1,32 @@
+/** Map a risk-engine level string to the on-chain RiskLevel enum (default MEDIUM). */
+export declare function riskLevelToEnum(level: string): number;
+/** Map a risk-engine recommendation string to the on-chain Recommendation enum (default CAUTION). */
+export declare function recommendationToEnum(rec: string): number;
+export declare function isAgentAuthorized(walletAddress: `0x${string}`): Promise<boolean>;
+export interface AutoAuthorizeResult {
+    riskRegistryAuthorized: boolean;
+    autoAuthorized: boolean;
+    authorizationTxHash?: string;
+    authorizationReason?: string;
+}
+export declare function tryAutoAuthorize(walletAddress: `0x${string}`): Promise<AutoAuthorizeResult>;
+export interface ManagedAuthCheckResult {
+    authorized: boolean;
+    autoAuthResult?: AutoAuthorizeResult;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export declare function checkManagedWalletAuthorization(walletAddress: `0x${string}`): Promise<ManagedAuthCheckResult>;
+export declare function deriveActionHash(chainId: number, actionType: string, walletAddress: string, extra: Record<string, string | undefined>): `0x${string}`;
+export interface RegistryQueryResult {
+    version: string;
+    address: string;
+    walletAddress: string;
+    authorized: boolean;
+    hasRiskRecord: boolean;
+    currentMerkleRoot: string | null;
+    currentDataURI: string | null;
+    error?: string;
+}
+export declare function queryRegistryForTarget(walletAddress: `0x${string}`): Promise<RegistryQueryResult>;
+//# sourceMappingURL=safeHandsRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"safeHandsRegistry.d.ts","sourceRoot":"","sources":["../../src/lib/safeHandsRegistry.ts"],"names":[],"mappings":"AAoBA,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED,qGAAqG;AACrG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGxD;AASD,wBAAsB,iBAAiB,CAAC,aAAa,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAatF;AAED,MAAM,WAAW,mBAAmB;IAClC,sBAAsB,EAAE,OAAO,CAAC;IAChC,cAAc,EAAE,OAAO,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAyCjG;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAsB,+BAA+B,CAAC,aAAa,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAiBnH;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACxC,KAAK,MAAM,EAAE,CAGf;AAOD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,sBAAsB,CAAC,aAAa,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmDvG"}

package/dist/lib/safeHandsRegistry.js

@@ -0,0 +1,151 @@
+// ─── SafeHandsRegistry client ──────────────────────────────────────────
+// Read/write client for the on-chain SafeHandsRegistry (trust + reputation
+// oracle). Replaces the legacy SafeHandsRegistry client. Read-only by default;
+// the only writes are agent authorization (owner key) and risk-record
+// publishing (operator key) — both behind explicit gates in the callers.
+// ────────────────────────────────────────────────────────────────────────
+import { privateKeyToAccount } from "viem/accounts";
+import { keccak256, encodePacked, isAddress } from "viem";
+import { publicClient, createPharosWalletClientFromAccount } from "./pharosClient.js";
+import { SAFEHANDS_REGISTRY_ADDRESS, SAFEHANDS_REGISTRY_ABI, AUTO_AUTHORIZE_AGENT_WALLET, } from "./constants.js";
+// SafeHandsRegistry enum orderings (must match the Solidity enums).
+const LEVELS = ["low", "medium", "high", "critical"];
+const RECOMMENDATIONS = ["proceed", "caution", "block"];
+/** Map a risk-engine level string to the on-chain RiskLevel enum (default MEDIUM). */
+export function riskLevelToEnum(level) {
+    const i = LEVELS.indexOf(level.toLowerCase());
+    return i >= 0 ? i : 1;
+}
+/** Map a risk-engine recommendation string to the on-chain Recommendation enum (default CAUTION). */
+export function recommendationToEnum(rec) {
+    const i = RECOMMENDATIONS.indexOf(rec.toLowerCase());
+    return i >= 0 ? i : 1;
+}
+/** The configured registry address, or null when not yet deployed/configured. */
+function registryAddress() {
+    return SAFEHANDS_REGISTRY_ADDRESS && isAddress(SAFEHANDS_REGISTRY_ADDRESS)
+        ? SAFEHANDS_REGISTRY_ADDRESS
+        : null;
+}
+export async function isAgentAuthorized(walletAddress) {
+    const address = registryAddress();
+    if (!address)
+        return false;
+    try {
+        return (await publicClient.readContract({
+            address,
+            abi: SAFEHANDS_REGISTRY_ABI,
+            functionName: "isAuthorizedAgent",
+            args: [walletAddress],
+        }));
+    }
+    catch {
+        return false;
+    }
+}
+export async function tryAutoAuthorize(walletAddress) {
+    if (!AUTO_AUTHORIZE_AGENT_WALLET) {
+        return { riskRegistryAuthorized: false, autoAuthorized: false, authorizationReason: "AUTO_AUTHORIZE_AGENT_WALLET is disabled." };
+    }
+    const address = registryAddress();
+    if (!address) {
+        return { riskRegistryAuthorized: false, autoAuthorized: false, authorizationReason: "SAFEHANDS_REGISTRY_ADDRESS is not configured." };
+    }
+    const ownerKey = process.env.RISK_REGISTRY_OWNER_PRIVATE_KEY;
+    if (!ownerKey) {
+        return { riskRegistryAuthorized: false, autoAuthorized: false, authorizationReason: "RISK_REGISTRY_OWNER_PRIVATE_KEY is not configured." };
+    }
+    if (!isAddress(walletAddress) || walletAddress === "0x0000000000000000000000000000000000000000") {
+        return { riskRegistryAuthorized: false, autoAuthorized: false, authorizationReason: "Invalid wallet address for auto-authorization." };
+    }
+    try {
+        if (await isAgentAuthorized(walletAddress)) {
+            return { riskRegistryAuthorized: true, autoAuthorized: false };
+        }
+        const normalized = (ownerKey.startsWith("0x") ? ownerKey : `0x${ownerKey}`);
+        const ownerWallet = createPharosWalletClientFromAccount(privateKeyToAccount(normalized));
+        const txHash = await ownerWallet.writeContract({
+            address,
+            abi: SAFEHANDS_REGISTRY_ABI,
+            functionName: "setAuthorizedAgent",
+            args: [walletAddress, true],
+        });
+        return { riskRegistryAuthorized: true, autoAuthorized: true, authorizationTxHash: txHash };
+    }
+    catch (err) {
+        return {
+            riskRegistryAuthorized: false,
+            autoAuthorized: false,
+            authorizationReason: `Auto-authorization failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+export async function checkManagedWalletAuthorization(walletAddress) {
+    if (await isAgentAuthorized(walletAddress))
+        return { authorized: true };
+    const autoResult = await tryAutoAuthorize(walletAddress);
+    if (autoResult.riskRegistryAuthorized) {
+        return { authorized: true, autoAuthResult: autoResult };
+    }
+    return {
+        authorized: false,
+        autoAuthResult: autoResult,
+        errorCode: "AGENT_WALLET_NOT_AUTHORIZED",
+        errorMessage: `Managed wallet ${walletAddress} is not authorized in SafeHandsRegistry. ` +
+            `The contract owner must call setAuthorizedAgent(${walletAddress}, true), ` +
+            `or enable AUTO_AUTHORIZE_AGENT_WALLET=true with RISK_REGISTRY_OWNER_PRIVATE_KEY.`,
+    };
+}
+export function deriveActionHash(chainId, actionType, walletAddress, extra) {
+    const parts = [String(chainId), actionType, walletAddress, ...Object.values(extra).filter(Boolean)].join(":");
+    return keccak256(encodePacked(["string"], [parts]));
+}
+export async function queryRegistryForTarget(walletAddress) {
+    const address = registryAddress();
+    const base = { version: "safehands-registry", address: address ?? "", walletAddress };
+    if (!address) {
+        return {
+            ...base,
+            authorized: false,
+            hasRiskRecord: false,
+            currentMerkleRoot: null,
+            currentDataURI: null,
+            error: "SafeHandsRegistry address not configured (deploy + set SAFEHANDS_REGISTRY_ADDRESS).",
+        };
+    }
+    try {
+        const authorized = await isAgentAuthorized(walletAddress);
+        let currentMerkleRoot = null;
+        let currentDataURI = null;
+        try {
+            currentMerkleRoot = (await publicClient.readContract({
+                address,
+                abi: SAFEHANDS_REGISTRY_ABI,
+                functionName: "currentMerkleRoot",
+                args: [],
+            }));
+            currentDataURI = (await publicClient.readContract({
+                address,
+                abi: SAFEHANDS_REGISTRY_ABI,
+                functionName: "currentDataURI",
+                args: [],
+            }));
+        }
+        catch {
+            /* ignore if not yet committed */
+        }
+        const hasRiskRecord = Boolean(currentMerkleRoot && currentMerkleRoot !== "0x0000000000000000000000000000000000000000000000000000000000000000");
+        return { ...base, authorized, hasRiskRecord, currentMerkleRoot, currentDataURI };
+    }
+    catch (err) {
+        return {
+            ...base,
+            authorized: false,
+            hasRiskRecord: false,
+            currentMerkleRoot: null,
+            currentDataURI: null,
+            error: `SafeHandsRegistry unavailable: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+//# sourceMappingURL=safeHandsRegistry.js.map

package/dist/lib/safeHandsRegistry.js.map

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

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

@@ -1,5 +1,5 @@
 import type { Account } from "viem";
-export type SignerMode = "none" | "env" | "managed-testnet" | "external-signer" | "x402-env";
+export type SignerMode = "none" | "env" | "managed-mainnet" | "external-signer" | "x402-env";
 export type SignerPurpose = "write" | "x402";
 export interface SignerResult {
     account: Account;
@@ -16,8 +16,8 @@ export type GetSignerResult = SignerResult | SignerFailure;
 export declare function isSignerFailure(r: GetSignerResult): r is SignerFailure;
 /**
  * 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.
+ * 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 declare function getSigner(agentId?: string, options?: {
     purpose?: SignerPurpose;

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

@@ -4,6 +4,7 @@
 // ────────────────────────────────────────────────────────────────────────
 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;
 }
@@ -29,13 +30,25 @@ function accountFromEnvKey(envName, mode) {
 }
 async function accountFromManagedWallet(agentId) {
     const walletMode = process.env.WALLET_MODE || "none";
-    if (walletMode !== "managed-testnet" || !agentId)
+    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-testnet wallets.",
+                message: "WALLET_ENCRYPTION_KEY is required when WALLET_STORE_PATH is used for persistent managed-mainnet wallets.",
             },
         };
     }
@@ -45,7 +58,7 @@ async function accountFromManagedWallet(agentId) {
     try {
         const privateKey = decryptKey(stored.encryptedKey, getEffectiveEncryptionKey());
         const account = privateKeyToAccount(normalizePrivateKey(privateKey));
-        return { account, address: account.address, mode: "managed-testnet" };
+        return { account, address: account.address, mode: "managed-mainnet" };
     }
     catch {
         return {
@@ -58,21 +71,30 @@ async function accountFromManagedWallet(agentId) {
 }
 /**
  * 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.
+ * 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";
-    const managed = await accountFromManagedWallet(agentId);
-    if (managed)
-        return managed;
+    // 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" || process.env.PRIVATE_KEY) {
+    if (walletMode === "env") {
         const env = accountFromEnvKey("PRIVATE_KEY", "env");
         if (env)
             return env;
@@ -81,8 +103,8 @@ export async function getSigner(agentId, options = {}) {
         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.",
+                ? "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.",
         },
     };
 }

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/signer/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,0EAA0E;AAC1E,0DAA0D;AAC1D,2EAA2E;AAE3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAoBxF,MAAM,UAAU,eAAe,CAAC,CAAkB;IAChD,OAAO,OAAO,IAAI,CAAC,CAAC;AACtB,CAAC;AAED,SAAS,mBAAmB,CAAC,EAAU;IACrC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAkB,CAAC;AACjE,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAkD,EAAE,IAAgB;IAC7F,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IACrB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,mBAAmB,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,KAAK,EAAE;gBACL,IAAI,EAAE,qBAAqB;gBAC3B,OAAO,EAAE,GAAG,OAAO,8BAA8B;aAClD;SACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,wBAAwB,CAAC,OAAgB;IACtD,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,MAAM,CAAC;IACrD,IAAI,UAAU,KAAK,iBAAiB,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE9D,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,EAAE,CAAC;QACxE,OAAO;YACL,KAAK,EAAE;gBACL,IAAI,EAAE,gCAAgC;gBACtC,OAAO,EACL,0GAA0G;aAC7G;SACF,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAEzB,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,YAAY,EAAE,yBAAyB,EAAE,CAAC,CAAC;QAChF,MAAM,OAAO,GAAG,mBAAmB,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC,CAAC;QACrE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,KAAK,EAAE;gBACL,IAAI,EAAE,qBAAqB;gBAC3B,OAAO,EAAE,sIAAsI;aAChJ;SACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,OAAgB,EAChB,UAAuC,EAAE;IAEzC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC;IAE3C,MAAM,OAAO,GAAG,MAAM,wBAAwB,CAAC,OAAO,CAAC,CAAC;IACxD,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAE5B,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,iBAAiB,CAAC,yBAAyB,EAAE,UAAU,CAAC,CAAC;QACzE,IAAI,OAAO;YAAE,OAAO,OAAO,CAAC;IAC9B,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,MAAM,CAAC;IACrD,IAAI,UAAU,KAAK,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QACpD,MAAM,GAAG,GAAG,iBAAiB,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;QACpD,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC;IACtB,CAAC;IAED,OAAO;QACL,KAAK,EAAE;YACL,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EACL,OAAO,KAAK,MAAM;gBAChB,CAAC,CAAC,gJAAgJ;gBAClJ,CAAC,CAAC,oIAAoI;SAC3I;KACF,CAAC;AACJ,CAAC"}
+{"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"}