safehands-pharos 1.4.0 → 2.6.0

package/dist/api/indexerRoutes.d.ts

@@ -0,0 +1,46 @@
+export declare function handleGoldskyStatus(): {
+    readOnly: true;
+    executionAvailable: boolean;
+    service: string;
+    status: import("../lib/goldsky.js").GoldskyConfigStatus;
+    role: string;
+    recommendedEntities: {
+        attestations: string;
+        riskRoots: string;
+    };
+    network: import("../lib/networks.js").NetworkName;
+};
+/**
+ * Read-only, keyless, composable on-chain reputation for an address: the count of
+ * SafeHands-verified safe broadcasts attributed to it (+ recency), plus registry
+ * authorization/risk-record context. Any agent can query this as a trust signal.
+ * Zero count = NEUTRAL (no track record yet), never negative.
+ */
+export declare function handleAgentReputation(address: string): Promise<{
+    readOnly: true;
+    executionAvailable: boolean;
+    address: `0x${string}`;
+    reputation: {
+        verifiedActionCount: number;
+        lastVerifiedActionAt: number;
+        configured: boolean;
+        source: "onchain" | "unconfigured";
+    };
+    registry: {
+        isAuthorizedAgent: boolean;
+        hasRiskRecord: boolean;
+        currentMerkleRoot: string | null;
+    };
+    interpretation: string;
+    network: import("../lib/networks.js").NetworkName;
+}>;
+export declare function handleLatestRiskRootIndex(): Promise<{
+    readOnly: true;
+    executionAvailable: boolean;
+    status: string;
+    goldsky: import("../lib/goldsky.js").GoldskyLookupResult<import("../lib/goldsky.js").IndexedRiskRootRecord>;
+    onchain: Record<string, unknown> | null;
+    note: string;
+    network: import("../lib/networks.js").NetworkName;
+}>;
+//# sourceMappingURL=indexerRoutes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"indexerRoutes.d.ts","sourceRoot":"","sources":["../../src/api/indexerRoutes.ts"],"names":[],"mappings":"AAOA,wBAAgB,mBAAmB;;;;;;;;;;;EAYlC;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM;;;;;;;;;;;;;;;;;GA4B1D;AAED,wBAAsB,yBAAyB;;;;;;;;GAsB9C"}

package/dist/api/indexerRoutes.js

