safehands-pharos 1.5.0 → 2.6.0

package/dist/api/toolRoutes.d.ts

@@ -0,0 +1,14 @@
+import { type ToolResponse } from "../lib/toolResponse.js";
+/** True for state-changing tools (execution / disk-writing). Used by the HTTP
+ * layer to require authentication before a write tool can run over an open origin. */
+export declare function isWriteTool(name: string): boolean;
+export declare function listHostedTools(): {
+    count: number;
+    tools: {
+        name: string;
+        write: boolean;
+        enabled: boolean;
+    }[];
+};
+export declare function invokeHostedTool(toolName: string, params: unknown): Promise<ToolResponse<unknown>>;
+//# sourceMappingURL=toolRoutes.d.ts.map

package/dist/api/toolRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolRoutes.d.ts","sourceRoot":"","sources":["../../src/api/toolRoutes.ts"],"names":[],"mappings":"AAOA,OAAO,EAAmC,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAsF5F;sFACsF;AACtF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAMD,wBAAgB,eAAe;;;;;;;EAU9B;AAED,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAqCxG"}

package/dist/api/toolRoutes.js

@@ -0,0 +1,138 @@
+// ─── SafeHands Tool Gateway API ────────────────────────────────────────
+// Optional HTTP bridge for the same 33 tools exposed through MCP/Anvita.
+// This does not replace MCP; it lets a hosted deployment expose every tool at
+// POST /tools/:toolName when the operator intentionally enables the API.
+// Write tools remain protected by the same env gates used by MCP handlers.
+// ────────────────────────────────────────────────────────────────────────
+import { fail, ok, productionSafeMessage } from "../lib/toolResponse.js";
+import { handleAssessRisk } from "../tools/assessRisk.js";
+import { handleSimulateTransaction } from "../tools/simulateTransaction.js";
+import { handleGetExecutionHistory } from "../tools/getExecutionHistory.js";
+import { handleGetTokenPrice } from "../tools/getTokenPrice.js";
+import { handleGetWalletBalance } from "../tools/getWalletBalance.js";
+import { handleCheckAllowance } from "../tools/checkAllowance.js";
+import { handleGetTransactionStatus } from "../tools/getTransactionStatus.js";
+import { handleEstimateGas } from "../tools/estimateGas.js";
+import { handlePublishRiskScore } from "../tools/publishRiskScore.js";
+import { handleQueryRiskRegistry } from "../tools/queryRiskRegistry.js";
+import { handleVerifyRiskInclusion } from "../tools/verifyRiskInclusion.js";
+import { handleGetAgentReputation } from "../tools/getAgentReputation.js";
+import { handleGetGasPrice } from "../tools/getGasPrice.js";
+import { handleGetPoolInfo } from "../tools/getPoolInfo.js";
+import { handleQueryGoldsky } from "../tools/queryGoldsky.js";
+import { handleGetSpvProof } from "../tools/getSpvProof.js";
+import { handleCheckTokenSecurity } from "../tools/checkTokenSecurity.js";
+import { handleCreateAgentWallet } from "../tools/createAgentWallet.js";
+import { handleSafeHandsPreflightCheck } from "../tools/safehandsPreflightCheck.js";
+import { handleSafeHandsSafeExecute } from "../tools/safehandsSafeExecute.js";
+import { handleSafeHandsWalletHealth } from "../tools/safehandsWalletHealth.js";
+import { handleSafeHandsX402Preflight } from "../tools/safehandsX402Preflight.js";
+import { handleSafeHandsRiskReport } from "../tools/safehandsRiskReport.js";
+import { handleExplainRisk } from "../tools/explainRisk.js";
+import { handleTokenRegistryStatus } from "../tools/tokenRegistryStatus.js";
+import { handleGetAgentWallet } from "../tools/getAgentWallet.js";
+import { handleGetAgentWalletBalance } from "../tools/getAgentWalletBalance.js";
+import { handleGetAgentPolicy } from "../tools/getAgentPolicy.js";
+import { handleSetAgentPolicy } from "../tools/setAgentPolicy.js";
+import { handleExecuteSwap } from "../tools/executeSwap.js";
+import { handleSendPayment } from "../tools/sendPayment.js";
+import { handleApproveToken } from "../tools/approveToken.js";
+import { handleX402PayAndFetch } from "../tools/x402PayAndFetch.js";
+import { auditLog } from "../lib/auditLog.js";
+const TOOL_HANDLERS = {
+    safehands_preflight_check: handleSafeHandsPreflightCheck,
+    safehands_safe_execute: handleSafeHandsSafeExecute,
+    execute_swap: handleExecuteSwap,
+    send_payment: handleSendPayment,
+    approve_token: handleApproveToken,
+    x402_pay_and_fetch: handleX402PayAndFetch,
+    safehands_wallet_health: handleSafeHandsWalletHealth,
+    safehands_x402_preflight: handleSafeHandsX402Preflight,
+    safehands_risk_report: handleSafeHandsRiskReport,
+    explain_risk: handleExplainRisk,
+    token_registry_status: handleTokenRegistryStatus,
+    assess_risk: handleAssessRisk,
+    simulate_transaction: handleSimulateTransaction,
+    get_execution_history: handleGetExecutionHistory,
+    get_token_price: handleGetTokenPrice,
+    get_wallet_balance: handleGetWalletBalance,
+    check_allowance: handleCheckAllowance,
+    get_transaction_status: handleGetTransactionStatus,
+    estimate_gas: handleEstimateGas,
+    publish_risk_score: handlePublishRiskScore,
+    query_risk_registry: handleQueryRiskRegistry,
+    verify_risk_inclusion: handleVerifyRiskInclusion,
+    get_agent_reputation: handleGetAgentReputation,
+    get_gas_price: handleGetGasPrice,
+    get_pool_info: handleGetPoolInfo,
+    query_goldsky_subgraph: handleQueryGoldsky,
+    get_spv_proof: handleGetSpvProof,
+    check_token_security: handleCheckTokenSecurity,
+    get_agent_policy: handleGetAgentPolicy,
+    set_agent_policy: handleSetAgentPolicy,
+    create_agent_wallet: handleCreateAgentWallet,
+    get_agent_wallet: handleGetAgentWallet,
+    get_agent_wallet_balance: handleGetAgentWalletBalance,
+};
+const WRITE_TOOLS = new Set([
+    "safehands_safe_execute",
+    "execute_swap",
+    "send_payment",
+    "approve_token",
+    "x402_pay_and_fetch",
+    "publish_risk_score",
+    "set_agent_policy",
+    "create_agent_wallet",
+]);
+/** True for state-changing tools (execution / disk-writing). Used by the HTTP
+ * layer to require authentication before a write tool can run over an open origin. */
+export function isWriteTool(name) {
+    return WRITE_TOOLS.has(name);
+}
+function isToolResponse(value) {
+    return !!value && typeof value === "object" && "success" in value && "timestamp" in value && "error" in value;
+}
+export function listHostedTools() {
+    const names = Object.keys(TOOL_HANDLERS).sort();
+    return {
+        count: names.length,
+        tools: names.map((name) => ({
+            name,
+            write: WRITE_TOOLS.has(name),
+            enabled: !WRITE_TOOLS.has(name) || process.env.WRITE_TOOLS_ENABLED === "true",
+        })),
+    };
+}
+export async function invokeHostedTool(toolName, params) {
+    const handler = TOOL_HANDLERS[toolName];
+    if (!handler) {
+        return fail("UNKNOWN_TOOL", `Unknown SafeHands tool '${toolName}'.`, false, "tool_gateway");
+    }
+    if (WRITE_TOOLS.has(toolName) && process.env.WRITE_TOOLS_ENABLED !== "true") {
+        return fail("WRITE_TOOLS_DISABLED", `${toolName} is disabled by default. Set WRITE_TOOLS_ENABLED=true only for trusted full-enabled deployments.`, false, "tool_gateway");
+    }
+    const start = Date.now();
+    try {
+        const result = await handler(params ?? {});
+        auditLog({
+            ts: new Date().toISOString(),
+            tool: `http:${toolName}`,
+            success: isToolResponse(result) ? result.success : true,
+            errorCode: isToolResponse(result) && !result.success ? result.error.code : undefined,
+            durationMs: Date.now() - start,
+        });
+        return isToolResponse(result) ? result : ok(result);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        auditLog({
+            ts: new Date().toISOString(),
+            tool: `http:${toolName}`,
+            success: false,
+            errorCode: "TOOL_EXECUTION_FAILED",
+            durationMs: Date.now() - start,
+        });
+        return fail("TOOL_EXECUTION_FAILED", productionSafeMessage(message, "Tool execution failed."), false, toolName);
+    }
+}
+//# sourceMappingURL=toolRoutes.js.map

