safehands-pharos 1.5.0 → 2.8.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/analysis/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAC9E,2EAA2E;AAE3E,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC"}

package/dist/lib/analysis/pharosTokens.d.ts

@@ -0,0 +1,31 @@
+import { type NetworkName, type PharosNetwork } from "../networks.js";
+import type { EvidenceSource, EvidenceStatus } from "./types.js";
+export interface TokenRegistryEvidence {
+    symbol: string | null;
+    name: string | null;
+    network: NetworkName;
+    chainId: number;
+    address: string | null;
+    decimals: number | null;
+    source: EvidenceSource;
+    status: EvidenceStatus;
+    riskRelevance: string;
+}
+interface ResolvedToken {
+    symbol: string;
+    name: string | null;
+    address: string;
+    decimals: number | null;
+    source: EvidenceSource;
+}
+/** Resolve a token (symbol or address) within a network's official registry. */
+export declare function lookupPharosToken(input: string, network: NetworkName): ResolvedToken | undefined;
+/**
+ * Build read-only token-registry evidence for a token on a network.
+ *  - recognized official token → status `implemented`
+ *  - valid but unknown address  → status `to_verify` (never silently trusted)
+ *  - invalid / unknown symbol   → `null`
+ */
+export declare function tokenRegistryEvidence(input: string, network?: PharosNetwork): TokenRegistryEvidence | null;
+export {};
+//# sourceMappingURL=pharosTokens.d.ts.map

package/dist/lib/analysis/pharosTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pharosTokens.d.ts","sourceRoot":"","sources":["../../../src/lib/analysis/pharosTokens.ts"],"names":[],"mappings":"AAUA,OAAO,EAAoB,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAExF,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACvB;AAKD,UAAU,aAAa;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,aAAa,GAAG,SAAS,CA2BhG;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkC,GAAG,qBAAqB,GAAG,IAAI,CA8B9H"}

package/dist/lib/analysis/pharosTokens.js