@@ -0,0 +1,75 @@
+import { goldskyStatus, lookupLatestRiskRootInGoldsky } from "../lib/goldsky.js";
+import { queryRegistryForTarget } from "../lib/safeHandsRegistry.js";
+import { getAgentReputation } from "../lib/pharos/attestationPublisher.js";
+import { getActiveNetworkName } from "../lib/networks.js";
+import { readOnlyMeta } from "./response.js";
+import { isAddress } from "viem";
+export function handleGoldskyStatus() {
+    return {
+        service: "safehands-goldsky-indexer",
+        status: goldskyStatus(),
+        role: "Goldsky indexes SafeHands on-chain Registry and Attestation events for fast user/agent lookup. Contracts remain the source of truth.",
+        recommendedEntities: {
+            attestations: process.env.GOLDSKY_ATTESTATION_ENTITIES || "safeHandsAttesteds,attestations",
+            riskRoots: process.env.GOLDSKY_RISK_ROOT_ENTITIES || "riskRootCommitteds,safeHandsRiskRootCommitteds",
+        },
+        network: getActiveNetworkName(),
+        ...readOnlyMeta(),
+    };
+}
+/**
+ * Read-only, keyless, composable on-chain reputation for an address: the count of
+ * SafeHands-verified safe broadcasts attributed to it (+ recency), plus registry
+ * authorization/risk-record context. Any agent can query this as a trust signal.
+ * Zero count = NEUTRAL (no track record yet), never negative.
+ */
+export async function handleAgentReputation(address) {
+    if (!address || !isAddress(address)) {
+        throw new Error("A valid 0x address is required (GET /reputation/:address).");
+    }
+    const [reputation, registry] = await Promise.all([
+        getAgentReputation(address),
+        queryRegistryForTarget(address),
+    ]);
+    return {
+        address,
+        reputation: {
+            verifiedActionCount: reputation.verifiedCount,
+            lastVerifiedActionAt: reputation.lastAttestationAt,
+            configured: reputation.configured,
+            source: reputation.source,
+        },
+        registry: {
+            isAuthorizedAgent: registry.authorized,
+            hasRiskRecord: registry.hasRiskRecord,
+            currentMerkleRoot: registry.currentMerkleRoot,
+        },
+        interpretation: reputation.verifiedCount > 0
+            ? `${reputation.verifiedCount} SafeHands-verified on-chain action(s); positive track record.`
+            : "No SafeHands-verified actions yet: NEUTRAL. Absence of record is not negative; this ledger only records verified-safe actions.",
+        network: getActiveNetworkName(),
+        ...readOnlyMeta(),
+    };
+}
+export async function handleLatestRiskRootIndex() {
+    const goldsky = await lookupLatestRiskRootInGoldsky();
+    // Optional on-chain registry read: queryRegistryForTarget also returns the current root.
+    // It needs a wallet address only to include authorization; use zero address-like fallback
+    // only when a valid operator address is supplied by env.
+    const referenceWallet = process.env.SAFEHANDS_REGISTRY_REFERENCE_WALLET;
+    let onchain = null;
+    if (referenceWallet && isAddress(referenceWallet)) {
+        onchain = { ...(await queryRegistryForTarget(referenceWallet)) };
+    }
+    return {
+        status: goldsky.indexed ? "indexed" : "not_indexed",
+        goldsky,
+        onchain,
+        note: onchain
+            ? "onchain.currentMerkleRoot is included from SafeHandsRegistry. Goldsky is the fast query layer."
+            : "Set SAFEHANDS_REGISTRY_REFERENCE_WALLET to include an on-chain registry read in this endpoint.",
+        network: getActiveNetworkName(),
+        ...readOnlyMeta(),
+    };
+}
+//# sourceMappingURL=indexerRoutes.js.map

package/dist/api/indexerRoutes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexerRoutes.js","sourceRoot":"","sources":["../../src/api/indexerRoutes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAEjC,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,OAAO,EAAE,2BAA2B;QACpC,MAAM,EAAE,aAAa,EAAE;QACvB,IAAI,EAAE,sIAAsI;QAC5I,mBAAmB,EAAE;YACnB,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,iCAAiC;YAC3F,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,gDAAgD;SACtG;QACD,OAAO,EAAE,oBAAoB,EAAE;QAC/B,GAAG,YAAY,EAAE;KAClB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,OAAe;IACzD,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC/C,kBAAkB,CAAC,OAAO,CAAC;QAC3B,sBAAsB,CAAC,OAAwB,CAAC;KACjD,CAAC,CAAC;IACH,OAAO;QACL,OAAO;QACP,UAAU,EAAE;YACV,mBAAmB,EAAE,UAAU,CAAC,aAAa;YAC7C,oBAAoB,EAAE,UAAU,CAAC,iBAAiB;YAClD,UAAU,EAAE,UAAU,CAAC,UAAU;YACjC,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B;QACD,QAAQ,EAAE;YACR,iBAAiB,EAAE,QAAQ,CAAC,UAAU;YACtC,aAAa,EAAE,QAAQ,CAAC,aAAa;YACrC,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;SAC9C;QACD,cAAc,EACZ,UAAU,CAAC,aAAa,GAAG,CAAC;YAC1B,CAAC,CAAC,GAAG,UAAU,CAAC,aAAa,gEAAgE;YAC7F,CAAC,CAAC,gIAAgI;QACtI,OAAO,EAAE,oBAAoB,EAAE;QAC/B,GAAG,YAAY,EAAE;KAClB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB;IAC7C,MAAM,OAAO,GAAG,MAAM,6BAA6B,EAAE,CAAC;IAEtD,yFAAyF;IACzF,0FAA0F;IAC1F,yDAAyD;IACzD,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC;IACxE,IAAI,OAAO,GAAmC,IAAI,CAAC;IACnD,IAAI,eAAe,IAAI,SAAS,CAAC,eAAe,CAAC,EAAE,CAAC;QAClD,OAAO,GAAG,EAAE,GAAG,CAAC,MAAM,sBAAsB,CAAC,eAAgC,CAAC,CAAC,EAAE,CAAC;IACpF,CAAC;IAED,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa;QACnD,OAAO;QACP,OAAO;QACP,IAAI,EAAE,OAAO;YACX,CAAC,CAAC,gGAAgG;YAClG,CAAC,CAAC,gGAAgG;QACpG,OAAO,EAAE,oBAAoB,EAAE;QAC/B,GAAG,YAAY,EAAE;KAClB,CAAC;AACJ,CAAC"}

