docs: refresh AGENTS.md

Author: echobt

AGENTS.md

@@ -12,7 +12,7 @@ This is a **single-crate Rust binary** (`term-executor`) built with Axum. There
 
 ```
 Client → POST /submit (multipart archive) → term-executor
-  1. Authenticate via X-Hotkey header (SS58 hotkey)
+  1. Authenticate via X-Hotkey, X-Nonce, X-Signature, X-Api-Key headers
   2. Extract uploaded archive (zip/tar.gz) containing tasks/ and agent_code/
   3. Parse each task: workspace.yaml, prompt.md, tests/
   4. For each task (concurrently, up to limit):
@@ -33,7 +33,7 @@ Client → POST /submit (multipart archive) → term-executor
 | `src/main.rs` | Entry point — bootstraps config, session manager, executor, Axum server, reaper tasks |
 | `src/config.rs` | `Config` struct loaded from environment variables with defaults; `AUTHORIZED_HOTKEY` constant |
 | `src/handlers.rs` | Axum route handlers: `/health`, `/status`, `/metrics`, `/submit`, `/batch/{id}`, `/batch/{id}/tasks`, `/batch/{id}/task/{task_id}`, `/batches` |
-| `src/auth.rs` | Hotkey authentication: `extract_hotkey()`, `verify_hotkey()`, `validate_ss58()` |
+| `src/auth.rs` | Authentication: `extract_auth_headers()`, `verify_request()`, `validate_ss58()`, sr25519 signature verification via `verify_sr25519_signature()`, `NonceStore` for replay protection, `AuthHeaders`/`AuthError` types |
 | `src/executor.rs` | Core evaluation engine — spawns batch tasks that clone repos, run agents, run tests concurrently |
 | `src/session.rs` | `SessionManager` with `DashMap`, `Batch`, `BatchResult`, `TaskResult`, `BatchStatus`, `TaskStatus`, `WsEvent` types |
 | `src/task.rs` | Archive extraction (zip/tar.gz), task directory parsing, agent code loading, language detection |
@@ -43,7 +43,7 @@ Client → POST /submit (multipart archive) → term-executor
 
 ### Key Shared State (via `Arc`)
 
-- `AppState` (in `handlers.rs`) holds `Config`, `SessionManager`, `Metrics`, `Executor`, `started_at`
+- `AppState` (in `handlers.rs`) holds `Config`, `SessionManager`, `Metrics`, `Executor`, `NonceStore`, `started_at`
 - `SessionManager` uses `DashMap<String, Arc<Batch>>` for lock-free concurrent access
 - Per-batch `Semaphore` in `executor.rs` controls concurrent tasks within a batch (configurable, default: 8)
 - `broadcast::Sender<WsEvent>` per batch for WebSocket event streaming
@@ -59,7 +59,7 @@ Client → POST /submit (multipart archive) → term-executor
 - **Archive Handling**: `flate2` + `tar` (tar.gz), `zip` 2 (zip)
 - **Error Handling**: `anyhow` 1 + `thiserror` 2
 - **Logging**: `tracing` + `tracing-subscriber` with env-filter
-- **Crypto/Identity**: `sha2`, `hex`, `base64`, `bs58` (SS58 address validation), `uuid` v4
+- **Crypto/Identity**: `sha2`, `hex`, `base64`, `bs58` (SS58 address validation), `schnorrkel` 0.11 (sr25519 signature verification), `rand_core` 0.6, `uuid` v4
 - **Time**: `chrono` with serde support
 - **Build Tooling**: `mold` linker via `.cargo/config.toml`, `clang` as linker driver
 - **Container**: Multi-stage Dockerfile — `rust:1.93-slim-bookworm` builder → `debian:bookworm-slim` runtime (includes python3, pip, venv, build-essential, git, curl)
@@ -168,4 +168,4 @@ Both hooks are activated via `git config core.hooksPath .githooks`.
 
 ## Authentication
 
-Authentication uses SS58 hotkey validation via the `X-Hotkey` HTTP header combined with an API key via the `X-Api-Key` header. The authorized hotkey is hardcoded as `AUTHORIZED_HOTKEY` in `src/config.rs`. The API key is configured via the `WORKER_API_KEY` environment variable (required). Only requests with both a matching hotkey and a valid API key can submit batches via `POST /submit`. All other endpoints are open.
+Authentication requires four HTTP headers: `X-Hotkey` (SS58 address), `X-Nonce` (unique per-request), `X-Signature` (sr25519 hex signature of `hotkey + nonce`), and `X-Api-Key`. The authorized hotkey is hardcoded as `AUTHORIZED_HOTKEY` in `src/config.rs`. The API key is configured via the `WORKER_API_KEY` environment variable (required). Verification steps: hotkey must match `AUTHORIZED_HOTKEY`, API key must match, SS58 format must be valid, nonce must not have been seen before (replay protection via `NonceStore` in `src/auth.rs` with 5-minute TTL), and the sr25519 signature must verify against the hotkey's public key using the Substrate signing context. Only requests passing all checks can submit batches via `POST /submit`. All other endpoints are open.

src/AGENTS.md

@@ -7,8 +7,9 @@ This is a single-crate binary. All source files live in `src/` with no sub-modul
 ```
 main.rs
   ├── config.rs      (Config::from_env, AUTHORIZED_HOTKEY)