@@ -0,0 +1,78 @@
+// ─── Network-aware Pharos Token Registry (read-only) ───────────────────
+// Single source of truth for token-registry *evidence*. Pacific Mainnet uses the
+// official Pharos token list (constants.PACIFIC_MAINNET_TOKEN_REGISTRY); Atlantic
+// Testnet delegates to the existing testnet classifier (unchanged). Recognition is
+// by registry address only — it is NOT a safety guarantee for an action. Pure: no
+// RPC, no keys, no writes.
+// ────────────────────────────────────────────────────────────────────────
+import { getAddress, isAddress } from "viem";
+import { PACIFIC_MAINNET_TOKEN_REGISTRY } from "../constants.js";
+import { getActiveNetwork } from "../networks.js";
+import { classifyTokenRegistryStatus } from "../../tools/tokenRegistryStatus.js";
+const RISK_RELEVANCE = "Recognized via the network token registry by address; recognition is metadata, not a safety guarantee; a known token does not make a risky action safe.";
+/** Resolve a token (symbol or address) within a network's official registry. */
+export function lookupPharosToken(input, network) {
+    const raw = (input ?? "").trim();
+    if (!raw)
+        return undefined;
+    if (network === "pacific-mainnet") {
+        const upper = raw.toUpperCase();
+        const entries = Object.values(PACIFIC_MAINNET_TOKEN_REGISTRY);
+        const bySymbol = entries.find((t) => t.symbol === upper);
+        if (bySymbol) {
+            return { symbol: bySymbol.symbol, name: bySymbol.name, address: bySymbol.address, decimals: bySymbol.decimals, source: "official_docs" };
+        }
+        if (isAddress(raw)) {
+            const lower = raw.toLowerCase();
+            const byAddr = entries.find((t) => t.address.toLowerCase() === lower);
+            if (byAddr) {
+                return { symbol: byAddr.symbol, name: byAddr.name, address: byAddr.address, decimals: byAddr.decimals, source: "official_docs" };
+            }
+        }
+        return undefined;
+    }
+    // Atlantic Testnet — delegate to the existing classifier (behavior preserved).
+    const cls = classifyTokenRegistryStatus(raw);
+    if (cls.symbol && cls.normalizedAddress && (cls.status === "CANONICAL_MAINNET_TOKEN" || cls.status === "SKILL_ENGINE_CANONICAL_TOKEN")) {
+        return { symbol: cls.symbol, name: null, address: cls.normalizedAddress, decimals: null, source: "existing_registry" };
+    }
+    return undefined;
+}
+/**
+ * Build read-only token-registry evidence for a token on a network.
+ *  - recognized official token → status `implemented`
+ *  - valid but unknown address  → status `to_verify` (never silently trusted)
+ *  - invalid / unknown symbol   → `null`
+ */
+export function tokenRegistryEvidence(input, network = getActiveNetwork()) {
+    const raw = (input ?? "").trim();
+    const tok = lookupPharosToken(raw, network.name);
+    if (tok) {
+        return {
+            symbol: tok.symbol,
+            name: tok.name,
+            network: network.name,
+            chainId: network.chainId,
+            address: tok.address,
+            decimals: tok.decimals,
+            source: tok.source,
+            status: "implemented",
+            riskRelevance: RISK_RELEVANCE,
+        };
+    }
+    if (isAddress(raw)) {
+        return {
+            symbol: null,
+            name: null,
+            network: network.name,
+            chainId: network.chainId,
+            address: getAddress(raw),
+            decimals: null,
+            source: "to_verify",
+            status: "to_verify",
+            riskRelevance: "Token is a valid address but not in the official network registry; treat as unverified/custom (TO_VERIFY).",
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=pharosTokens.js.map

package/dist/lib/analysis/pharosTokens.js.map

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

package/dist/lib/analysis/safeTx.d.ts

@@ -0,0 +1,27 @@
+import { type CanonicalContractEvidence } from "./contractIntel.js";
+import { type AnalyzerResult } from "./types.js";
+import type { GuardianDecision } from "../guardian/decision.js";
+export declare const MULTISEND_SELECTOR = "0x8d80ff0a";
+export declare const SAFE_EXEC_SELECTOR = "0x6a761202";
+export interface SafeInnerCall {
+    index: number;
+    operation: number;
+    to: string;
+    value: string;
+    dataLength: number;
+    selector: string | null;
+    decision: GuardianDecision;
+    summary: string;
+    /** Per-network canonical recognition of this inner call's target (null when unknown). */
+    canonicalContractEvidence: CanonicalContractEvidence | null;
+}
+export interface SafeTxAnalysisDetails {
+    kind: "multisend" | "safe_exec" | "unknown";
+    selector: string | null;
+    innerCallCount: number | null;
+    innerCalls: SafeInnerCall[];
+    hasDelegateCall: boolean;
+    fullyDecoded: boolean;
+}
+export declare function analyzeSafeTx(data: string): Promise<AnalyzerResult<SafeTxAnalysisDetails>>;
+//# sourceMappingURL=safeTx.d.ts.map

package/dist/lib/analysis/safeTx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeTx.d.ts","sourceRoot":"","sources":["../../../src/lib/analysis/safeTx.ts"],"names":[],"mappings":"AASA,OAAO,EAA6B,KAAK,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAE/F,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAC/C,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAM/C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,yFAAyF;IACzF,yBAAyB,EAAE,yBAAyB,GAAG,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;IAC5C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,EAAE,OAAO,CAAC;CACvB;AA+BD,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,qBAAqB,CAAC,CAAC,CAiFhG"}

package/dist/lib/analysis/safeTx.js

@@ -0,0 +1,118 @@
+// ─── Safe / MultiSend Analyzer (read-only, Experimental) ───────────────
+// Recognizes Safe transactions and decodes MultiSend batches on a best-effort
+// basis. The highest-risk inner call drives the aggregate decision. Deep decode
+// is Experimental — partial/unparsable input is reported clearly. Never submits
+// a Safe transaction and never co-signs.
+// ────────────────────────────────────────────────────────────────────────
+import { bytesToBigInt, bytesToHex, decodeFunctionData, hexToBytes } from "viem";
+import { analyzeApproval, APPROVE_SELECTOR } from "./approval.js";
+import { canonicalContractEvidence } from "./contractIntel.js";
+import { analyzeEvmCall } from "./evm.js";
+import { makeResult } from "./types.js";
+export const MULTISEND_SELECTOR = "0x8d80ff0a";
+export const SAFE_EXEC_SELECTOR = "0x6a761202"; // execTransaction(...)
+const MULTISEND_ABI = [
+    { name: "multiSend", type: "function", stateMutability: "payable", inputs: [{ name: "transactions", type: "bytes" }], outputs: [] },
+];
+const SEVERITY = { ALLOW: 0, PREPARE_ONLY: 1, REQUIRE_CONFIRMATION: 2, BLOCK: 3 };
+function worst(a, b) {
+    return SEVERITY[a] >= SEVERITY[b] ? a : b;
+}
+function decodeMultiSendBatch(transactions) {
+    const buf = hexToBytes(transactions);
+    const calls = [];
+    let i = 0;
+    while (i < buf.length) {
+        const operation = buf[i];
+        i += 1;
+        const to = bytesToHex(buf.slice(i, i + 20));
+        i += 20;
+        const value = bytesToBigInt(buf.slice(i, i + 32));
+        i += 32;
+        const dataLen = Number(bytesToBigInt(buf.slice(i, i + 32)));
+        i += 32;
+        const data = bytesToHex(buf.slice(i, i + dataLen));
+        i += dataLen;
+        calls.push({ index: calls.length, operation, to, value: value.toString(), dataLength: dataLen, data });
+    }
+    return calls;
+}
+export async function analyzeSafeTx(data) {
+    const reasons = [];
+    const warnings = ["Safe/MultiSend decoding is Experimental; verify the full batch independently before signing."];
+    const hex = (data?.startsWith("0x") ? data : `0x${data ?? ""}`).toLowerCase();
+    const selector = hex.length >= 10 ? hex.slice(0, 10) : null;
+    const partial = (kind, msg) => makeResult({
+        analyzer: "safe_tx",
+        decision: "REQUIRE_CONFIRMATION",
+        internalDecision: "REQUIRE_CONFIRMATION",
+        riskLevel: "UNKNOWN",
+        reasons: [msg],
+        warnings,
+        analyzerStatus: "partial",
+        experimental: true,
+        details: { kind, selector, innerCallCount: null, innerCalls: [], hasDelegateCall: false, fullyDecoded: false },
+    });
+    if (selector === SAFE_EXEC_SELECTOR) {
+        return partial("safe_exec", "Recognized a Safe execTransaction call; nested call decode is not performed (Experimental).");
+    }
+    if (selector !== MULTISEND_SELECTOR) {
+        return partial("unknown", `Not a recognized Safe/MultiSend selector (${selector ?? "n/a"}).`);
+    }
+    let transactions;
+    try {
+        const decoded = decodeFunctionData({ abi: MULTISEND_ABI, data: hex });
+        transactions = decoded.args[0];
+    }
+    catch {
+        return partial("multisend", "MultiSend payload could not be ABI-decoded (Experimental, partial).");
+    }
+    let rawCalls;
+    try {
+        rawCalls = decodeMultiSendBatch(transactions);
+    }
+    catch {
+        return partial("multisend", "MultiSend batch bytes could not be parsed (Experimental, partial).");
+    }
+    let aggregate = "ALLOW";
+    let hasDelegateCall = false;
+    const innerCalls = [];
+    for (const c of rawCalls) {
+        const sel = c.data && c.data.length >= 10 ? c.data.slice(0, 10).toLowerCase() : null;
+        if (c.operation === 1)
+            hasDelegateCall = true;
+        let decision;
+        let summary;
+        if (sel === APPROVE_SELECTOR) {
+            const a = analyzeApproval(c.data, c.to);
+            decision = a.decision;
+            summary = a.reasons[0] ?? "approval";
+        }
+        else {
+            const e = await analyzeEvmCall({ to: c.to, data: c.data, value: c.value });
+            decision = e.decision;
+            summary = e.reasons[0] ?? e.details.callClass;
+        }
+        // A delegatecall in a batch is inherently higher-risk.
+        if (c.operation === 1)
+            decision = worst(decision, "REQUIRE_CONFIRMATION");
+        aggregate = worst(aggregate, decision);
+        innerCalls.push({ index: c.index, operation: c.operation, to: c.to, value: c.value, dataLength: c.dataLength, selector: sel, decision, summary, canonicalContractEvidence: canonicalContractEvidence(c.to) });
+    }
+    if (hasDelegateCall)
+        warnings.push("Batch contains a delegatecall (operation=1); elevated risk.");
+    reasons.push(`Decoded MultiSend batch with ${innerCalls.length} inner call(s); aggregate decision follows the highest-risk inner call.`);
+    const riskLevel = aggregate === "BLOCK" ? "CRITICAL" : aggregate === "REQUIRE_CONFIRMATION" ? "MEDIUM" : "LOW";
+    return makeResult({
+        analyzer: "safe_tx",
+        decision: aggregate,
+        internalDecision: aggregate,
+        riskLevel,
+        reasons,
+        warnings,
+        analyzerStatus: "ok",
+        experimental: true,
+        details: { kind: "multisend", selector, innerCallCount: innerCalls.length, innerCalls, hasDelegateCall, fullyDecoded: true },
+    });
+}
+//# sourceMappingURL=safeTx.js.map

package/dist/lib/analysis/safeTx.js.map

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

package/dist/lib/analysis/token.d.ts

@@ -0,0 +1,21 @@
+import { type TokenRegistryStatusValue } from "../../tools/tokenRegistryStatus.js";
+import { type NetworkName } from "../networks.js";
+import { type TokenRegistryEvidence } from "./pharosTokens.js";
+import { type AnalyzerResult } from "./types.js";
+export interface TokenAnalysisDetails {
+    input: string;
+    resolvedFrom: "symbol" | "address" | "invalid";
+    normalizedAddress: string | null;
+    symbol: string | null;
+    status: TokenRegistryStatusValue;
+    verificationStatus: string;
+    /** Which network's registry produced this verdict. */
+    registryScope: NetworkName;
+    /** True — SafeHands now ships a Pacific Mainnet token registry (Phase 5B). */
+    mainnetRegistryImplemented: boolean;
+    /** Per-network token-registry evidence (null when not a valid token). */
+    tokenRegistryEvidence: TokenRegistryEvidence | null;
+    activeNetwork: string;
+}
+export declare function analyzeToken(token: string): AnalyzerResult<TokenAnalysisDetails>;
+//# sourceMappingURL=token.d.ts.map

package/dist/lib/analysis/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../../src/lib/analysis/token.ts"],"names":[],"mappings":"AASA,OAAO,EAA+B,KAAK,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAChH,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAA4C,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACzG,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7D,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IAC/C,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,wBAAwB,CAAC;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,aAAa,EAAE,WAAW,CAAC;IAC3B,8EAA8E;IAC9E,0BAA0B,EAAE,OAAO,CAAC;IACpC,yEAAyE;IACzE,qBAAqB,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACpD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,oBAAoB,CAAC,CAMhF"}

package/dist/lib/analysis/token.js

@@ -0,0 +1,151 @@
+// ─── Token Analyzer (read-only) ────────────────────────────────────────
+// Maps a token (symbol or address) to a public SafeHands decision, PER-NETWORK.
+// On Pacific Mainnet it uses the official Pharos token registry
+// (constants.PACIFIC_MAINNET_TOKEN_REGISTRY, Phase 5A audit); on Atlantic Testnet
+// it uses the existing testnet classifier (unchanged). Tokens are never trusted
+// by symbol alone, and a known token NEVER makes a risky action safe.
+// ────────────────────────────────────────────────────────────────────────
+import { getAddress, isAddress } from "viem";
+import { classifyTokenRegistryStatus } from "../../tools/tokenRegistryStatus.js";
+import { getActiveNetwork } from "../networks.js";
+import { lookupPharosToken, tokenRegistryEvidence } from "./pharosTokens.js";
+import { makeResult } from "./types.js";
+export function analyzeToken(token) {
+    const raw = (token ?? "").trim();
+    const active = getActiveNetwork();
+    const evidence = tokenRegistryEvidence(raw, active);
+    return active.isMainnet ? analyzePacificToken(raw, active.name, evidence) : analyzeAtlanticToken(raw, active.name, evidence);
+}
+/** Pacific Mainnet: recognize against the official Pharos token registry. */
+function analyzePacificToken(raw, registryScope, evidence) {
+    const reasons = [];
+    const warnings = [];
+    const tok = lookupPharosToken(raw, "pacific-mainnet");
+    let normalizedAddress;
+    let symbol;
+    let status;
+    let verificationStatus;
+    let resolvedFrom;
+    let internalDecision;
+    let riskLevel;
+    if (tok) {
+        normalizedAddress = getAddress(tok.address);
+        symbol = tok.symbol;
+        status = "CANONICAL_MAINNET_TOKEN";
+        verificationStatus = "DOCS_VERIFIED";
+        resolvedFrom = isAddress(raw) ? "address" : "symbol";
+        if (resolvedFrom === "address") {
+            // ALLOW requires an address match against the official registry — the caller
+            // named the exact canonical contract.
+            internalDecision = "ALLOW";
+            riskLevel = "LOW";
+            reasons.push(`Token is a canonical Pharos Pacific Mainnet token (${symbol}).`);
+        }
+        else {
+            // Fail-closed (truth-model rule 1): a known NAME alone never produces ALLOW.
+            // The symbol resolves to the canonical registry address, but the caller did
+            // not identify a contract — confirm the resolved address before acting.
+            internalDecision = "REQUIRE_CONFIRMATION";
+            riskLevel = "MEDIUM";
+            reasons.push(`Symbol "${raw}" resolves to the canonical Pharos Pacific Mainnet token ${symbol} at ${normalizedAddress}, but a symbol alone is not an on-chain guarantee; confirm the resolved address before acting on it.`);
+            warnings.push(`Symbol "${raw}" was resolved to the official Pacific Mainnet registry address ${normalizedAddress}; a symbol alone is not an on-chain guarantee.`);
+        }
+    }
+    else if (isAddress(raw)) {
+        normalizedAddress = getAddress(raw);
+        symbol = null;
+        status = "CUSTOM_NON_REGISTRY";
+        verificationStatus = "UNVERIFIED_CUSTOM_TOKEN";
+        resolvedFrom = "address";
+        internalDecision = "REQUIRE_CONFIRMATION";
+        riskLevel = "MEDIUM";
+        reasons.push("Token is not in the Pacific Mainnet registry; unknown/custom token requires review.");
+    }
+    else {
+        normalizedAddress = null;
+        symbol = null;
+        status = "INVALID_ADDRESS";
+        verificationStatus = "INVALID_ADDRESS";
+        resolvedFrom = "invalid";
+        internalDecision = "BLOCK";
+        riskLevel = "CRITICAL";
+        reasons.push("Token is not a valid EVM address or known Pacific Mainnet symbol.");
+    }
+    return makeResult({
+        analyzer: "token",
+        decision: internalDecision,
+        internalDecision,
+        riskLevel,
+        reasons,
+        warnings,
+        analyzerStatus: "ok",
+        details: { input: raw, resolvedFrom, normalizedAddress, symbol, status, verificationStatus, registryScope, mainnetRegistryImplemented: true, tokenRegistryEvidence: evidence, activeNetwork: registryScope },
+    });
+}
+/** Atlantic Testnet: existing testnet classifier (behavior preserved). */
+function analyzeAtlanticToken(raw, registryScope, evidence) {
+    const cls = classifyTokenRegistryStatus(raw);
+    const reasons = [];
+    const warnings = [];
+    const resolvedFrom = cls.status === "INVALID_ADDRESS" ? "invalid" : isAddress(raw) ? "address" : "symbol";
+    if (resolvedFrom === "symbol" && cls.normalizedAddress) {
+        warnings.push(`Symbol "${raw}" was resolved to the project's testnet registry address ${cls.normalizedAddress}; a symbol alone is not an on-chain guarantee.`);
+    }
+    let internalDecision;
+    let riskLevel;
+    switch (cls.status) {
+        case "INVALID_ADDRESS":
+            internalDecision = "BLOCK";
+            riskLevel = "CRITICAL";
+            reasons.push("Token is not a valid EVM address or known symbol.");
+            break;
+        case "SKILL_ENGINE_CANONICAL_TOKEN":
+        case "CANONICAL_MAINNET_TOKEN":
+            if (resolvedFrom === "symbol") {
+                // Fail-closed (truth-model rule 1): a known NAME alone never produces ALLOW.
+                internalDecision = "REQUIRE_CONFIRMATION";
+                riskLevel = "MEDIUM";
+                reasons.push(`Symbol "${raw}" resolves to the registry token ${cls.symbol ?? "?"} at ${cls.normalizedAddress ?? "?"}, but a symbol alone is not an on-chain guarantee; confirm the resolved address before acting on it.`);
+            }
+            else {
+                internalDecision = "ALLOW";
+                riskLevel = "LOW";
+                reasons.push(`Token is a canonical Atlantic-mainnet token (${cls.symbol ?? "?"}).`);
+            }
+            break;
+        case "ALTERNATE_SOURCE_TOKEN":
+            internalDecision = "REQUIRE_CONFIRMATION";
+            riskLevel = "MEDIUM";
+            reasons.push("Token is an alternate-source token (not the primary registry entry); confirm before use.");
+            break;
+        case "CUSTOM_NON_REGISTRY":
+        case "UNKNOWN":
+        default:
+            internalDecision = "REQUIRE_CONFIRMATION";
+            riskLevel = "MEDIUM";
+            reasons.push("Token is not in the SafeHands registry; unknown/custom token requires review.");
+            break;
+    }
+    return makeResult({
+        analyzer: "token",
+        decision: internalDecision,
+        internalDecision,
+        riskLevel,
+        reasons,
+        warnings,
+        analyzerStatus: "ok",
+        details: {
+            input: raw,
+            resolvedFrom,
+            normalizedAddress: cls.normalizedAddress,
+            symbol: cls.symbol,
+            status: cls.status,
+            verificationStatus: cls.verificationStatus,
+            registryScope,
+            mainnetRegistryImplemented: true,
+            tokenRegistryEvidence: evidence,
+            activeNetwork: registryScope,
+        },
+    });
+}
+//# sourceMappingURL=token.js.map

package/dist/lib/analysis/token.js.map

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

package/dist/lib/analysis/types.d.ts

@@ -0,0 +1,49 @@
+import type { GuardianDecision } from "../guardian/decision.js";
+export type AnalyzerRiskLevel = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL" | "UNKNOWN";
+/** ok = fully analyzed; partial = recognized but not fully decoded; unavailable = could not analyze. */
+export type AnalyzerStatus = "ok" | "partial" | "unavailable";
+/**
+ * Shared provenance/maturity labels for read-only recognition evidence
+ * (canonical contracts, token registry). Recognition is metadata — it is never a
+ * safety guarantee for an action.
+ *   official_docs    — taken from official Pharos docs (Phase 5A audit).
+ *   existing_registry — from the project's existing testnet registry/config.
+ *   to_verify        — a valid target that is NOT in any official registry.
+ */
+export type EvidenceSource = "official_docs" | "existing_registry" | "to_verify";
+/** implemented = backed by code + tests; experimental = partial; to_verify = unconfirmed. */
+export type EvidenceStatus = "implemented" | "experimental" | "to_verify";
+export interface AnalyzerResult<TDetails = Record<string, unknown>> {
+    analyzer: string;
+    /** Public four-value SafeHands decision. */
+    decision: GuardianDecision;
+    /** Internal engine-style label kept for explanation only. */
+    internalDecision?: string;
+    riskLevel: AnalyzerRiskLevel;
+    reasons: string[];
+    warnings: string[];
+    analyzerStatus: AnalyzerStatus;
+    /** True when the analyzer is a partial/demo decoder (e.g. deep Safe/Permit2 decode). */
+    experimental?: boolean;
+    /** Always true — analyzers never write. Lets callers/tests assert read-only. */
+    readOnly: true;
+    details: TDetails;
+}
+/**
+ * Optional read-only chain access. Pass concrete implementations from
+ * pharosClient in tool wiring; omit for offline/pure analysis and smoke tests.
+ * None of these may mutate chain state.
+ */
+export interface ReadOnlyChainAccess {
+    getCode?: (address: `0x${string}`) => Promise<string | undefined>;
+    estimateGas?: (args: {
+        to?: `0x${string}`;
+        data?: `0x${string}`;
+        value?: bigint;
+        account?: `0x${string}`;
+    }) => Promise<bigint>;
+    getGasPrice?: () => Promise<bigint>;
+    getTransactionReceipt?: (hash: `0x${string}`) => Promise<unknown>;
+}
+export declare function makeResult<T>(partial: Omit<AnalyzerResult<T>, "readOnly">): AnalyzerResult<T>;
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/analysis/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/analysis/types.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAEnF,wGAAwG;AACxG,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG,mBAAmB,GAAG,WAAW,CAAC;AACjF,6FAA6F;AAC7F,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,cAAc,GAAG,WAAW,CAAC;AAE1E,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,EAAE,cAAc,CAAC;IAC/B,wFAAwF;IACxF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gFAAgF;IAChF,QAAQ,EAAE,IAAI,CAAC;IACf,OAAO,EAAE,QAAQ,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAClE,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE;QACnB,EAAE,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;QACnB,IAAI,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;KACzB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,qBAAqB,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,MAAM,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAE7F"}

package/dist/lib/analysis/types.js

@@ -0,0 +1,10 @@
+// ─── SafeHands Read-Only Analyzers — Shared Types ──────────────────────
+// Every analyzer is READ-ONLY. No analyzer signs, sends, approves, swaps,
+// publishes, or writes on-chain. Optional chain access is read-only (eth_getCode,
+// eth_estimateGas, eth_getGasPrice, eth_getTransactionReceipt) and is omitted in
+// offline/pure analysis and tests.
+// ────────────────────────────────────────────────────────────────────────
+export function makeResult(partial) {
+    return { readOnly: true, ...partial };
+}
+//# sourceMappingURL=types.js.map

package/dist/lib/analysis/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/analysis/types.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,0EAA0E;AAC1E,kFAAkF;AAClF,iFAAiF;AACjF,mCAAmC;AACnC,2EAA2E;AAuD3E,MAAM,UAAU,UAAU,CAAI,OAA4C;IACxE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AACxC,CAAC"}

package/dist/lib/analysis/x402.d.ts

@@ -0,0 +1,24 @@
+import { type AnalyzerResult } from "./types.js";
+export interface X402AnalysisInput {
+    url: string;
+    paymentAmountUsdc?: string;
+    paymentTokenAddress?: string;
+    payTo?: string;
+    agentId?: string;
+    chainId?: number;
+}
+export interface X402AnalysisDetails {
+    url: string;
+    paymentAmountUsdc: string;
+    maxPaymentUsdc: string;
+    paymentTokenAddress: string;
+    payTo: string | null;
+    payToValid: boolean | null;
+    urlSafe: boolean;
+    amountWithinLimit: boolean;
+    tokenAllowlisted: boolean;
+    mainnetPaymentOnly: true;
+    mainnetPaymentSupported: boolean;
+}
+export declare function analyzeX402(input: X402AnalysisInput): AnalyzerResult<X402AnalysisDetails>;
+//# sourceMappingURL=x402.d.ts.map

package/dist/lib/analysis/x402.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../../../src/lib/analysis/x402.ts"],"names":[],"mappings":"AAaA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,IAAI,CAAC;IACzB,uBAAuB,EAAE,OAAO,CAAC;CAClC;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,iBAAiB,GAAG,cAAc,CAAC,mBAAmB,CAAC,CAkDzF"}

package/dist/lib/analysis/x402.js

@@ -0,0 +1,60 @@
+// ─── x402 Analyzer (read-only) ─────────────────────────────────────────
+// Wraps the existing deterministic x402 policy checks: URL SSRF guard, payment
+// amount vs policy limit, and payment-token allowlist. Pure and offline-safe
+// (static SSRF check, no DNS, no network). Requires NO payment keys.
+//
+// SafeHands supports x402 preflight by default. Actual settlement remains gated
+// behind signer availability, WRITE_TOOLS_ENABLED, policy checks, and authorization.
+// ────────────────────────────────────────────────────────────────────────
+import { isAddress } from "viem";
+import { evaluateActionPolicy } from "../policy/actionPolicyEngine.js";
+import { mapEngineDecision } from "../guardian/decision.js";
+import { MAX_X402_PAYMENT_USDC, X402_PAYMENT_TOKEN_ADDRESS } from "../constants.js";
+import { makeResult } from "./types.js";
+export function analyzeX402(input) {
+    const paymentAmountUsdc = input.paymentAmountUsdc ?? "0.001";
+    const paymentTokenAddress = input.paymentTokenAddress ?? X402_PAYMENT_TOKEN_ADDRESS;
+    const policy = evaluateActionPolicy({
+        actionType: "x402_pay_and_fetch",
+        agentId: input.agentId,
+        url: input.url,
+        paymentAmountUsdc,
+        paymentTokenAddress,
+        chainId: input.chainId,
+    });
+    const urlCheck = policy.checks.find((c) => c.name === "x402_url");
+    const amountCheck = policy.checks.find((c) => c.name === "x402_payment_limit");
+    const tokenCheck = policy.checks.find((c) => c.name === "x402_payment_token");
+    const urlSafe = urlCheck ? urlCheck.status === "pass" : false;
+    const amountWithinLimit = amountCheck ? amountCheck.status === "pass" : true;
+    const tokenAllowlisted = !tokenCheck || tokenCheck.status === "pass";
+    const payToValid = input.payTo !== undefined ? isAddress(input.payTo) : null;
+    const warnings = [...policy.requiredActions];
+    if (payToValid === false)
+        warnings.push("payTo recipient is not a valid EVM address.");
+    // payment keys are never required for analysis; settlement is gated at the tool layer
+    const decision = payToValid === false ? "BLOCK" : mapEngineDecision(policy.decision);
+    return makeResult({
+        analyzer: "x402",
+        decision,
+        internalDecision: policy.decision,
+        riskLevel: policy.riskLevel,
+        reasons: policy.reasons.length ? policy.reasons : [urlSafe ? "x402 request passed static safety checks." : "x402 request failed a safety check."],
+        warnings,
+        analyzerStatus: "ok",
+        details: {
+            url: input.url,
+            paymentAmountUsdc,
+            maxPaymentUsdc: MAX_X402_PAYMENT_USDC,
+            paymentTokenAddress,
+            payTo: input.payTo ?? null,
+            payToValid,
+            urlSafe,
+            amountWithinLimit,
+            tokenAllowlisted,
+            mainnetPaymentOnly: true,
+            mainnetPaymentSupported: true,
+        },
+    });
+}
+//# sourceMappingURL=x402.js.map