Feat/tx captain

.gitignore

@@ -59,6 +59,10 @@ debug-formatter.html
 # Submodule / nested repos
 edb
 
+# Repo uses npm; prevent accidental pnpm installs at the root from being committed
+# (confuses Vercel's package-manager auto-detection)
+/pnpm-lock.yaml
+
 # Misc
 *.pdf
 *test*

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "edb"]
+	path = edb
+	url = git@github.com:Timidan/edb-extended.git
+	branch = toolkit

README.md

@@ -66,6 +66,47 @@ A full simulation analysis page with six tabs:
 
 Browse past simulations stored in IndexedDB. Re-open any previous result for review or further debugging.
 
+### Transaction Analysis (Tx-Captain)
+
+A forensics sub-tool that turns a completed simulation into a verifiable, evidence-backed verdict. Two entry points:
+
+- Click **Summarize** in the simulation results header (next to Share/Export).
+- Open `/builder?mode=analysis` directly — the panel attaches to whichever simulation is currently pinned in the SimulationContext.
+
+What it does:
+
+- **Evidence extraction** -- Walks the V3 trace and emits a structured evidence packet (calls, storage reads/writes, events, transfers, path contracts).
+- **Heuristic sieve** -- Flags patterns that routinely ship bugs: `revert_on_path`, `sload_after_sstore` (state contradicting writes), `zero_address_transfer`, `large_delta` (transfers at/over 10 ETH), and `accumulator` (three or more writes to the same contract slot).
+- **LLM verdict** -- Sends the sanitized packet to the configured LLM (Gemini / Anthropic / OpenAI / custom, per the LLM config panel) and parses the response against a Zod schema: verdict, confidence, core contradiction, causal chain, gates, risk upper bound, missing evidence.
+- **Deep Dive (optional)** -- When enabled, fetches verified Solidity source for each path contract (Sourcify / Etherscan / Blockscout) and falls back to Heimdall decompilation on unverified addresses. Sources are stripped of SPDX/pragma/import lines and vendored libraries (`@openzeppelin/…`, `@chainlink/…`, `node_modules/…`) before being sent to the LLM.
+
+Privacy and export guarantees:
+
+- Analyses are stored in a dedicated IndexedDB store (`web3-toolkit-tx-analysis`) separate from simulation history and are never uploaded.
+- Sensitive keys (`rpcUrl`, `apiKey`, `privateKey`, `secret`, …) are stripped recursively before persistence.
+- Prompts are SHA-256 hashed alongside the verdict so you can audit exactly what was sent.
+- Each verdict can be exported as Markdown or JSON from the panel toolbar.
+
+#### Encrypted Triage (Fhenix Wave 3)
+
+Alongside the classical LLM path, Tx-Captain ships an **encrypted triage** path built on Fhenix CoFHE. The browser encrypts a 12-bit feature vector derived from the EvidencePacket and submits it to a live fhEVM classifier on Ethereum Sepolia. The contract classifies the vector under FHE, storing encrypted `(classBits, severity)` handles that only the submitter can decrypt via `decryptForView` + self-issued permit. A second contract — `RiskThrottle` — consumes the encrypted severity via `FHE.select` and updates per-user throttle status without any party decrypting on-chain.
+
+Live deployments (Ethereum Sepolia, chainId 11155111):
+
+| Contract | Address | Etherscan |
+|---|---|---|
+| `HackTriage` | `0xBe02be322c7733759ee068067BD620791e9e73D4` | [verified](https://sepolia.etherscan.io/address/0xBe02be322c7733759ee068067BD620791e9e73D4#code) |
+| `RiskThrottle` | `0x1FbB01D8e3FE4E99D6742eeBf1A4e276050ecD05` | [verified](https://sepolia.etherscan.io/address/0x1FbB01D8e3FE4E99D6742eeBf1A4e276050ecD05#code) |
+
+Reproduction:
+
+1. Set `VITE_HACK_TRIAGE_ADDRESS` in `.env` (defaults to the live address above).
+2. Connect a Sepolia-funded wallet via RainbowKit, run a simulation, and open the Analysis panel.
+3. Flip the **Cleartext / Encrypted** toggle in `TxAnalysisPanel` to Encrypted, then click **Run Encrypted Triage**.
+4. The hook walks `encrypting → writing → waiting-fhe → decrypting → ready`, revealing class labels and severity locally without ever decrypting on-chain.
+
+Architecture, threat model, leakage table, and open questions live in [docs/superpowers/plans/fhenix-wave3-architecture.md](docs/superpowers/plans/fhenix-wave3-architecture.md). Solidity sources are in [fhe/contracts/](fhe/contracts/); client helpers in [src/utils/hack-analysis/triage/](src/utils/hack-analysis/triage/) and [src/components/tx-analysis/useHackTriage.ts](src/components/tx-analysis/useHackTriage.ts).
+
 ### Integrations
 
 The `/integrations` route hosts protocol-specific modules that extend HexKit beyond debugging into active DeFi operations.
@@ -175,6 +216,31 @@ For the LI.FI Earn integration and AI concierge, set the following in `.env`:
 | `GEMINI_FALLBACK_MODEL` | Fallback on 429/503 (default: `gemini-2.5-flash`) |
 | `PROXY_SECRET` | Shared secret for API proxy authentication (production) |
 | `ALLOWED_ORIGINS` | Comma-separated allowed CORS origins (production) |
+| `VITE_HACK_TRIAGE_ADDRESS` | Ethereum Sepolia `HackTriage` contract (default: `0xBe02...73D4`) |
+
+### Heimdall endpoints (bridge)
+
+The bridge exposes three POST endpoints that shell out to the [heimdall-rs](https://github.com/Jon-Becker/heimdall-rs) CLI:
+
+- `POST /heimdall/version` → `{ available: boolean, version?: string }`
+- `POST /heimdall/decompile` → `{ source, abi, bytecodeHash, ... }`
+ - Body: `{ bytecode: "0x..." }` **or** `{ address, chainId }`
+- `POST /heimdall/dump` → `{ slots: [...], address, chainId, blockNumber, ... }`
+ - Body: `{ address, chainId, blockNumber? | blockTag? }`
+
+**Security:** Clients must not send `rpcUrl` — the bridge resolves it per-chain from a server-side allowlist (default: mainnet / optimism / base / arbitrum) and rejects any request that carries `rpcUrl` with HTTP 400. Override the allowlist with `HEIMDALL_RPC_BY_CHAIN` (see `.env.example`). The bridge also computes `bytecodeHash` itself from `eth_getCode` — the client never supplies it — to prevent cache-key poisoning.
+
+Results are cached in-memory on the bridge (LRU + TTL). To install the binary: run `bash edb/scripts/install.sh` — it pulls heimdall via bifrost automatically unless `INSTALL_HEIMDALL=0`. Front end consumers use [`src/utils/heimdall/hooks.ts`](src/utils/heimdall/hooks.ts).
+
+#### Unverified contract support (heuristic tier)
+
+When Sourcify has no source for a contract, the Storage Layout Viewer falls back to Heimdall decompilation if the bridge has it installed. Results are shown with an amber **Heuristic** badge and a banner explaining the caveats:
+
+- Slot labels derived from decompiled function signatures (ERC20-like, Ownable, Pausable) and Heimdall's `modifiers` hint per slot.
+- Struct packing is **not** resolved — every populated slot is shown as a single 32-byte value.
+- Mapping keys must be discovered manually (use the existing mapping probe).
+
+To enable: install Heimdall on the bridge (see install step above). To disable globally, set `HEIMDALL_BIN_PATH` to a path that does not exist — the availability check will fall back to "unavailable" and the heuristic tier is skipped.
 
 ## Project Structure
 
@@ -229,7 +295,8 @@ src/
  lib/ Shared libraries
 
 api/
- llm-recommend.ts Gemini LLM proxy with model fallback
+ llm-invoke.ts Provider-agnostic LLM proxy (allowlist-enforced BYOK transport)
+ llm-recommend.ts Gemini LLM proxy with model fallback (legacy; kept for rollback)
  lifi-composer.ts LI.FI Composer quote/execute proxy
  edb/ EDB simulation API routes
 

api/_llm/allowlist.ts

@@ -0,0 +1,42 @@
+import type { LlmProvider } from "../../src/utils/llm/types";
+
+const BASE_URLS: Record<Exclude<LlmProvider, "custom">, string> = {
+ anthropic: (process.env.ANTHROPIC_BASE_URL ?? "https://api.anthropic.com").replace(/\/$/, ""),
+ openai: (process.env.OPENAI_BASE_URL ?? "https://api.openai.com").replace(/\/$/, ""),
+ gemini: (process.env.GEMINI_BASE_URL ?? "https://generativelanguage.googleapis.com").replace(/\/$/, ""),
+};
+
+const ALLOWED_PATHS: Record<Exclude<LlmProvider, "custom">, RegExp[]> = {
+ anthropic: [/^\/v1\/messages$/],
+ openai: [/^\/v1\/chat\/completions$/, /^\/v1\/responses$/],
+ gemini: [
+ /^\/v1beta\/models\/[A-Za-z0-9._-]+:generateContent$/,
+ /^\/v1beta\/models\/[A-Za-z0-9._-]+:streamGenerateContent(\?alt=sse)?$/,
+ ],
+};
+
+export function isAllowedProviderUrl(
+ provider: LlmProvider,
+ path: string,
+): boolean {
+ if (provider === "custom") return false;
+ if (!(provider in BASE_URLS)) return false;
+ if (path.startsWith("http://") || path.startsWith("https://")) return false;
+ if (path.includes("..")) return false;
+ const rules = ALLOWED_PATHS[provider];
+ return rules.some((rx) => rx.test(path));
+}
+
+export function resolveProviderUrl(
+ provider: LlmProvider,
+ path: string,
+): string {
+ if (!isAllowedProviderUrl(provider, path)) {
+ throw new Error(`Provider URL not allowed: ${provider}${path}`);
+ }
+ return `${BASE_URLS[provider as Exclude<LlmProvider, "custom">]}${path}`;
+}
+
+export function listAllowedProviders(): LlmProvider[] {
+ return Object.keys(BASE_URLS) as LlmProvider[];
+}

api/_llm/guardHeaders.ts

@@ -0,0 +1,71 @@
+import * as crypto from "crypto";
+
+export interface GuardConfig {
+ allowedOrigins: string[];
+ proxySecret: string | undefined;
+}
+
+export interface GuardResult {
+ ok: boolean;
+ status?: number;
+ reason?: string;
+}
+
+function timingSafeEqualStr(a: string, b: string): boolean {
+ const ab = Buffer.from(a);
+ const bb = Buffer.from(b);
+ if (ab.length !== bb.length) return false;
+ return crypto.timingSafeEqual(ab, bb);
+}
+
+function isSameOriginOrLocalhost(origin: string, host: string | undefined): boolean {
+ if (origin.startsWith("http://localhost:") || origin === "http://localhost") return true;
+ if (origin.startsWith("http://127.0.0.1:") || origin === "http://127.0.0.1") return true;
+ if (!host) return false;
+ return origin === `https://${host}` || origin === `http://${host}`;
+}
+
+/**
+ * Fail-closed request guard. Allow order:
+ * 1. If proxySecret configured, require x-proxy-secret match (timing-safe).
+ * 2. Else if Origin absent, allow (same-origin server call / curl).
+ * 3. Else allow when origin is in allowedOrigins, is localhost/127.0.0.1,
+ * or equals same-host (http(s)://${host}).
+ * 4. Anything else: reject 403. Empty allowedOrigins + external Origin
+ * does NOT open the proxy — previously this was a fail-open bug.
+ */
+export function checkRequestGuards(
+ req: { headers: Record<string, string | string[] | undefined> },
+ cfg: GuardConfig,
+): GuardResult {
+ const h = (name: string): string | undefined => {
+ const v = req.headers[name.toLowerCase()];
+ return Array.isArray(v) ? v[0] : v;
+ };
+
+ if (cfg.proxySecret) {
+ const sent = h("x-proxy-secret") ?? "";
+ return timingSafeEqualStr(sent, cfg.proxySecret)
+ ? { ok: true }
+ : { ok: false, status: 403, reason: "bad_proxy_secret" };
+ }
+
+ const origin = h("origin");
+ const host = h("host");
+
+ if (!origin) return { ok: true };
+
+ if (cfg.allowedOrigins.includes(origin)) return { ok: true };
+ if (isSameOriginOrLocalhost(origin, host)) return { ok: true };
+
+ return { ok: false, status: 403, reason: "origin_not_allowed" };
+}
+
+export function readGuardConfigFromEnv(): GuardConfig {
+ const allowedOrigins = (process.env.ALLOWED_ORIGINS ?? "")
+ .split(",")
+ .map((s) => s.trim())
+ .filter(Boolean);
+ const proxySecret = process.env.PROXY_SECRET || undefined;
+ return { allowedOrigins, proxySecret };
+}

api/edb/[...path].ts → api/edb-proxy.ts

@@ -1,5 +1,5 @@
 import type { VercelRequest, VercelResponse } from "@vercel/node";
-import { maybeInjectDefaultEtherscanKey } from "../edbShared.js";
+import { maybeInjectDefaultEtherscanKey } from "./edbShared.js";
 
 export const config = {
  api: { bodyParser: false },
@@ -104,9 +104,17 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
  return res.status(405).json({ error: "method_not_allowed" });
  }
 
- // Extract sub-path from URL — more reliable than req.query.path across Vercel runtimes
- const urlPath = (req.url || "").split("?")[0];
- const subPath = urlPath.replace(/^\/api\/edb\/?/, "");
+ // Extract sub-path from the `path` query param populated by the Vercel
+ // rewrite rule in vercel.json. Vercel's file-based catch-all routing
+ // (`api/edb/[...path].ts`) does not reliably match multi-segment requests
+ // under `/api/edb/*` on this project, so we route via an explicit rewrite
+ // that mirrors the lifi-composer pattern.
+ const pathParam = req.query?.path;
+ const subPath = Array.isArray(pathParam)
+ ? pathParam.join("/")
+ : typeof pathParam === "string"
+ ? pathParam
+ : "";
 
  // Validate each path segment
  const parts = subPath ? subPath.split("/") : [];