package/dist/api/paidRoutes.d.ts

@@ -0,0 +1,8 @@
+import type express from "express";
+/**
+ * Register the x402 paid bundle entrypoints. MUST be called AFTER the x402 gate is
+ * installed on PAID_ROUTE_PATHS, so a verified (non-replayed) payment is guaranteed
+ * before any handler here executes.
+ */
+export declare function registerPaidRoutes(app: express.Application): void;
+//# sourceMappingURL=paidRoutes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paidRoutes.d.ts","sourceRoot":"","sources":["../../src/api/paidRoutes.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAcnC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,CAAC,WAAW,GAAG,IAAI,CAuJjE"}

package/dist/api/paidRoutes.js

@@ -0,0 +1,175 @@
+// ─── SafeHands API — x402 Paid Bundle Entrypoints ─────────────────
+// The additive `/paid/*` routes gated by src/api/x402Gate.ts. Each is a BUNDLE
+// entrypoint: gating/charging happens once at the HTTP boundary (the x402 gate is
+// installed on these paths BEFORE these handlers run), then the handler may fan out
+// to several internal analyzers/tools in-process. Internal helper tools are never
+// individually charged.
+//
+// These are read-only value-added endpoints (risk assessment, token security,
+// simulation, market data, full risk report). They wrap the SAME pure tool handlers
+// used by MCP/Anvita and x402Server — no signer, no wallet, no write path. Registered
+// only after the x402 gate, so by the time a handler executes the payment is verified
+// and non-replayed. Handlers return the standard ToolResponse envelope.
+// ────────────────────────────────────────────────────────────────────────────
+import { handleAssessRisk } from "../tools/assessRisk.js";
+import { handleCheckTokenSecurity } from "../tools/checkTokenSecurity.js";
+import { handleSimulateTransaction } from "../tools/simulateTransaction.js";
+import { handleGetTokenPrice } from "../tools/getTokenPrice.js";
+import { handleGetPoolInfo } from "../tools/getPoolInfo.js";
+import { handleSafeHandsRiskReport } from "../tools/safehandsRiskReport.js";
+import { getDodoRoute } from "../lib/dodoApi.js";
+import { CHAIN_ID, PHAROS_ENVIRONMENT, IS_MAINNET } from "../lib/constants.js";
+import { fail, ok, productionSafeMessage } from "../lib/toolResponse.js";
+const SOURCE = "guardian_api_x402";
+/**
+ * Register the x402 paid bundle entrypoints. MUST be called AFTER the x402 gate is
+ * installed on PAID_ROUTE_PATHS, so a verified (non-replayed) payment is guaranteed
+ * before any handler here executes.
+ */
+export function registerPaidRoutes(app) {
+    app.get("/paid/assess-risk", async (req, res) => {
+        try {
+            const { action, tokenIn, tokenOut, amount, toAddress, walletAddress } = req.query;
+            const result = await handleAssessRisk({
+                action: action,
+                tokenIn: tokenIn,
+                tokenOut: tokenOut,
+                amount: amount,
+                toAddress: toAddress,
+                walletAddress: walletAddress,
+            });
+            res.json(result);
+        }
+        catch (e) {
+            res.status(400).json(fail("BAD_REQUEST", productionSafeMessage(e instanceof Error ? e.message : String(e)), false, SOURCE));
+        }
+    });
+    app.get("/paid/check-token-security", async (req, res) => {
+        try {
+            const { tokenAddress, chainId } = req.query;
+            const cid = chainId ? parseInt(chainId, 10) : CHAIN_ID;
+            const result = await handleCheckTokenSecurity({ tokenAddress: tokenAddress, chainId: cid });
+            res.json(result);
+        }
+        catch (e) {
+            res.status(400).json(fail("BAD_REQUEST", productionSafeMessage(e instanceof Error ? e.message : String(e)), false, SOURCE));
+        }
+    });
+    app.get("/paid/simulate-transaction", async (req, res) => {
+        try {
+            const { action, tokenIn, tokenOut, amount, toAddress, walletAddress } = req.query;
+            const result = await handleSimulateTransaction({
+                action: action,
+                tokenIn: tokenIn,
+                tokenOut: tokenOut,
+                amount: amount,
+                toAddress: toAddress,
+                walletAddress: walletAddress,
+            });
+            res.json(result);
+        }
+        catch (e) {
+            res.status(400).json(fail("BAD_REQUEST", productionSafeMessage(e instanceof Error ? e.message : String(e)), false, SOURCE));
+        }
+    });
+    app.get("/paid/token-price", async (req, res) => {
+        try {
+            const { token } = req.query;
+            if (!token || typeof token !== "string") {
+                return res
+                    .status(400)
+                    .json(fail("BAD_REQUEST", "Missing required query parameter: token (PROS, USDC, or USDT)", false, SOURCE));
+            }
+            const result = await handleGetTokenPrice({ token: token });
+            res.json(result);
+        }
+        catch (e) {
+            res.status(400).json(fail("BAD_REQUEST", productionSafeMessage(e instanceof Error ? e.message : String(e)), false, SOURCE));
+        }
+    });
+    app.get("/paid/pool-info", async (req, res) => {
+        try {
+            const { tokenA, tokenB } = req.query;
+            if (!tokenA || !tokenB || typeof tokenA !== "string" || typeof tokenB !== "string") {
+                return res
+                    .status(400)
+                    .json(fail("BAD_REQUEST", "Missing required query parameters: tokenA and tokenB (PROS, USDC, or USDT)", false, SOURCE));
+            }
+            const result = await handleGetPoolInfo({ tokenA: tokenA, tokenB: tokenB });
+            res.json(result);
+        }
+        catch (e) {
+            res.status(400).json(fail("BAD_REQUEST", productionSafeMessage(e instanceof Error ? e.message : String(e)), false, SOURCE));
+        }
+    });
+    app.get("/paid/swap-route", async (req, res) => {
+        try {
+            const { tokenIn, tokenOut, amount } = req.query;
+            if (!tokenIn ||
+                !tokenOut ||
+                !amount ||
+                typeof tokenIn !== "string" ||
+                typeof tokenOut !== "string" ||
+                typeof amount !== "string") {
+                return res
+                    .status(400)
+                    .json(fail("BAD_REQUEST", "Missing required query parameters: tokenIn, tokenOut, amount", false, SOURCE));
+            }
+            const amountNum = Number(amount);
+            if (!Number.isFinite(amountNum) || amountNum <= 0) {
+                return res.status(400).json(fail("BAD_REQUEST", "amount must be a positive number", false, SOURCE));
+            }
+            const quote = await getDodoRoute({
+                fromToken: tokenIn,
+                toToken: tokenOut,
+                amountHuman: amount,
+                walletAddress: "0x0000000000000000000000000000000000000001",
+            });
+            res.json(ok({
+                tokenIn,
+                tokenOut,
+                amountIn: amount,
+                estimatedOutput: quote.routeAvailable ? quote.amountOut : null,
+                priceImpact: quote.priceImpact,
+                routeAvailable: quote.routeAvailable,
+                gasEstimate: quote.gasLimit,
+                wasSubstituted: quote.wasSubstituted,
+                substitutionNote: quote.substitutionNote || null,
+                source: "DODO/FaroSwap route API",
+                chainId: CHAIN_ID,
+                environment: PHAROS_ENVIRONMENT,
+                isMainnet: IS_MAINNET,
+            }));
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            if (message.includes("SWAP_LIQUIDITY_NOT_CONFIGURED")) {
+                return res.status(503).json(fail("SWAP_LIQUIDITY_NOT_CONFIGURED", message, false, SOURCE));
+            }
+            res.status(400).json(fail("BAD_REQUEST", productionSafeMessage(message), false, SOURCE));
+        }
+    });
+    // Flagship bundle: one payment fans out to preflight (multiple analyzers) + registry
+    // lookup in-process. Charged exactly once at the /paid/risk-report entrypoint.
+    app.get("/paid/risk-report", async (req, res) => {
+        try {
+            const { actionType, chainId, amount, tokenAddress, spender, approvalAmount, recipient, walletAddress, includeChecks } = req.query;
+            const result = await handleSafeHandsRiskReport({
+                actionType: actionType,
+                chainId: chainId ? parseInt(chainId, 10) : CHAIN_ID,
+                amount: amount,
+                tokenAddress: tokenAddress,
+                spender: spender,
+                approvalAmount: approvalAmount,
+                recipient: recipient,
+                walletAddress: walletAddress,
+                includeChecks: includeChecks === undefined ? undefined : includeChecks !== "false",
+            });
+            res.status(result.success ? 200 : 400).json(result);
+        }
+        catch (e) {
+            res.status(400).json(fail("BAD_REQUEST", productionSafeMessage(e instanceof Error ? e.message : String(e)), false, SOURCE));
+        }
+    });
+}
+//# sourceMappingURL=paidRoutes.js.map