+  ├── auth.rs        (NonceStore created in main, reaper_loop spawned from main)
   ├── handlers.rs     (Axum router + AppState)
-  │     ├── auth.rs   (hotkey verification for /submit)
+  │     ├── auth.rs   (extract_auth_headers + verify_request for /submit)
   │     ├── executor.rs (spawned from submit handler)
   │     │     ├── task.rs (extract, parse, load tasks)
   │     │     ├── session.rs (BatchResult/TaskResult mutation)
@@ -24,7 +25,7 @@ main.rs
 
 ### `main.rs`
 - Entry point. Initializes tracing, config, session manager, metrics, executor.
-- Creates `AppState`, builds Axum router, spawns background tasks (session reaper, stale dir reaper).
+- Creates `AppState`, builds Axum router, spawns background tasks (session reaper, nonce reaper, stale dir reaper).
 - Binds to `0.0.0.0:{PORT}` with graceful shutdown on CTRL+C.
 - **Convention**: Background tasks are spawned with `tokio::spawn` and run indefinitely.
 
@@ -36,18 +37,22 @@ main.rs
 - **Convention**: Add new config fields here, with a `DEFAULT_*` constant and an env var name. Always provide a sensible default.
 
 ### `handlers.rs`
-- Defines `AppState` struct (`config`, `sessions`, `metrics`, `executor`, `started_at`).
+- Defines `AppState` struct (`config`, `sessions`, `metrics`, `executor`, `nonce_store`, `started_at`).
 - `router()` builds the Axum `Router` with all routes and shared state.
 - Route handlers: `health`, `status`, `metrics`, `submit_batch`, `get_batch`, `get_batch_tasks`, `get_task`, `list_batches`.
 - Routes: `GET /health`, `GET /status`, `GET /metrics`, `POST /submit`, `GET /batch/{id}`, `GET /batch/{id}/tasks`, `GET /batch/{id}/task/{task_id}`, `GET /batches`, `GET /ws`.
-- `submit_batch` handler does: hotkey auth → busy check → multipart upload → archive extraction → batch creation → executor spawn.
+- `submit_batch` handler does: auth header extraction → `verify_request` (hotkey + API key + nonce + signature) → busy check → multipart upload → archive extraction → batch creation → executor spawn.
 - **Convention**: Return `Result<impl IntoResponse, (StatusCode, Json<Value>)>` from handlers that can fail. Use `Json(serde_json::json!({...}))` for responses.
 
 ### `auth.rs`
-- `verify_hotkey(hotkey)` — compares submitted hotkey against `AUTHORIZED_HOTKEY`.
-- `extract_hotkey(headers)` — reads `X-Hotkey` header from request.
+- `NonceStore` — `DashMap`-backed nonce tracker with 5-minute TTL and background reaper loop for replay protection.
+- `AuthHeaders` — struct holding `hotkey`, `nonce`, `signature`, `api_key` extracted from request headers.
+- `extract_auth_headers(headers)` — reads `X-Hotkey`, `X-Nonce`, `X-Signature`, `X-Api-Key` headers from request.
+- `verify_request(auth, nonce_store, expected_api_key)` — full auth pipeline: hotkey match → API key match → SS58 validation → nonce replay check → sr25519 signature verification.
 - `validate_ss58(address)` — validates SS58 address format using `bs58`.
-- **Convention**: Auth is mandatory — `POST /submit` requires a valid `X-Hotkey` header matching the authorized hotkey.
+- `verify_sr25519_signature(ss58_hotkey, message, signature_hex)` — verifies an sr25519 signature using `schnorrkel` with the Substrate signing context.
+- `AuthError` — enum with `UnauthorizedHotkey`, `InvalidHotkey`, `InvalidApiKey`, `NonceReused`, `InvalidSignature` variants, each with `.code()` and `.message()` methods.
+- **Convention**: Auth is mandatory — `POST /submit` requires all four headers (`X-Hotkey`, `X-Nonce`, `X-Signature`, `X-Api-Key`). The signed message is `hotkey + nonce`.
 
 ### `executor.rs`
 - `Executor::spawn_batch(batch, archive, concurrent_limit)` — spawns a tokio task that runs all tasks in the batch.
@@ -63,7 +68,9 @@ main.rs
 - `TaskTestResult`, `TaskResult`, `BatchResult` — core result data types.
 - `WsEvent` — WebSocket event struct with `event`, `batch_id`, `task_id`, `data`.
 - `Batch` — holds id, created_at, result (`Arc<Mutex<BatchResult>>`), events_tx (`broadcast::Sender<WsEvent>`), cancel channel.
-- `SessionManager` — `DashMap`-backed batch store with create/get/list/has_active_batch/mark operations.
+- `SessionStats` — atomic counters for created/active/completed/failed batches.
+- `BatchSummary` — lightweight struct for `list_batches()` output.
+- `SessionManager` — `DashMap`-backed batch store with `SessionStats`, create/get/list/has_active_batch/mark_completed/mark_failed operations.
 - `reaper_loop()` — runs every 60s, removes batches older than TTL, sends cancel signal.
 - **Convention**: All enums use `#[serde(rename_all = "snake_case")]`. Batch IDs are UUID v4 strings.