chore: consolidate and harden

.env.example

@@ -1,30 +1,68 @@
-# TorPC Configuration Example
+# ToRPC Configuration Example
+# Copy this file to `.env` and configure as needed. Every variable below
+# is read by the daemon at startup; values that don't parse log a warning
+# and fall back to the documented default rather than silently using zero.
 
-# Geth Connection
-GETH_URL=http://127.0.0.1:8545
+# ----- Core Services --------------------------------------------------------
 
-# Flashbots Configuration (optional)
-FLASHBOTS_URL=https://relay.flashbots.net
-FLASHBOTS_SIGNING_KEY=your_private_key_here
-FLASHBOTS_RELAY_URL=https://relay.flashbots.net
+# Upstream Ethereum node JSON-RPC endpoint.
+GETH_URL=http://127.0.0.1:8545
 
-# Server Settings
+# Bind address for the proxy's HTTP listener (the .onion service forwards here).
 BIND_ADDR=127.0.0.1:8080
+
+# tracing-subscriber filter. Examples: `info`, `debug`, `torpc=trace,hyper=info`.
 RUST_LOG=info
 
-# Security Configuration
-# Maximum request body size in bytes (default: 512KB)
-MAX_REQUEST_SIZE=524288
+# ----- MEV Protection (optional) -------------------------------------------
+
+# Hex private key used ONLY to sign X-Flashbots-Signature headers. Any
+# Ethereum key works; it never holds funds. 64 hex chars, no `0x` prefix.
+# Leave unset to disable MEV protection — the proxy will then return a
+# JSON-RPC error -32004 for `eth_sendBundle` instead of silently faking
+# a response.
+# FLASHBOTS_SIGNING_KEY=1111111111111111111111111111111111111111111111111111111111111111
+
+# MEV relay endpoint. Defaults to mainnet if FLASHBOTS_SIGNING_KEY is set.
+# Mainnet:  https://relay.flashbots.net
+# Sepolia:  https://relay-sepolia.flashbots.net
+# Holesky:  https://relay-holesky.flashbots.net
+# FLASHBOTS_RELAY_URL=https://relay.flashbots.net
+
+# Backwards-compatible alias for FLASHBOTS_RELAY_URL. Prefer the latter.
+# FLASHBOTS_URL=https://relay.flashbots.net
+
+# ----- Security -------------------------------------------------------------
 
-# Request timeout in seconds (default: 30)
+# Maximum request body size in bytes. Default 1 MiB.
+# `MAX_BODY_SIZE` is also accepted as a legacy alias.
+MAX_REQUEST_SIZE=1048576
+
+# Per-request timeout in seconds. Default 30.
 REQUEST_TIMEOUT=30
 
-# Enable strict security headers (disables CORS) (default: false)
-STRICT_SECURITY_HEADERS=false
+# When `true`, applies stricter security headers (no CORS). Default `true`.
+# `STRICT_HEADERS` is also accepted as a legacy alias.
+STRICT_SECURITY_HEADERS=true
+
+# ----- Rate Limiting --------------------------------------------------------
 
-# Rate Limiting
+# Requests allowed per (IP, source-port) bucket per window. Default 100.
 RATE_LIMIT_REQUESTS=100
+
+# Window duration in seconds. Default 60.
 RATE_LIMIT_WINDOW=60
 
-# Tor Settings (if using SOCKS proxy)
-TOR_SOCKS_PROXY=127.0.0.1:9050
+# Max concurrent in-flight requests across the entire router. Default 256.
+MAX_CONCURRENT_CONNECTIONS=256
+
+# ----- Discovery (client-side proxy only) -----------------------------------
+
+# Enable the optional discovery server that wallet GUIs use to detect a
+# running proxy. OFF by default — when on, the server is bound to
+# 127.0.0.1 and gated by a per-launch random token written to
+# ${XDG_RUNTIME_DIR:-/tmp}/torpc-discovery.token (mode 0600).
+# TORPC_DISCOVERY_ENABLE=true
+
+# Port for the discovery server when enabled. Default 8081.
+# TORPC_DISCOVERY_PORT=8081

.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+  CARGO_INCREMENTAL: 0
+  # Service-required tests are gated behind `#[ignore]` and run via
+  # `make test-with-services` only. Keep CI service-free by NOT passing
+  # --include-ignored anywhere in this workflow.
+  RUST_BACKTRACE: 1
+
+jobs:
+  fmt:
+    name: rustfmt
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - name: cargo fmt --check (root)
+        run: cargo fmt --check
+      - name: cargo fmt --check (torpc-proxy workspace)
+        run: cargo fmt --check --manifest-path torpc-proxy/Cargo.toml --all
+
+  clippy:
+    name: clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: clippy (root)
+        run: cargo clippy --all-targets -- -D warnings
+      - name: clippy (torpc-proxy workspace)
+        run: cargo clippy --manifest-path torpc-proxy/Cargo.toml --workspace --all-targets -- -D warnings
+
+  test:
+    name: test (no services)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: build
+        run: cargo build --workspace
+      - name: build torpc-proxy workspace
+        run: cargo build --manifest-path torpc-proxy/Cargo.toml --workspace
+      - name: fast tests
+        run: make test
+      - name: torpc-proxy workspace tests
+        run: cargo test --manifest-path torpc-proxy/Cargo.toml --workspace

.gitignore

@@ -1,19 +1,26 @@
-# Logs
+# ----- Logs --------------------------------------------------------------
 logs
 *.log
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 dev-debug.log
+
+# Personal task tracking — kept out of source control so the repo can be
+# cloned without leaking the original author's planning artifacts.
 prd.txt
 
-# Dependency directories
+# Per-developer Claude Code project instructions. Each contributor keeps
+# their own; not part of the source-controlled state.
+CLAUDE.md
+
+# ----- Dependency directories -------------------------------------------
 node_modules/
 
-# Environment variables
+# ----- Environment ------------------------------------------------------
 .env
 
-# Editor directories and files
+# ----- Editor / OS ------------------------------------------------------
 .idea
 .vscode
 *.suo
@@ -22,29 +29,31 @@ node_modules/
 *.sln
 *.sw?
 .taskmaster
-cache/
-
-# OS specific
 .DS_Store
 
-# Added by cargo
+# ----- Cargo / Rust ----------------------------------------------------
+# `Cargo.lock` is INTENTIONALLY tracked: torpc is a binary crate and
+# operators rely on reproducible builds. Per Cargo's own docs, libraries
+# may ignore `Cargo.lock` but binaries should commit it.
 /target
-Cargo.lock
-
-# Rust specific
 **/*.rs.bk
 *.pdb
 
-# Data directories
+# ----- Build / test output ---------------------------------------------
+cache/
+compiled/
+dev/cache/
+dev/out/
+output/contribute/
+tarpaulin-report.html
+cobertura.xml
+
+# ----- Runtime data ----------------------------------------------------
 /data/
 !/data/.gitkeep
 
-# Tor specific
+# ----- Tor specific ----------------------------------------------------
+# `configs/torrc` IS tracked so a fresh clone can run; only local overrides
+# are ignored. Generated `.onion` hostnames must never be committed.
 *.onion
 /configs/torrc.local
-/configs/
-/output/
-
-# Test artifacts
-tarpaulin-report.html
-cobertura.xml