package/dist/api/paidRoutes.js.map

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

package/dist/api/prepareRoutes.d.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import type { ReadOnlyChainAccess } from "../lib/analysis/index.js";
+import type { AgentRouteOptions } from "./agentRoutes.js";
+declare const prepareTxSchema: z.ZodObject<{
+    to: z.ZodString;
+    data: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    chainId: z.ZodOptional<z.ZodNumber>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    to: z.ZodString;
+    data: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    chainId: z.ZodOptional<z.ZodNumber>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    to: z.ZodString;
+    data: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    chainId: z.ZodOptional<z.ZodNumber>;
+}, z.ZodTypeAny, "passthrough">>;
+export type PrepareTxInput = z.input<typeof prepareTxSchema>;
+/**
+ * POST /prepare/tx — SafeHands-checked, prepare-only unsigned transaction.
+ * Returns `preparedTransaction` + `requiresUserSignature: true` (PREPARE_ONLY) when
+ * the action is not blocked; `BLOCK` with no prepared tx otherwise.
+ */
+export declare function handlePrepareTx(raw: unknown, access?: ReadOnlyChainAccess, opts?: AgentRouteOptions): Promise<{
+    readOnly: true;
+    executionAvailable: boolean;
+    decision: import("../lib/guardian/decision.js").GuardianDecision;
+    /** The underlying SafeHands verdict (ALLOW / BLOCK / REQUIRE_CONFIRMATION). */
+    guardianDecision: import("../lib/guardian/decision.js").GuardianDecision;
+    riskLevel: import("../lib/analysis/types.js").AnalyzerRiskLevel;
+    reasons: string[];
+    /** True when the underlying verdict needs explicit user confirmation before signing. */
+    confirmationRequired: boolean;
+    /** True only when an unsigned tx was prepared (never on BLOCK). */
+    requiresUserSignature: boolean;
+    preparedTransaction: {
+        to: `0x${string}`;
+        data: string;
+        value: string;
+        chainId: number;
+        from: null;
+        unsigned: boolean;
+        signature: null;
+    } | null;
+    network: import("../lib/networks.js").NetworkName;
+    chainId: number;
+    policyPreset: string | null;
+    policyVersion: string;
+    /** SafeHands signs nothing and broadcasts nothing — the caller does both externally. */
+    signingAvailable: boolean;
+    broadcastAvailable: boolean;
+    nextStep: string;
+    source: string;
+}>;
+export {};
+//# sourceMappingURL=prepareRoutes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prepareRoutes.d.ts","sourceRoot":"","sources":["../../src/api/prepareRoutes.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;AAM1D,QAAA,MAAM,eAAe;;;;;;;;;;;;;;;gCAOL,CAAC;AAEjB,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE7D;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,OAAO,EACZ,MAAM,CAAC,EAAE,mBAAmB,EAC5B,IAAI,GAAE,iBAAsB;;;;IAuC1B,+EAA+E;;;;IAI/E,wFAAwF;;IAExF,mEAAmE;;;;;;;;;;;;;;;IAOnE,wFAAwF;;;;;GAS3F"}