package/dist/api/toolRoutes.js.map

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

package/dist/api/walletPrepareRoutes.d.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import type { ReadOnlyChainAccess } from "../lib/analysis/index.js";
+import type { AgentRouteOptions } from "./agentRoutes.js";
+declare const walletPrepareSchema: z.ZodObject<{
+    to: z.ZodString;
+    data: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    chainId: z.ZodOptional<z.ZodNumber>;
+    /** Wallet context read from the request — provided by the frontend/SDK/CLI/agent host. */
+    userAddress: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    to: z.ZodString;
+    data: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    chainId: z.ZodOptional<z.ZodNumber>;
+    /** Wallet context read from the request — provided by the frontend/SDK/CLI/agent host. */
+    userAddress: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    to: z.ZodString;
+    data: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    chainId: z.ZodOptional<z.ZodNumber>;
+    /** Wallet context read from the request — provided by the frontend/SDK/CLI/agent host. */
+    userAddress: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type WalletPrepareInput = z.input<typeof walletPrepareSchema>;
+/** UX hint for the caller/host — never a substitute for the public decision. */
+export type WalletNextAction = "CONNECT_WALLET_OR_PROVIDE_ADDRESS" | "SIGN_IN_EXTERNAL_WALLET" | "REVIEW_FIRST" | "STOP";
+/**
+ * POST /wallet/prepare — SafeHands-checked, wallet-ready transaction handoff.
+ * - Missing wallet context → `requiresWalletConnection: true`,
+ *   `nextAction: CONNECT_WALLET_OR_PROVIDE_ADDRESS`, no `walletRequest`.
+ * - Provided wallet + not blocked → `walletRequest` {from,to,data,value,chainId}.
+ * - BLOCK → no `walletRequest`, `nextAction: STOP`.
+ * - REQUIRE_CONFIRMATION → `confirmationRequired: true`, `nextAction: REVIEW_FIRST`.
+ */
+export declare function handleWalletPrepare(raw: unknown, access?: ReadOnlyChainAccess, opts?: AgentRouteOptions): Promise<{
+    readOnly: true;
+    executionAvailable: boolean;
+    decision: import("../lib/guardian/decision.js").GuardianDecision;
+    guardianDecision: import("../lib/guardian/decision.js").GuardianDecision;
+    riskLevel: import("../lib/analysis/types.js").AnalyzerRiskLevel;
+    reasons: string[];
+    /** True when no wallet context was provided and the action is not blocked. */
+    requiresWalletConnection: boolean;
+    /** True when the underlying verdict needs explicit user review before signing. */
+    confirmationRequired: boolean;
+    /** UX hint for the host/client. */
+    nextAction: WalletNextAction;
+    /** Wallet-ready request for an EXTERNAL wallet (null when blocked or no wallet). */
+    walletRequest: {
+        from: string;
+        to: `0x${string}`;
+        data: string;
+        value: string;
+        chainId: number;
+    } | null;
+    preparedTransactionId: string | undefined;
+    preparedTransactionHash: string | undefined;
+    network: import("../lib/networks.js").NetworkName;
+    chainId: number;
+    policyPreset: string | null;
+    policyVersion: string;
+    /** SafeHands signs nothing and broadcasts nothing — the external wallet does both. */
+    signingAvailable: boolean;
+    broadcastAvailable: boolean;
+    nextStep: string;
+    source: string;
+}>;
+export {};
+//# sourceMappingURL=walletPrepareRoutes.d.ts.map

package/dist/api/walletPrepareRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walletPrepareRoutes.d.ts","sourceRoot":"","sources":["../../src/api/walletPrepareRoutes.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAO1D,QAAA,MAAM,mBAAmB;;;;;IAMrB,0FAA0F;;;;;;;;IAA1F,0FAA0F;;;;;;;;IAA1F,0FAA0F;;;gCAI9E,CAAC;AAEjB,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAErE,gFAAgF;AAChF,MAAM,MAAM,gBAAgB,GACxB,mCAAmC,GACnC,yBAAyB,GACzB,cAAc,GACd,MAAM,CAAC;AAEX;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EACZ,MAAM,CAAC,EAAE,mBAAmB,EAC5B,IAAI,GAAE,iBAAsB;;;;;;;IAqF1B,8EAA8E;;IAE9E,kFAAkF;;IAElF,mCAAmC;;IAEnC,oFAAoF;;cA1DvD,MAAM;;;;;;;;;;;;IAkEnC,sFAAsF;;;;;GAOzF"}

package/dist/api/walletPrepareRoutes.js

@@ -0,0 +1,127 @@
+// ─── SafeHands API — Wallet-Ready Transaction Handoff ──
+// Prepares a WALLET-READY transaction request for an EXTERNAL wallet to sign and
+// send. Wallet connection happens OUTSIDE SafeHands (frontend/dApp, SDK userAddress,
+// CLI --from, or MCP/agent host) — SafeHands only READS the wallet context from the
+// request. It runs the SafeHands check on the intent and, when the caller supplied a
+// wallet address and the action is not blocked, returns a `walletRequest`
+// {from,to,data,value,chainId} for external signing/sending.
+//
+// SafeHands NEVER signs, NEVER broadcasts, NEVER creates or manages a wallet, and
+// holds NO key. Read-only by construction: no signer/wallet/send primitive here.
+// ────────────────────────────────────────────────────────────────────────
+import { z } from "zod";
+import { isAddress } from "viem";
+import { createGuardianAgent } from "../agent/index.js";
+import { getActiveNetwork, getActiveNetworkName } from "../lib/networks.js";
+import { readOnlyMeta } from "./response.js";
+import { savePreparedTx } from "../lib/preparedTxStore.js";
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+const walletPrepareSchema = z
+    .object({
+    to: z.string(),
+    data: z.string().optional(),
+    value: z.string().optional(),
+    chainId: z.number().optional(),
+    /** Wallet context read from the request — provided by the frontend/SDK/CLI/agent host. */
+    userAddress: z.string().optional(),
+    from: z.string().optional(),
+})
+    .passthrough(); // policyPreset / policy are read by the server (agentPolicyOpts)
+/**
+ * POST /wallet/prepare — SafeHands-checked, wallet-ready transaction handoff.
+ * - Missing wallet context → `requiresWalletConnection: true`,
+ *   `nextAction: CONNECT_WALLET_OR_PROVIDE_ADDRESS`, no `walletRequest`.
+ * - Provided wallet + not blocked → `walletRequest` {from,to,data,value,chainId}.
+ * - BLOCK → no `walletRequest`, `nextAction: STOP`.
+ * - REQUIRE_CONFIRMATION → `confirmationRequired: true`, `nextAction: REVIEW_FIRST`.
+ */
+export async function handleWalletPrepare(raw, access, opts = {}) {
+    const input = walletPrepareSchema.parse(raw);
+    if (!isAddress(input.to))
+        throw new Error("`to` must be a valid address.");
+    if (input.to === ZERO_ADDRESS)
+        throw new Error("`to` must not be the zero address.");
+    if (input.data !== undefined && !/^0x[0-9a-fA-F]*$/.test(input.data)) {
+        throw new Error("`data` must be 0x-prefixed hex.");
+    }
+    if (input.value !== undefined) {
+        const n = Number(input.value);
+        if (!Number.isFinite(n) || n < 0)
+            throw new Error("`value` must be a non-negative number.");
+    }
+    // Wallet context is read-only: SafeHands echoes it, never derives or stores a key.
+    const walletAddress = (input.userAddress ?? input.from)?.trim();
+    const hasWallet = typeof walletAddress === "string" && walletAddress.length > 0;
+    if (hasWallet && !isAddress(walletAddress)) {
+        throw new Error("`userAddress`/`from` must be a valid address.");
+    }
+    const network = getActiveNetwork();
+    const chainId = input.chainId ?? network.chainId;
+    // Real escalate-only SafeHands check on the intent — a BLOCK is never weakened.
+    const agent = createGuardianAgent({ access, policy: opts.policy, policyPreset: opts.policyPreset });
+    const verdict = await agent.check({ to: input.to, data: input.data, value: input.value, chainId });
+    const blocked = verdict.decision === "BLOCK";
+    const confirmationRequired = verdict.decision === "REQUIRE_CONFIRMATION";
+    // A wallet-ready request is produced ONLY when not blocked AND a wallet address is present.
+    const walletRequest = !blocked && hasWallet
+        ? {
+            from: walletAddress,
+            to: input.to,
+            data: input.data ?? "0x",
+            value: input.value ?? "0",
+            chainId,
+        }
+        : null;
+    let preparedTransactionId;
+    let preparedTransactionHash;
+    if (walletRequest) {
+        const record = savePreparedTx(walletRequest.from, walletRequest.to, walletRequest.data, walletRequest.value, walletRequest.chainId, verdict.decision, verdict.policyVersion ?? null, verdict.policyPreset ?? null);
+        preparedTransactionId = record.id;
+        preparedTransactionHash = record.hash;
+    }
+    // requiresWalletConnection only matters when the action could proceed (not blocked).
+    const requiresWalletConnection = !blocked && !hasWallet;
+    // nextAction priority: STOP (block) > CONNECT (no wallet) > REVIEW (confirm) > SIGN.
+    const nextAction = blocked
+        ? "STOP"
+        : !hasWallet
+            ? "CONNECT_WALLET_OR_PROVIDE_ADDRESS"
+            : confirmationRequired
+                ? "REVIEW_FIRST"
+                : "SIGN_IN_EXTERNAL_WALLET";
+    const nextStep = blocked
+        ? "Do not proceed: the action is unsafe. Surface the block reason; no wallet request is produced."
+        : !hasWallet
+            ? "Connect a wallet (or provide userAddress/from), then call again to receive a wallet-ready request."
+            : confirmationRequired
+                ? "Review the request, then sign and send it from your own external wallet. SafeHands does not sign or broadcast."
+                : "Sign and send the wallet request from your own external wallet. SafeHands holds no keys and does not broadcast.";
+    return {
+        // Public four-value decision contract.
+        decision: verdict.decision,
+        guardianDecision: verdict.decision,
+        riskLevel: verdict.riskLevel,
+        reasons: verdict.reasons,
+        /** True when no wallet context was provided and the action is not blocked. */
+        requiresWalletConnection,
+        /** True when the underlying verdict needs explicit user review before signing. */
+        confirmationRequired,
+        /** UX hint for the host/client. */
+        nextAction,
+        /** Wallet-ready request for an EXTERNAL wallet (null when blocked or no wallet). */
+        walletRequest,
+        preparedTransactionId,
+        preparedTransactionHash,
+        network: getActiveNetworkName(),
+        chainId,
+        policyPreset: verdict.policyPreset ?? null,
+        policyVersion: verdict.policyVersion ?? null,
+        /** SafeHands signs nothing and broadcasts nothing — the external wallet does both. */
+        signingAvailable: false,
+        broadcastAvailable: false,
+        nextStep,
+        source: "wallet_prepare",
+        ...readOnlyMeta(), // readOnly: true, executionAvailable: false
+    };
+}
+//# sourceMappingURL=walletPrepareRoutes.js.map

package/dist/api/walletPrepareRoutes.js.map

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

package/dist/api/x402Gate.d.ts

@@ -0,0 +1,51 @@
+import type express from "express";
+/** The additive paid bundle entrypoints. Existing free routes are never listed here. */
+export declare const PAID_ROUTE_PATHS: readonly ["/paid/assess-risk", "/paid/check-token-security", "/paid/simulate-transaction", "/paid/token-price", "/paid/pool-info", "/paid/swap-route", "/paid/risk-report"];
+type Env = Record<string, string | undefined>;
+export interface X402GateConfig {
+    /** True only when BOTH a receiver (payTo) and an external facilitator URL are set. */
+    configured: boolean;
+    /** Receive-only address for earned fees (X402_PAY_TO / WALLET_ADDRESS). */
+    payTo: string;
+    /** External facilitator (relayer) base URL — verification/settlement happen off-host. */
+    facilitatorUrl: string | null;
+    /** Price per paid call, in USDC-equivalent human units (default 0.01). */
+    priceUsdc: string;
+    /** x402 network id, e.g. eip155:688689. */
+    network: `${string}:${string}`;
+    /** ERC-20 used for payment (mirrors X402_PAYMENT_TOKEN_ADDRESS). */
+    paymentTokenAddress: string;
+    /** Replay-protection window in ms (mirrors x402Server default: 10 minutes). */
+    replayWindowMs: number;
+}
+/**
+ * Resolve the x402 gate config from env. REMOTE facilitator only — the single service
+ * never holds a key. `configured` requires payTo AND facilitatorUrl; anything else leaves
+ * the gate unconfigured so `/paid/*` fails closed. Pure + offline (tests pass synthetic env).
+ */
+export declare function resolveX402GateConfig(env?: Env): X402GateConfig;
+/**
+ * Client-facing message for a replay-store failure. Raw store errors can
+ * carry internals — Upstash REST error strings, the Redis hostname from a DNS
+ * failure, or state-dir filesystem paths — so production gets a generic
+ * message; the detail stays in server-side logs (and in dev responses).
+ * Exported for offline tests.
+ */
+export declare function replayStoreUnavailableMessage(err: unknown, production?: boolean): string;
+export interface X402Gate {
+    configured: boolean;
+    /**
+     * Install the gate on the app. When configured: replay → x402 paymentMiddleware on
+     * `/paid/*` (so the handler runs ONLY after a verified, non-replayed payment). When
+     * unconfigured: a fail-closed 503 guard on `/paid/*`. Must be installed BEFORE the
+     * paid route handlers so payment is verified first.
+     */
+    install(app: express.Application): void;
+}
+/**
+ * Build the x402 gate for the single service. Zero-custody: uses a remote facilitator
+ * client (X402_FACILITATOR_URL) for verify/settle; no local signer, no key, no wallet.
+ */
+export declare function buildX402Gate(cfg?: X402GateConfig): X402Gate;
+export {};
+//# sourceMappingURL=x402Gate.d.ts.map

package/dist/api/x402Gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402Gate.d.ts","sourceRoot":"","sources":["../../src/api/x402Gate.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAiBnC,wFAAwF;AACxF,eAAO,MAAM,gBAAgB,6KAQnB,CAAC;AAEX,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE9C,MAAM,WAAW,cAAc;IAC7B,sFAAsF;IACtF,UAAU,EAAE,OAAO,CAAC;IACpB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,OAAO,EAAE,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;IAC/B,oEAAoE;IACpE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,GAAiB,GAAG,cAAc,CAe5E;AAgCD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,OAAO,EACZ,UAAU,GAAE,OAA+C,GAC1D,MAAM,CAIR;AAyED,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,GAAE,cAAwC,GAAG,QAAQ,CAsBrF"}

package/dist/api/x402Gate.js

@@ -0,0 +1,184 @@
+// ─── SafeHands API — x402 Payment Gate (zero-custody) ─────────────
+// Adds real x402 gating to the SINGLE deployed service (dist/api/server.js) for
+// the additive `/paid/*` bundle entrypoints — WITHOUT breaking the free public
+// read API and WITHOUT putting a signing/facilitator key on the host.
+//
+// Zero-custody posture (WALLET_MODE=none):
+//   • The service holds NO private key. Verification + settlement are delegated to
+//     an EXTERNAL facilitator via X402_FACILITATOR_URL (a relayer that runs off-host).
+//   • X402_PAY_TO is a RECEIVE-only address for earned fees — not custody of user funds.
+//   • When receiver + facilitator config is absent, `/paid/*` is FAIL-CLOSED (503):
+//     the paid handler NEVER runs before payment is verified.
+//
+// Charge-once model: gating happens at the HTTP entrypoint only. A `/paid/*` route
+// may fan out to several internal analyzers/tools in-process (e.g. /paid/risk-report),
+// but the single verified X-PAYMENT settles exactly once. Internal helper tools are
+// never individually gated. Replay protection (checkAndRecordX402Replay) guarantees the
+// same payment authorization cannot buy a second call.
+//
+// Pure/env-driven config resolver (resolveX402GateConfig) is offline-testable; the gate
+// installer only touches the Express app. Nothing here signs, sends, or creates a wallet.
+// ────────────────────────────────────────────────────────────────────────────
+import { ExactEvmScheme as ServerExactEvmScheme } from "@x402/evm/exact/server";
+import { HTTPFacilitatorClient } from "@x402/core/server";
+import { paymentMiddleware, x402ResourceServer } from "@x402/express";
+import { CHAIN_ID, X402_PAYMENT_TOKEN_ADDRESS, PACIFIC_WPROS_ADDRESS, WPROS_ADDRESS, activeTokenDecimals, } from "../lib/constants.js";
+import { fail } from "../lib/toolResponse.js";
+import { checkAndRecordX402Replay } from "../lib/x402ReplayStore.js";
+const SOURCE = "guardian_api_x402";
+/** The additive paid bundle entrypoints. Existing free routes are never listed here. */
+export const PAID_ROUTE_PATHS = [
+    "/paid/assess-risk",
+    "/paid/check-token-security",
+    "/paid/simulate-transaction",
+    "/paid/token-price",
+    "/paid/pool-info",
+    "/paid/swap-route",
+    "/paid/risk-report",
+];
+/**
+ * Resolve the x402 gate config from env. REMOTE facilitator only — the single service
+ * never holds a key. `configured` requires payTo AND facilitatorUrl; anything else leaves
+ * the gate unconfigured so `/paid/*` fails closed. Pure + offline (tests pass synthetic env).
+ */
+export function resolveX402GateConfig(env = process.env) {
+    const payTo = (env.X402_PAY_TO || env.WALLET_ADDRESS || "").trim();
+    const facilitatorUrl = (env.X402_FACILITATOR_URL || "").trim() || null;
+    const priceUsdc = (env.X402_PRICE_USDC || "0.01").trim();
+    const replayWindowMs = Number(env.SAFEHANDS_X402_REPLAY_WINDOW_MS || 10 * 60 * 1000);
+    const configured = Boolean(payTo && facilitatorUrl);
+    return {
+        configured,
+        payTo,
+        facilitatorUrl,
+        priceUsdc,
+        network: `eip155:${CHAIN_ID}`,
+        paymentTokenAddress: X402_PAYMENT_TOKEN_ADDRESS,
+        replayWindowMs: Number.isFinite(replayWindowMs) && replayWindowMs > 0 ? replayWindowMs : 10 * 60 * 1000,
+    };
+}
+/** Fail-closed guard: paid routes return 503 (handler never runs) when x402 is unconfigured. */
+function unconfiguredGuard(_req, res) {
+    res.status(503).json(fail("X402_SERVER_RECEIVER_CONFIG_MISSING", "Paid endpoints require an x402 receiver (X402_PAY_TO) plus an external facilitator (X402_FACILITATOR_URL). " +
+        "Free endpoints remain available. The zero-custody service holds no signing key.", false, SOURCE));
+}
+/**
+ * x402 X-PAYMENT is base64-encoded JSON. Reject obvious junk BEFORE recording it in
+ * the replay store: each store write is an O(n) full-file rewrite, so without
+ * this an attacker could flood `/paid/*` with unique random headers and grow the
+ * store / burn CPU+disk. A malformed header would fail downstream verification
+ * anyway; dropping it here just avoids the write. Legitimate payments decode fine.
+ */
+function looksLikeX402Payment(header) {
+    if (header.length > 8192)
+        return false;
+    try {
+        const parsed = JSON.parse(Buffer.from(header, "base64").toString("utf-8"));
+        return !!parsed && typeof parsed === "object";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Client-facing message for a replay-store failure. Raw store errors can
+ * carry internals — Upstash REST error strings, the Redis hostname from a DNS
+ * failure, or state-dir filesystem paths — so production gets a generic
+ * message; the detail stays in server-side logs (and in dev responses).
+ * Exported for offline tests.
+ */
+export function replayStoreUnavailableMessage(err, production = process.env.NODE_ENV === "production") {
+    if (production)
+        return "x402 replay store is temporarily unavailable.";
+    const message = err instanceof Error ? err.message : String(err);
+    return `x402 replay store unavailable: ${message}`;
+}
+/** Durable replay protection: reject a reused X-PAYMENT authorization before settlement. */
+function buildReplayMiddleware(cfg) {
+    return function replayProtectionMiddleware(req, res, next) {
+        const paymentHeader = req.headers["x-payment"];
+        if (typeof paymentHeader !== "string" || paymentHeader.length <= 10)
+            return next();
+        // Pre-filter malformed headers so junk floods can't grow the O(n) replay store.
+        if (!looksLikeX402Payment(paymentHeader)) {
+            res
+                .status(400)
+                .json(fail("X402_PAYMENT_MALFORMED", "X-PAYMENT header is not a valid x402 payment payload.", false, SOURCE));
+            return;
+        }
+        checkAndRecordX402Replay(paymentHeader, cfg.replayWindowMs)
+            .then((result) => {
+            res.setHeader("X-SafeHands-X402-Replay-Store", result.backend);
+            if (!result.allowed) {
+                res
+                    .status(402)
+                    .json(fail("REPLAY_ATTACK_DETECTED", "This x402 payment signature has already been used.", false, SOURCE));
+                return;
+            }
+            next();
+        })
+            .catch((err) => {
+            console.error("[SafeHands x402] replay store unavailable:", err instanceof Error ? err.message : String(err));
+            res
+                .status(503)
+                .json(fail("X402_REPLAY_STORE_UNAVAILABLE", replayStoreUnavailableMessage(err), true, SOURCE));
+        });
+    };
+}
+/** Money parser: convert the human price into the atomic amount + asset for the exact scheme. */
+function buildMoneyParser(cfg) {
+    return async (amount, network) => {
+        if (network !== cfg.network)
+            return null;
+        const decimals = activeTokenDecimals()[cfg.paymentTokenAddress.toLowerCase()] || 6;
+        const multiplier = Math.pow(10, decimals);
+        const isWpros = cfg.paymentTokenAddress.toLowerCase() === PACIFIC_WPROS_ADDRESS.toLowerCase() ||
+            cfg.paymentTokenAddress.toLowerCase() === WPROS_ADDRESS.toLowerCase();
+        const symbol = isWpros ? "WPROS" : "USDC";
+        return {
+            amount: Math.round(amount * multiplier).toString(),
+            asset: cfg.paymentTokenAddress,
+            extra: { token: symbol, name: symbol, version: "2" },
+        };
+    };
+}
+/** paymentMiddleware route map: each paid entrypoint priced independently, settled once. */
+function buildRouteConfig(cfg) {
+    const accepts = { scheme: "exact", price: cfg.priceUsdc, network: cfg.network, payTo: cfg.payTo };
+    const entry = (description) => ({ accepts, description, mimeType: "application/json" });
+    return {
+        "GET /paid/assess-risk": entry(`Assess transaction risk (USDC ${cfg.priceUsdc})`),
+        "GET /paid/check-token-security": entry(`Verify contract token security profile (USDC ${cfg.priceUsdc})`),
+        "GET /paid/simulate-transaction": entry(`Simulate EVM execution before broadcast (USDC ${cfg.priceUsdc})`),
+        "GET /paid/token-price": entry(`Real-time token price via DODO/FaroSwap (USDC ${cfg.priceUsdc})`),
+        "GET /paid/pool-info": entry(`DODO/FaroSwap pool data: ratio, impact, fees (USDC ${cfg.priceUsdc})`),
+        "GET /paid/swap-route": entry(`Swap route with estimated output via DODO (USDC ${cfg.priceUsdc})`),
+        "GET /paid/risk-report": entry(`Full SafeHands risk report bundle (USDC ${cfg.priceUsdc})`),
+    };
+}
+/**
+ * Build the x402 gate for the single service. Zero-custody: uses a remote facilitator
+ * client (X402_FACILITATOR_URL) for verify/settle; no local signer, no key, no wallet.
+ */
+export function buildX402Gate(cfg = resolveX402GateConfig()) {
+    return {
+        configured: cfg.configured,
+        install(app) {
+            const paths = PAID_ROUTE_PATHS;
+            if (!cfg.configured) {
+                app.use(paths, unconfiguredGuard);
+                return;
+            }
+            // 1) Replay protection first — a reused authorization is rejected before settlement.
+            app.use(paths, buildReplayMiddleware(cfg));
+            // 2) x402 gate via an EXTERNAL facilitator (relayer runs off-host; service holds no key).
+            const facilitatorClient = new HTTPFacilitatorClient({ url: cfg.facilitatorUrl });
+            const resourceServer = new x402ResourceServer(facilitatorClient);
+            const evmScheme = new ServerExactEvmScheme();
+            evmScheme.registerMoneyParser(buildMoneyParser(cfg));
+            resourceServer.register(cfg.network, evmScheme);
+            app.use(paymentMiddleware(buildRouteConfig(cfg), resourceServer));
+        },
+    };
+}
+//# sourceMappingURL=x402Gate.js.map

package/dist/api/x402Gate.js.map

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