safehands-pharos 1.4.0 → 2.6.0

package/SECURITY.md

@@ -0,0 +1,112 @@
+# Security Policy: SafeHands-Pharos
+
+## Scope
+
+SafeHands is a **mainnet-first, read-only-by-default** transaction firewall for AI agents on **Pharos Pacific (chain 1672)**: read/check/analyze runs on mainnet, and the hosted backend holds no keys. **Attestations publish on Pacific Mainnet using a segregated operational key**. The safety architecture is production-inspired but is **not audited for mainnet custody**, which is why user execution/signing remains strictly offline/self-hosted.
+
+## Threat Model
+
+SafeHands protects agents from:
+
+- Unintended **execution/signing on mainnet**, blocked **by default**: the hosted/default posture ships `WRITE_TOOLS_ENABLED=false` and holds no keys, so only read-only checks run on Pacific Mainnet. Self-hosted operators can opt in to execution via explicit env flags (see "Self-Hosted Backend"); those write paths are experimental and unaudited.
+- Unlimited token approvals (blocked by default)
+- SSRF via x402 URLs (localhost, private IPs, metadata IPs, IPv6 local all blocked)
+- Overspending (per-tx + daily caps enforced; swaps of tokens that cannot be priced against the USD caps, outside PROS/WPROS/USDC/USDT and the official registry, are denied by default rather than silently uncounted)
+- Executing/approving a token whose **security intelligence is missing** (GoPlus outage or token not yet indexed): the direct write path fails closed with `TOKEN_INTEL_UNAVAILABLE`; a caller `confirm` cannot substitute for a review that never happened. Registry-canonical tokens (identity verified on the official token registry) remain confirmable.
+- Unauthorized managed wallet execution for the heavier write paths: swap/payment/approve via a custodial wallet require SafeHandsRegistry authorization (`REQUIRE_AUTHORIZED_AGENT_FOR_WRITE`, default on). x402 is permissionless-first: self-signed x402 needs no authorization, and managed x402 is allowlist-gated only when `REQUIRE_AUTHORIZED_AGENT_FOR_X402=true` is opted in.
+- Invalid amounts, zero addresses, unknown tokens (strict validation)
+- Sends/approvals to operator-denylisted recipients (hard-BLOCK via `SAFEHANDS_RECIPIENT_DENYLIST`; empty by default, no fabricated scam list. Deeper address-poisoning / first-time-recipient checks are indexer-backed and deferred, not faked.)
+- Prompt/runtime injection of policy limits (policy stored in files, not runtime params)
+
+**Confirmation trust anchor.** The `confirm=true` flag accepted by the soft decision tiers (`REQUIRE_CONFIRMATION` / `REQUIRE_TOKEN_REVIEW`) is **caller-attested**: it is supplied by the calling agent, the very party SafeHands is guarding. The real trust anchor is therefore the **MCP host / human operator** who relays that confirmation; SafeHands cannot verify that a human actually reviewed the action. Hard stops (`BLOCK`, `REQUIRE_FUNDING`, missing token intel) never accept it, and the HTTP broadcast relay refuses confirmation-tier records entirely (no trusted confirmation channel exists there). See `docs/DECISION_CONTRACT.md`.
+
+## What SafeHands Does NOT Protect Against
+
+- Smart contract vulnerabilities in third-party tokens or pools
+- Private key compromise at the OS/process level
+- Denial of service against the RPC endpoint
+- Social engineering of the human operator
+
+## Key Management
+
+- Managed wallets are encrypted with AES-256-GCM (not KMS/Vault grade)
+- Private keys are never returned in tool responses or logged
+- The `SAFEHANDS_ATTESTER_PRIVATE_KEY` is an operational-only key for publishing attestations and must never be committed
+- `.env` is gitignored; `.env.example` uses placeholders only
+
+## Self-Hosted Backend: Security Profile
+
+If you optionally self-host the reference backend on a public host, run it under the
+**Mainnet Production Profile** and keep it zero-custody. A startup guard
+(`src/lib/productionGuards.ts`) enforces this when `NODE_ENV=production`:
+
+- **Zero-custody, enforced.** The public host must set `WALLET_MODE=none` and
+  `WRITE_TOOLS_ENABLED=false`. Managed execution (`WALLET_MODE=managed-mainnet` +
+  `WRITE_TOOLS_ENABLED=true`) **fails fast at boot** on a public host unless the
+  operator explicitly accepts the custody risk with
+  `SAFEHANDS_ALLOW_MANAGED_ON_PUBLIC=true` (self-hosted single-tenant only).
+- **Wallet separation (three roles).**
+  - **Owner / deployer wallet**: governs the contracts. **Never store it on
+    a container host (Docker / VPS / Fly)** or any hosted env; use it locally for
+    deployment only.
+  - **Attester wallet** (`SAFEHANDS_ATTESTER_PRIVATE_KEY`): gas-only, dedicated,
+    **low balance**; only publishes attestations / risk records after validation.
+  - **x402 facilitator wallet** (`X402_FACILITATOR_PRIVATE_KEY`): gas-only,
+    dedicated, low balance; only settles x402 payments. `X402_PAY_TO` is a receiver
+    **address** (no key on the host).
+- **Access model.** Public users/agents pay via **x402** (no API-key onboarding).
+  API keys (`SAFEHANDS_API_KEYS`) are **optional, admin/internal only**; the free
+  read tier stays open (`SAFEHANDS_REQUIRE_API_KEY=false`).
+- **CORS.** Tighten `CORS_ORIGIN` / `SAFEHANDS_CORS_ORIGIN` to your domain(s) for
+  guarded/paid surfaces in production (wildcard is acceptable only for the public
+  read tier; the guard warns on wildcard in production).
+- **Durable state.** Mount a persistent volume and set `SAFEHANDS_STATE_DIR` (e.g.
+  `/data`); the guard warns if state is ephemeral in production (an ephemeral host
+  with no persistent volume). Run a single instance; no horizontal replicas
+  (single authoritative state domain).
+- **Not formally audited.** The safety architecture is production-inspired but has
+  **not** undergone a formal external security audit.
+
+See [`docs/deployment/ARCHITECTURE_DECISION.md`](docs/deployment/ARCHITECTURE_DECISION.md).
+
+## SafeHandsRiskRegistry
+
+| Field | Value |
+|---|---|
+| Registry Address | `0x428e02bf85412e7242d991cd6725ec59e8b06c8d` |
+| Attestation Address | `0x71a7a87b3b1ab6d86204cad691bb32fd75b4588c` |
+| Network | Pharos Pacific Mainnet (1672) |
+| Authorization | Required for attestation publishing only |
+
+Both addresses are **live on Pharos Pacific Mainnet (1672)** and independently verifiable
+(`eth_getCode` returns deployed bytecode; viewable on `https://www.pharosscan.xyz`). The
+setup wizard (`src/init.ts`) writes them as defaults; redeploy with
+`scripts/deploy-safehands.ts` to override.
+
+Preflight, read-only, user-signed, and env wallet modes do **not** require RiskRegistry authorization.
+
+**Operator-trust caveat.** The registry/attestation contracts are the intended trust anchor, but they are *operator-permissioned*: any address the owner has authorized can call `commitRiskRoot` (SafeHandsRiskRegistry) or `attest` (SafeHandsAttestation). A compromised or malicious authorized operator could therefore publish a poisoned risk root or mint a reputation attestation. The contracts are otherwise sound (`Ownable2Step`, `renounceOwnership` disabled, double-hashed Merkle leaves, write-once attestations, no reentrancy), so the centralization of the *authorized-operator set* is the real residual trust assumption whenever the registry is presented as an oracle. Consumers should treat published risk roots as **operator-attested, not trustless**, and pin/verify the operator set they rely on.
+
+## Reporting Vulnerabilities
+
+If you discover a security issue, please open a GitHub issue at [github.com/SZtch/safehands-pharos/issues](https://github.com/SZtch/safehands-pharos/issues) or contact the maintainer directly.
+
+## Network & Execution Disclaimer
+
+SafeHands is **mainnet-first for read/check/analyze on Pharos Pacific (1672)** and holds no keys in hosted mode. **Execution and signing are kept entirely offline**: mainnet *execution* is blocked by design on the hosted server. The safety architecture is production-inspired but has not undergone formal security audit.
+
+## Runtime dependency audit note
+
+`npm audit` currently reports vulnerabilities in the Hardhat/Mocha developer-tooling tree (`@nomicfoundation/hardhat-toolbox-viem`, `hardhat-ignition`, `mocha`, and transitive packages such as `lodash-es`, `serialize-javascript`, and `elliptic`). These packages are used for local contract testing and deployment tooling, not by the production SafeHands API/x402 runtime path.
+
+For the Mainnet Production Profile (Single-Instance Production Architecture), deploy with:
+
+```bash
+npm ci                                  # dev deps included: tsc lives there; the prepare hook compiles dist/
+npm prune --omit=dev                    # then drop dev tooling (Hardhat/Mocha/tsc) from the host
+NODE_ENV=production npm run start:api   # the boot guards only run with NODE_ENV=production; always set it
+```
+
+(`npm ci --omit=dev` alone cannot work here: the `prepare` hook runs `tsc`, which is a devDependency. On container hosts, prefer the repo `Dockerfile`; its multi-stage build does the same compile-then-prune split.)
+
+Do not run Hardhat/Mocha tooling on the public API host. A forced audit fix can downgrade/change Hardhat toolbox versions and may break the Hardhat 3 setup, so it is intentionally not applied blindly. Track these as dev-tooling findings and re-run `npm audit` after Hardhat/Mocha publish compatible patched releases.

package/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: safehands-pharos
+description: Pharos Pacific Mainnet-first SafeHands Agent for AI-agent transaction safety, x402 preflight, token checks, and gated execution.
+---
+
+# SafeHands Pharos
+
+SafeHands is an **agent surface of 33 registered MCP tools** for the Pharos ecosystem. It protects AI agents by checking transaction intent before the agent signs, approves, swaps, pays an x402 resource, or publishes risk data, and exposes an **on-chain agent reputation oracle** (`get_agent_reputation`) so any agent can read a counterparty's verified-safe track record as a composable trust signal.
+
+SafeHands is:
+
+> Read-only SafeHands by default, wallet handoff/user-signed prepare available, optional gated execution only with explicit env flags and authorization.
+
+## Core capabilities
+
+1. **Policy preflight**: Return deterministic `ALLOW`, `BLOCK`, `REQUIRE_CONFIRMATION`, or `PREPARE_ONLY` decisions for payments, approvals, swaps, contract calls, and x402 requests. In the read-only default, execution intents come back as `PREPARE_ONLY`: validated for you to sign externally, never executed here.
+2. **Risk analysis**: Produce structured risk evidence, human-readable reports, and risk-score explanations.
+3. **Pacific Mainnet token checks**: Classify tokens using the active Pharos network registry. Unsupported Pacific Mainnet tokens fail clearly instead of falling back to Atlantic/testnet addresses.
+4. **x402 safety**: Validate URL, chain, token, payment limit, and signer readiness. Default Pacific Mainnet x402 token is USDC; WPROS/PROS-compatible wrapped payment is also supported. **Permissionless-first**: `safehands_x402_preflight` needs no key and no authorization, and self-signed x402 payments (the agent's own `X402_SIGNER_PRIVATE_KEY`) require no SafeHandsRegistry authorization; only the optional managed/custodial wallet path can be allowlist-gated.
+5. **Gated execution**: Optional write tools for swaps, payments, approvals, x402 fetches, and risk publishing are disabled by default and require explicit operator configuration. These write tools are experimental and unaudited; they are opt-in, self-hosted, single-tenant only.
+6. **On-chain layer**: Includes `SafeHandsRegistry` and `SafeHandsAttestation` contracts for registry and proof workflows when configured.
+
+## What SafeHands refuses by default
+
+- It will not hold or create a wallet in default mode.
+- It will not sign transactions in default mode.
+- It will not broadcast transactions in default mode.
+- It will not allow unlimited token approvals by default.
+- It will not execute or approve a token whose security intelligence is unavailable (provider outage / token not yet indexed): fail-closed, not confirmable; registry-canonical tokens excepted.
+- It will not swap an input token it cannot price against the USD spend caps (denied by default).
+- It will not fetch localhost/private-IP x402 URLs unless local demo mode is explicitly enabled.
+- It will not use Atlantic/testnet token addresses for Pacific Mainnet token operations.
+
+## Example tasks
+
+- “Run SafeHands preflight before this agent approves USDC.”
+- “Check whether this token is canonical on Pharos Pacific Mainnet.”
+- “Explain why this approval was blocked.”
+- “Check x402 preflight for this paid API before signing.”
+- “Check my managed agent wallet health.”
+
+## Information needed from the user or agent
+
+- Target chain ID or network, if not using the default Pacific Mainnet.
+- Transaction intent: payment, approval, swap, contract call, x402 fetch, or risk publishing.
+- Token symbol/address and amount when relevant.
+- Recipient, spender, target contract, or URL when relevant.
+- Agent ID only when using managed-wallet mode.
+
+## Deliverables
+
+- Structured JSON response with `success`, `data`, `error`, and `timestamp`.
+- SafeHands decision and risk level.
+- Plain-English reasons and required actions.
+- Network, token-registry, signer, and policy evidence where relevant.
+
+## Required usage by other agents
+
+Before executing any write transaction, a calling agent should call `safehands_preflight_check` or the relevant SafeHands tool. If SafeHands returns `BLOCK`, the agent must stop and explain the reason to the user. If SafeHands returns `REQUIRE_CONFIRMATION`, the agent should ask the user for explicit confirmation or further review before continuing.

package/contracts/SafeHandsAttestation.sol

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+interface ISafeHandsRegistry {
+    function owner() external view returns (address);
+
+    function isAuthorizedOperator(address operator) external view returns (bool);
+}
+
+/**
+ * @title SafeHandsAttestation
+ * @notice Immutable, append-only, privacy-preserving attestation ledger for
+ *         SafeHands verified broadcasts — the proof half of the SafeHands
+ *         on-chain layer (pair with the governed {SafeHandsRegistry}).
+ *
+ * "If SafeHands broadcasts it, SafeHands attests it."
+ *
+ * Attestations are write-once and never mutated or deleted: the integrity of the
+ * ledger IS its value. Only hashed context is published (preparedTransactionHash,
+ * txHash, policyHash, metadataHash) — never raw calldata, keys, recipients,
+ * amounts, or private intents.
+ *
+ * Attester authorization is delegated to {SafeHandsRegistry} so there is a single
+ * source of truth for "who is a SafeHands operator". Any contract or agent can
+ * compose on `isAttested(txHash)` as a trust gate.
+ */
+contract SafeHandsAttestation {
+    /// @notice The registry that governs operator authorization.
+    ISafeHandsRegistry public immutable registry;
+
+    // Action types as bytes32 (future-proof, privacy-preserving labels).
+    bytes32 public constant ACTION_PAYMENT = keccak256("PAYMENT");
+    bytes32 public constant ACTION_SWAP = keccak256("SWAP");
+    bytes32 public constant ACTION_BRIDGE = keccak256("BRIDGE");
+    bytes32 public constant ACTION_APPROVAL = keccak256("APPROVAL");
+    bytes32 public constant ACTION_CONTRACT_CALL = keccak256("CONTRACT_CALL");
+    bytes32 public constant ACTION_NFT = keccak256("NFT");
+    bytes32 public constant ACTION_DEFI = keccak256("DEFI");
+    bytes32 public constant ACTION_TREASURY = keccak256("TREASURY");
+    bytes32 public constant ACTION_AGENT_ACTION = keccak256("AGENT_ACTION");
+    bytes32 public constant ACTION_X402_PAYMENT = keccak256("X402_PAYMENT");
+    bytes32 public constant ACTION_UNKNOWN = keccak256("UNKNOWN");
+
+    struct Attestation {
+        bytes32 preparedTransactionHash;
+        bytes32 txHash;
+        uint256 chainId;
+        bytes32 actionType;
+        bytes32 policyHash;
+        bytes32 metadataHash;
+        address agent;
+        address attester;
+        uint64 timestamp;
+    }
+
+    uint256 public attestationCount;
+    mapping(bytes32 => Attestation) private _byTxHash;
+    mapping(bytes32 => bool) public hasAttestedTx;
+    mapping(bytes32 => bool) public hasAttestedPreparedTx;
+
+    /// @notice Per-agent reputation: count of SafeHands-verified safe broadcasts
+    ///         attributed to an address, plus recency. This is the composable
+    ///         trust signal other agents can read via {reputationOf}.
+    mapping(address => uint256) public attestationCountByAgent;
+    mapping(address => uint64) public lastAttestationAt;
+
+    event SafeHandsAttested(
+        bytes32 indexed preparedTransactionHash,
+        bytes32 indexed txHash,
+        address indexed agent,
+        uint256 chainId,
+        bytes32 actionType,
+        bytes32 policyHash,
+        bytes32 metadataHash,
+        address attester
+    );
+
+    error ZeroRegistry();
+    error ZeroHash();
+    error InvalidChainId();
+    error UnauthorizedAttester();
+    error AlreadyAttested();
+
+    modifier onlyOperator() {
+        if (msg.sender != registry.owner() && !registry.isAuthorizedOperator(msg.sender)) {
+            revert UnauthorizedAttester();
+        }
+        _;
+    }
+
+    constructor(address registry_) {
+        if (registry_ == address(0)) revert ZeroRegistry();
+        registry = ISafeHandsRegistry(registry_);
+    }
+
+    /**
+     * @notice Record an immutable attestation that SafeHands verified and broadcast
+     *         an action. Reverts if either the txHash or preparedTransactionHash has
+     *         already been attested (no overwrites, ever).
+     */
+    function attest(
+        bytes32 preparedTransactionHash,
+        bytes32 txHash,
+        uint256 chainId,
+        bytes32 actionType,
+        bytes32 policyHash,
+        bytes32 metadataHash,
+        address agent
+    ) external onlyOperator {
+        if (preparedTransactionHash == bytes32(0) || txHash == bytes32(0)) revert ZeroHash();
+        if (chainId == 0) revert InvalidChainId();
+        if (hasAttestedTx[txHash]) revert AlreadyAttested();
+        if (hasAttestedPreparedTx[preparedTransactionHash]) revert AlreadyAttested();
+
+        hasAttestedTx[txHash] = true;
+        hasAttestedPreparedTx[preparedTransactionHash] = true;
+        uint64 ts = uint64(block.timestamp);
+        _byTxHash[txHash] = Attestation({
+            preparedTransactionHash: preparedTransactionHash,
+            txHash: txHash,
+            chainId: chainId,
+            actionType: actionType,
+            policyHash: policyHash,
+            metadataHash: metadataHash,
+            agent: agent,
+            attester: msg.sender,
+            timestamp: ts
+        });
+        unchecked {
+            ++attestationCount;
+        }
+
+        // Per-agent reputation: only attribute when an agent address is provided,
+        // so the zero address is never polluted with a reputation.
+        if (agent != address(0)) {
+            unchecked {
+                ++attestationCountByAgent[agent];
+            }
+            lastAttestationAt[agent] = ts;
+        }
+
+        emit SafeHandsAttested(
+            preparedTransactionHash,
+            txHash,
+            agent,
+            chainId,
+            actionType,
+            policyHash,
+            metadataHash,
+            msg.sender
+        );
+    }
+
+    // ─── Views (composable) ────────────────────────────────────────────────
+
+    function isAttested(bytes32 txHash) external view returns (bool) {
+        return hasAttestedTx[txHash];
+    }
+
+    function isPreparedAttested(bytes32 preparedTransactionHash) external view returns (bool) {
+        return hasAttestedPreparedTx[preparedTransactionHash];
+    }
+
+    function getAttestation(bytes32 txHash) external view returns (Attestation memory) {
+        return _byTxHash[txHash];
+    }
+
+    /**
+     * @notice Composable, privacy-preserving reputation for an agent/address:
+     *         the count of SafeHands-verified safe broadcasts attributed to it and
+     *         the most recent attestation time. Any contract or agent can read this
+     *         as a trust signal. Zero count = no track record yet (treat as neutral,
+     *         never as a negative — this ledger only records verified-safe actions).
+     */
+    function reputationOf(address agent)
+        external
+        view
+        returns (uint256 verifiedCount, uint64 lastAt)
+    {
+        return (attestationCountByAgent[agent], lastAttestationAt[agent]);
+    }
+}

package/contracts/SafeHandsRegistry.sol

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import "@openzeppelin/contracts/utils/cryptography/MerkleProof.sol";
+import "@openzeppelin/contracts/access/Ownable2Step.sol";
+
+/**
+ * @title SafeHandsRegistry
+ * @notice L2 Merkle Batching architecture for SafeHands Risk Records.
+ *         To prevent state bloat, risk records are no longer stored individually.
+ *         Instead, operators commit a single Merkle Root representing thousands
+ *         of risk assessments.
+ * @dev Ownership uses OpenZeppelin {Ownable2Step}: a transfer only completes when
+ *      the incoming owner calls {acceptOwnership}, so a mistyped address can never
+ *      orphan governance. {renounceOwnership} is disabled — this registry is the
+ *      trust root for operators/agents and must always retain an owner.
+ */
+contract SafeHandsRegistry is Ownable2Step {
+    enum RiskLevel {
+        LOW,
+        MEDIUM,
+        HIGH,
+        CRITICAL
+    }
+
+    enum Recommendation {
+        PROCEED,
+        CAUTION,
+        BLOCK
+    }
+
+    /// @notice Operators may publish risk roots.
+    mapping(address => bool) public isAuthorizedOperator;
+
+    /// @notice Agents (managed wallets) cleared for guarded execution.
+    mapping(address => bool) public isAuthorizedAgent;
+
+    /// @notice The latest committed Merkle Root of all active risk records.
+    bytes32 public currentMerkleRoot;
+
+    /// @notice Off-chain availability pointer (e.g. IPFS CID or Arweave Tx)
+    string public currentDataURI;
+
+    event OperatorSet(address indexed operator, bool authorized);
+    event AgentSet(address indexed agent, bool authorized);
+
+    event RiskRootCommitted(
+        bytes32 indexed root,
+        string dataURI,
+        address indexed operator
+    );
+
+    error NotOperator();
+    error ZeroAddress();
+    error Expired();
+    error InvalidRoot();
+    error EmptyDataURI();
+    error RenounceDisabled();
+
+    modifier onlyOperator() {
+        if (msg.sender != owner() && !isAuthorizedOperator[msg.sender]) revert NotOperator();
+        _;
+    }
+
+    constructor() Ownable(msg.sender) {}
+
+    // ─── Governance ────────────────────────────────────────────────────────
+
+    /// @notice Disabled. Hand ownership off via the two-step
+    ///         {transferOwnership} + {acceptOwnership} instead — the registry
+    ///         must never be left ownerless.
+    function renounceOwnership() public pure override {
+        revert RenounceDisabled();
+    }
+
+    function setOperator(address operator, bool authorized) external onlyOwner {
+        if (operator == address(0)) revert ZeroAddress();
+        isAuthorizedOperator[operator] = authorized;
+        emit OperatorSet(operator, authorized);
+    }
+
+    function setAuthorizedAgent(address agent, bool authorized) external onlyOwner {
+        if (agent == address(0)) revert ZeroAddress();
+        isAuthorizedAgent[agent] = authorized;
+        emit AgentSet(agent, authorized);
+    }
+
+    function setAuthorizedAgents(address[] calldata agents, bool authorized) external onlyOwner {
+        for (uint256 i; i < agents.length; ++i) {
+            address agent = agents[i];
+            if (agent == address(0)) revert ZeroAddress();
+            isAuthorizedAgent[agent] = authorized;
+            emit AgentSet(agent, authorized);
+        }
+    }
+
+    // ─── L2 Merkle Batching ────────────────────────────────────────────────
+
+    /**
+     * @notice Commits a new Merkle root representing a batch of risk records.
+     * @param root The keccak256 Merkle root.
+     * @param dataURI Pointer to the off-chain JSON containing the leaves (IPFS).
+     */
+    function commitRiskRoot(bytes32 root, string calldata dataURI) external onlyOperator {
+        if (root == bytes32(0)) revert InvalidRoot();
+        if (bytes(dataURI).length == 0) revert EmptyDataURI();
+        currentMerkleRoot = root;
+        currentDataURI = dataURI;
+        emit RiskRootCommitted(root, dataURI, msg.sender);
+    }
+
+    /**
+     * @notice Verifies if a specific risk record exists in the current Merkle tree.
+     *         Contracts requiring composability must pass the proof.
+     */
+    function verifyRiskRecord(
+        address target,
+        bytes32 actionHash,
+        uint8 score,
+        RiskLevel level,
+        Recommendation recommendation,
+        bytes32 policyVersionHash,
+        bytes32 evidenceHash,
+        uint64 expiresAt,
+        bytes32[] calldata proof
+    ) public view returns (bool) {
+        // expiresAt == 0 means never expires. Non-zero values must be in the future.
+        if (expiresAt != 0 && expiresAt < block.timestamp) revert Expired();
+
+        // Double hashing to prevent leaf-node preimage attacks (standard practice)
+        bytes32 leaf = keccak256(
+            bytes.concat(
+                keccak256(
+                    abi.encode(
+                        target,
+                        actionHash,
+                        score,
+                        level,
+                        recommendation,
+                        policyVersionHash,
+                        evidenceHash,
+                        expiresAt
+                    )
+                )
+            )
+        );
+        return MerkleProof.verify(proof, currentMerkleRoot, leaf);
+    }
+}

package/dist/agent/SafeHandsGuardianAgent.d.ts

@@ -0,0 +1,39 @@
+import type { ReadOnlyChainAccess } from "../lib/analysis/index.js";
+import { type AgentRequest, type IntentResult } from "./agentIntentClassifier.js";
+import { type GuardianPolicy, type PolicyOwner } from "./agentPolicyResolver.js";
+import { type AgentDecision } from "./agentDecisionFormatter.js";
+import { type CallerObligation } from "./agentRuntime.js";
+export interface GuardianAgentOptions {
+    /** Policy overrides merged onto the owner baseline. */
+    policy?: Partial<GuardianPolicy>;
+    /** Policy owner (backend = public default). */
+    owner?: PolicyOwner;
+    /** Applied policy preset name — surfaced in the decision; never weakens. */
+    policyPreset?: string;
+    /** Optional read-only chain access (getCode/estimateGas/...). Omitted offline. */
+    access?: ReadOnlyChainAccess;
+}
+export interface AgentToAgentDecision extends AgentDecision {
+    caller: {
+        id: string;
+        obligation: CallerObligation;
+        responsibility: string;
+    };
+}
+export declare class SafeHandsGuardianAgent {
+    private readonly policy;
+    private readonly access?;
+    private readonly owner;
+    private readonly policyPreset?;
+    constructor(opts?: GuardianAgentOptions);
+    getPolicy(): GuardianPolicy;
+    /** Classify only (no routing) — useful for diagnostics and tests. */
+    classify(req: AgentRequest): IntentResult;
+    /** Full read-only SafeHands check: classify → route → policy → format. */
+    check(req: AgentRequest): Promise<AgentDecision>;
+    /** Agent-to-Agent entry: returns the verdict plus the caller's obligation. */
+    checkForAgent(callerId: string, req: AgentRequest): Promise<AgentToAgentDecision>;
+}
+/** Convenience factory. */
+export declare function createGuardianAgent(opts?: GuardianAgentOptions): SafeHandsGuardianAgent;
+//# sourceMappingURL=SafeHandsGuardianAgent.d.ts.map

package/dist/agent/SafeHandsGuardianAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SafeHandsGuardianAgent.d.ts","sourceRoot":"","sources":["../../src/agent/SafeHandsGuardianAgent.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAkB,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAClG,OAAO,EAA8B,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE7G,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjF,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAKzE,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACjC,+CAA+C;IAC/C,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,gBAAgB,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9E;AAED,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;gBAE3B,IAAI,GAAE,oBAAyB;IAO3C,SAAS,IAAI,cAAc;IAI3B,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY;IAIzC,0EAA0E;IACpE,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAgDtD,8EAA8E;IACxE,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAMxF;AAED,2BAA2B;AAC3B,wBAAgB,mBAAmB,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG,sBAAsB,CAEvF"}

package/dist/agent/SafeHandsGuardianAgent.js

@@ -0,0 +1,98 @@
+// ─── SafeHands Agent (read-only) ──────────────────────────────
+// The complete pre-execution SafeHands Agent. It ORCHESTRATES existing
+// capabilities — Phase 1 decision contract, Phase 2 analyzers, Phase 3 read-only
+// handlers — and adds intent classification, policy enforcement, decision
+// formatting, and the Agent-to-Agent obligation contract.
+//
+// It holds NO private keys, NO wallet, NO signer. There is no code path to sign,
+// send, approve, swap, create/load a wallet, or publish. Read-only by
+// construction; execution is disabled by default.
+// ────────────────────────────────────────────────────────────────────────
+import { isExecutionAvailable } from "../lib/config.js";
+import { classifyIntent } from "./agentIntentClassifier.js";
+import { resolvePolicy, applyPolicy } from "./agentPolicyResolver.js";
+import { routeIntent } from "./agentToolRouter.js";
+import { formatDecision } from "./agentDecisionFormatter.js";
+import { obligationFor } from "./agentRuntime.js";
+import { enrich } from "./agentEnrich.js";
+import { isDenylistedRecipient } from "../lib/recipientSafety.js";
+import { POLICY_VERSION } from "../lib/policy/policyPresets.js";
+export class SafeHandsGuardianAgent {
+    policy;
+    access;
+    owner;
+    policyPreset;
+    constructor(opts = {}) {
+        this.owner = opts.owner ?? "backend";
+        this.policy = resolvePolicy(this.owner, opts.policy);
+        this.access = opts.access;
+        this.policyPreset = opts.policyPreset;
+    }
+    getPolicy() {
+        return this.policy;
+    }
+    /** Classify only (no routing) — useful for diagnostics and tests. */
+    classify(req) {
+        return classifyIntent(req);
+    }
+    /** Full read-only SafeHands check: classify → route → policy → format. */
+    async check(req) {
+        const { intent } = classifyIntent(req);
+        try {
+            const routed = await routeIntent(intent, req, { access: this.access, policy: this.policy });
+            const enrichment = await enrich(req);
+            const policyOutcome = applyPolicy({
+                base: routed.decision,
+                intent,
+                req,
+                policy: this.policy,
+                analyzerDetails: routed.primaryDetails,
+            });
+            const decision = formatDecision({ intent, req, routed, policyOutcome, executionAvailable: isExecutionAvailable(), policyPreset: this.policyPreset, enrichment });
+            // Recipient denylist — escalate-only hard block (only tightens, never weakens).
+            if (decision.decision !== "BLOCK" && isDenylistedRecipient(req.to)) {
+                return {
+                    ...decision,
+                    decision: "BLOCK",
+                    riskLevel: "CRITICAL",
+                    summary: `SafeHands → BLOCK: recipient ${req.to} is on the operator denylist (known-bad address).`,
+                    reasons: ["Recipient is on the operator denylist (known-bad address).", ...decision.reasons],
+                    recommendedAction: "Do not send to this address; it is flagged as known-bad by the operator.",
+                    callerObligation: obligationFor("BLOCK").obligation,
+                };
+            }
+            return decision;
+        }
+        catch (err) {
+            // Fail safe — invalid/un-analyzable input never yields a silent ALLOW.
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                intent,
+                decision: "REQUIRE_CONFIRMATION",
+                riskLevel: "UNKNOWN",
+                summary: `SafeHands → REQUIRE_CONFIRMATION for ${intent.replace(/_/g, " ")}. Input could not be analyzed.`,
+                reasons: [`Input could not be analyzed (validation/decoding failed): ${message}`],
+                recommendedAction: "Obtain explicit user/admin confirmation before any execution.",
+                evidence: { error: message },
+                readOnly: true,
+                executionAvailable: isExecutionAvailable(),
+                nextStep: "Pause and request explicit confirmation; correct the malformed input.",
+                callerObligation: obligationFor("REQUIRE_CONFIRMATION").obligation,
+                tool: "validation",
+                policyPreset: this.policyPreset ?? null,
+                policyVersion: POLICY_VERSION,
+            };
+        }
+    }
+    /** Agent-to-Agent entry: returns the verdict plus the caller's obligation. */
+    async checkForAgent(callerId, req) {
+        const result = await this.check(req);
+        const spec = obligationFor(result.decision);
+        return { ...result, caller: { id: callerId, obligation: spec.obligation, responsibility: spec.responsibility } };
+    }
+}
+/** Convenience factory. */
+export function createGuardianAgent(opts) {
+    return new SafeHandsGuardianAgent(opts);
+}
+//# sourceMappingURL=SafeHandsGuardianAgent.js.map

package/dist/agent/SafeHandsGuardianAgent.js.map

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