package/dist/api/prepareRoutes.js

@@ -0,0 +1,90 @@
+// ─── SafeHands API — Prepare-Only Transaction Mode ───────
+// Builds an UNSIGNED transaction request object AFTER a SafeHands check. SafeHands
+// holds no keys: it NEVER signs, NEVER broadcasts, NEVER creates/manages a wallet,
+// and NEVER publishes on-chain. The flow:
+//   1. validate the caller's intended call (to / data / value),
+//   2. run the real escalate-only SafeHands check (policy presets apply),
+//   3. if the verdict is BLOCK → prepare NOTHING (a BLOCK is never weakened),
+//      otherwise → return the unsigned tx + `requiresUserSignature: true` and a
+//      `PREPARE_ONLY` decision (the caller signs + broadcasts externally).
+// Pure + read-only by construction; no signer/wallet/write primitives 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";
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+const prepareTxSchema = z
+    .object({
+    to: z.string(),
+    data: z.string().optional(),
+    value: z.string().optional(),
+    chainId: z.number().optional(),
+})
+    .passthrough(); // policyPreset / policy are read by the server (agentPolicyOpts)
+/**
+ * POST /prepare/tx — SafeHands-checked, prepare-only unsigned transaction.
+ * Returns `preparedTransaction` + `requiresUserSignature: true` (PREPARE_ONLY) when
+ * the action is not blocked; `BLOCK` with no prepared tx otherwise.
+ */
+export async function handlePrepareTx(raw, access, opts = {}) {
+    const input = prepareTxSchema.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.");
+    }
+    const network = getActiveNetwork();
+    const chainId = input.chainId ?? network.chainId;
+    // Real escalate-only SafeHands check (policy presets apply via opts) — a BLOCK can
+    // never be weakened by any preset/request.
+    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";
+    // Unsigned transaction request object — no signer, no signature, no nonce/gas.
+    const preparedTransaction = blocked
+        ? null
+        : {
+            to: input.to,
+            data: input.data ?? "0x",
+            value: input.value ?? "0",
+            chainId,
+            from: null, // SafeHands holds no keys
+            unsigned: true,
+            signature: null,
+        };
+    return {
+        decision: verdict.decision,
+        /** The underlying SafeHands verdict (ALLOW / BLOCK / REQUIRE_CONFIRMATION). */
+        guardianDecision: verdict.decision,
+        riskLevel: verdict.riskLevel,
+        reasons: verdict.reasons,
+        /** True when the underlying verdict needs explicit user confirmation before signing. */
+        confirmationRequired,
+        /** True only when an unsigned tx was prepared (never on BLOCK). */
+        requiresUserSignature: !blocked,
+        preparedTransaction,
+        network: getActiveNetworkName(),
+        chainId,
+        policyPreset: verdict.policyPreset,
+        policyVersion: verdict.policyVersion,
+        /** SafeHands signs nothing and broadcasts nothing — the caller does both externally. */
+        signingAvailable: false,
+        broadcastAvailable: false,
+        nextStep: blocked
+            ? "Do not prepare: the action is unsafe. Abort and surface the block reason."
+            : "WARNING: This prepared tx is for EXTERNAL broadcast only. SafeHands holds no keys. Do not submit this to /broadcast/signed because no internal record was saved.",
+        source: "prepare_tx",
+        ...readOnlyMeta(), // readOnly: true, executionAvailable: false
+    };
+}
+//# sourceMappingURL=prepareRoutes.js.map

package/dist/api/prepareRoutes.js.map

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

package/dist/api/response.d.ts

@@ -0,0 +1,39 @@
+import type { PharosNetwork } from "../lib/networks.js";
+import type { GuardianDecision } from "../lib/guardian/decision.js";
+import { type RpcEvidence, type GasEvidence } from "../lib/pharos/rpcEvidence.js";
+import type { ReadOnlyChainAccess } from "../lib/analysis/types.js";
+export { ok, fail } from "../lib/toolResponse.js";
+export interface ReadOnlyMeta {
+    /** Always true — the API never writes, signs, sends, or publishes. */
+    readOnly: true;
+    /** False by default (mainnet execution disabled + gates off). */
+    executionAvailable: boolean;
+}
+/** Stamp a payload as read-only and report whether execution is available. */
+export declare function readOnlyMeta(): ReadOnlyMeta;
+export interface RpcMeta {
+    rpcEvidence: RpcEvidence;
+    gasEvidence: GasEvidence;
+    /** Alias of `rpcEvidence` for spec-compliance (same content). */
+    pharosEvidence: RpcEvidence;
+}
+/**
+ * Read-only RPC + gas capability evidence for a response. Deterministic, offline,
+ * and secret-free (no RPC URL/API key — only the redacted provider name). Evidence
+ * is metadata: it never relaxes a SafeHands decision.
+ */
+export declare function rpcMeta(network: PharosNetwork, access?: ReadOnlyChainAccess): RpcMeta;
+export interface ExplorerLinks {
+    address?: string;
+    tx?: string;
+    socialScanAddress?: string;
+    socialScanTx?: string;
+}
+/** Build read-only explorer links from a network's public explorer URLs. */
+export declare function explorerLinks(network: PharosNetwork, ref: {
+    address?: string | null;
+    txHash?: string | null;
+}): ExplorerLinks;
+/** Aggregate analyzer decisions to the most severe public decision. */
+export declare function worstDecision(decisions: GuardianDecision[]): GuardianDecision;
+//# sourceMappingURL=response.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/api/response.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAA4B,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC5G,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,QAAQ,EAAE,IAAI,CAAC;IACf,iEAAiE;IACjE,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,IAAI,YAAY,CAE3C;AAED,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,WAAW,CAAC;IACzB,iEAAiE;IACjE,cAAc,EAAE,WAAW,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAGrF;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAC3B,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACvD,aAAa,CAaf;AAUD,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,CAG7E"}

package/dist/api/response.js

@@ -0,0 +1,53 @@
+// ─── SafeHands API — Response Helpers (read-only) ─────────────
+// Shared response shaping for the read-only SafeHands API. `readOnlyMeta()`
+// stamps every payload as read-only and reports executionAvailable (false by
+// default — mainnet executionAllowed=false and all gates default off). No helper
+// here can sign, send, or publish.
+// ────────────────────────────────────────────────────────────────────────
+import { isExecutionAvailable } from "../lib/config.js";
+import { rpcEvidence, gasEvidence } from "../lib/pharos/rpcEvidence.js";
+export { ok, fail } from "../lib/toolResponse.js";
+/** Stamp a payload as read-only and report whether execution is available. */
+export function readOnlyMeta() {
+    return { readOnly: true, executionAvailable: isExecutionAvailable() };
+}
+/**
+ * Read-only RPC + gas capability evidence for a response. Deterministic, offline,
+ * and secret-free (no RPC URL/API key — only the redacted provider name). Evidence
+ * is metadata: it never relaxes a SafeHands decision.
+ */
+export function rpcMeta(network, access) {
+    const evidence = rpcEvidence(network, access);
+    return { rpcEvidence: evidence, gasEvidence: gasEvidence(access), pharosEvidence: evidence };
+}
+/** Build read-only explorer links from a network's public explorer URLs. */
+export function explorerLinks(network, ref) {
+    const base = network.explorerUrl.replace(/\/+$/, "");
+    const social = network.socialScanUrl?.replace(/\/+$/, "");
+    const links = {};
+    if (ref.address) {
+        links.address = `${base}/address/${ref.address}`;
+        if (social)
+            links.socialScanAddress = `${social}/address/${ref.address}`;
+    }
+    if (ref.txHash) {
+        links.tx = `${base}/tx/${ref.txHash}`;
+        if (social)
+            links.socialScanTx = `${social}/tx/${ref.txHash}`;
+    }
+    return links;
+}
+// Severity order: most severe wins when aggregating multiple analyzers.
+const SEVERITY = {
+    BLOCK: 3,
+    REQUIRE_CONFIRMATION: 2,
+    PREPARE_ONLY: 1,
+    ALLOW: 0,
+};
+/** Aggregate analyzer decisions to the most severe public decision. */
+export function worstDecision(decisions) {
+    if (decisions.length === 0)
+        return "REQUIRE_CONFIRMATION";
+    return decisions.reduce((worst, d) => (SEVERITY[d] > SEVERITY[worst] ? d : worst), "ALLOW");
+}
+//# sourceMappingURL=response.js.map

package/dist/api/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/api/response.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,4EAA4E;AAC5E,6EAA6E;AAC7E,iFAAiF;AACjF,mCAAmC;AACnC,2EAA2E;AAE3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAsC,MAAM,8BAA8B,CAAC;AAG5G,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AASlD,8EAA8E;AAC9E,MAAM,UAAU,YAAY;IAC1B,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,EAAE,CAAC;AACxE,CAAC;AASD;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,OAAsB,EAAE,MAA4B;IAC1E,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9C,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC;AAC/F,CAAC;AASD,4EAA4E;AAC5E,MAAM,UAAU,aAAa,CAC3B,OAAsB,EACtB,GAAwD;IAExD,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAChB,KAAK,CAAC,OAAO,GAAG,GAAG,IAAI,YAAY,GAAG,CAAC,OAAO,EAAE,CAAC;QACjD,IAAI,MAAM;YAAE,KAAK,CAAC,iBAAiB,GAAG,GAAG,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,CAAC;IAC3E,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QACf,KAAK,CAAC,EAAE,GAAG,GAAG,IAAI,OAAO,GAAG,CAAC,MAAM,EAAE,CAAC;QACtC,IAAI,MAAM;YAAE,KAAK,CAAC,YAAY,GAAG,GAAG,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,CAAC;IAChE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,wEAAwE;AACxE,MAAM,QAAQ,GAAqC;IACjD,KAAK,EAAE,CAAC;IACR,oBAAoB,EAAE,CAAC;IACvB,YAAY,EAAE,CAAC;IACf,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,uEAAuE;AACvE,MAAM,UAAU,aAAa,CAAC,SAA6B;IACzD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,sBAAsB,CAAC;IAC1D,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9F,CAAC"}