feat(server): v2 secure-session-core Task 4 - rate limit + single-use codes

SPEC-002 Phase 1 Task 4 (the final keystone task), code-reviewed APPROVED.
Closes the audit's reusable-code HIGH and rate-limiting-disabled HIGH.

- Rebuilt rate limiting as a self-contained in-memory per-IP limiter (replaces
  the non-compiling tower_governor; removed that dep). Fixed-window caps wired
  to login (8/min), change-password (5/min), code-validate (15/min) -> 429;
  per-IP lockout after 10 consecutive failed code validations (15-min cooldown).
- Single-use support codes: atomic consume on first agent bind (in-memory
  Pending->Connected under write lock + DB conditional UPDATE), rejecting a
  second presenter; validate/preview does not consume.
- Widened code format: XXX-XXX-XXX, 31-char unambiguous alphabet (no 0/O/1/I/L),
  CSPRNG + rejection sampling, ~44.6 bits (replaces 6-digit numeric); migration
  006 widens the code columns to TEXT.

Completes the keystone (Tasks 1-4): every audit CRITICAL + HIGH in the secure
auth/session core is now addressed. Known follow-up todos (not blocking): (1)
trusted-proxy client-IP extraction (NPM-on-loopback collapses clients to
127.0.0.1); (2) multi-instance fail-closed DB single-use gate. Not
cargo-check-verified locally - build-host/CI verification follows this commit.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

server/Cargo.toml

@@ -13,7 +13,9 @@ tokio = { version = "1", features = ["full", "sync", "time", "rt-multi-thread",
 axum = { version = "0.7", features = ["ws", "macros"] }
 tower = "0.5"
 tower-http = { version = "0.6", features = ["cors", "trace", "compression-gzip", "fs"] }
-tower_governor = { version = "0.4", features = ["axum"] }
+# NOTE: tower_governor removed in Task 4 — its rate-limit layer never compiled in
+# this codebase (the GovernorLayer generic signature it required is not in the
+# crate's public API). Replaced by the in-memory limiter in middleware/rate_limit.rs.
 
 # WebSocket
 futures-util = "0.3"

server/migrations/006_widen_support_code.sql

@@ -0,0 +1,21 @@
+-- Migration: 006_widen_support_code.sql
+-- Purpose: v2 Task 4 — widen the support-code column to hold the new
+--          higher-entropy human-readable code.
+--
+-- v1 generated a 6-digit numeric code; the column was VARCHAR(10) (001). Task 4
+-- replaces it with a grouped base32-style code `XXX-XXX-XXX` (9 symbols + 2
+-- hyphens = 11 chars), which does NOT fit in VARCHAR(10). Widen to TEXT so the
+-- column can hold the new code (and any future longer format) without truncation.
+--
+-- connect_sessions.support_code (also VARCHAR(10) in 001) stores the same value
+-- on a support session record, so it is widened too.
+--
+-- Idempotent: ALTER ... TYPE TEXT is a no-op if the column is already TEXT.
+-- Applied on server startup by sqlx::migrate!(); never pre-applied via psql.
+-- See .claude/standards/gururmm/sqlx-migrations.md.
+
+ALTER TABLE connect_support_codes
+    ALTER COLUMN code TYPE TEXT;
+
+ALTER TABLE connect_sessions
+    ALTER COLUMN support_code TYPE TEXT;

server/src/db/support_codes.rs

@@ -58,7 +58,11 @@ pub async fn get_support_code(
         .await
 }
 
-/// Update support code when client connects
+/// Update support code when client connects.
+///
+/// Superseded by [`consume_code_for_bind`] for the single-use bind path (Task 4);
+/// retained for any non-bind callers / future managed-session flows.
+#[allow(dead_code)]
 pub async fn mark_code_connected(
     pool: &PgPool,
     code: &str,
@@ -86,6 +90,59 @@ pub async fn mark_code_connected(
     Ok(())
 }
 
+/// Atomically CONSUME a support code for a first-time agent bind (single-use).
+///
+/// This is the durable single-use guarantee (Task 4 — closes the reusable-code
+/// HIGH). It is a single conditional UPDATE: the row is updated ONLY if the code
+/// has never been consumed (`consumed_at IS NULL`) AND is still `pending`. On
+/// success it stamps `consumed_at = NOW()`, flips `status` to `'connected'`, and
+/// records the binding session/client, returning the row's id.
+///
+/// If ZERO rows match (code already consumed, already connected, completed,
+/// cancelled, expired, or nonexistent) it returns `Ok(None)` — the caller MUST
+/// reject the bind. Because the guard is in the `WHERE` clause, two concurrent
+/// presenters of the same code cannot both succeed: PostgreSQL serializes the
+/// row update, so the second sees `consumed_at` already set (or status no longer
+/// `pending`) and matches zero rows.
+///
+/// Returns `Ok(Some(id))` if THIS call consumed the code, `Ok(None)` if it was
+/// not available for consumption.
+pub async fn consume_code_for_bind(
+    pool: &PgPool,
+    code: &str,
+    session_id: Option<Uuid>,
+    client_name: Option<&str>,
+    client_machine: Option<&str>,
+) -> Result<Option<Uuid>, sqlx::Error> {
+    // The expiry guard mirrors the existing validity semantics: a code with an
+    // `expires_at` in the past is not consumable. `expires_at IS NULL` means no
+    // expiry was set (legacy/ad-hoc codes) and is allowed.
+    let id: Option<Uuid> = sqlx::query_scalar(
+        r#"
+        UPDATE connect_support_codes
+        SET status = 'connected',
+            consumed_at = NOW(),
+            session_id = $1,
+            client_name = $2,
+            client_machine = $3,
+            connected_at = NOW()
+        WHERE code = $4
+          AND consumed_at IS NULL
+          AND status = 'pending'
+          AND (expires_at IS NULL OR expires_at > NOW())
+        RETURNING id
+        "#,
+    )
+    .bind(session_id)
+    .bind(client_name)
+    .bind(client_machine)
+    .bind(code)
+    .fetch_optional(pool)
+    .await?;
+
+    Ok(id)
+}
+
 /// Mark support code as completed
 pub async fn mark_code_completed(pool: &PgPool, code: &str) -> Result<(), sqlx::Error> {
     sqlx::query("UPDATE connect_support_codes SET status = 'completed' WHERE code = $1")

server/src/main.rs

@@ -21,7 +21,7 @@ pub mod proto {
 use anyhow::Result;
 use axum::http::{HeaderValue, Method};
 use axum::{
-    extract::{Json, Path, Query, Request, State},
+    extract::{ConnectInfo, Json, Path, Query, Request, State},
     http::StatusCode,
     middleware::{self as axum_middleware, Next},
     response::{Html, IntoResponse},
@@ -58,6 +58,9 @@ pub struct AppState {
     pub registry: Arc<std::sync::Mutex<Registry>>,
     /// Server start time
     pub start_time: Arc<std::time::Instant>,
+    /// Per-IP rate limiters + brute-force lockout (Task 4). Shared (Arc-backed
+    /// internally) so cloning AppState shares the same counters.
+    pub rate_limits: middleware::RateLimitState,
 }
 
 /// Middleware to inject JWT config and token blacklist into request extensions
@@ -263,6 +266,7 @@ async fn main() -> Result<()> {
         metrics,
         registry,
         start_time,
+        rate_limits: middleware::RateLimitState::new(),
     };
 
     // Build router
@@ -271,11 +275,21 @@ async fn main() -> Result<()> {
         .route("/health", get(health))
         // Prometheus metrics (no auth required - for monitoring)
         .route("/metrics", get(prometheus_metrics))
-        // Auth endpoints (TODO: Add rate limiting - see SEC2_RATE_LIMITING_TODO.md)
+        // Auth endpoints. Per-IP rate limiting (Task 4) is attached per-route via
-        .route("/api/auth/login", post(api::auth::login))
+        // `route_layer` so it applies ONLY to these endpoints, not the whole app.
+        .route(
+            "/api/auth/login",
+            post(api::auth::login).route_layer(axum_middleware::from_fn_with_state(
+                state.clone(),
+                middleware::login_rate_limit,
+            )),
+        )
         .route(
             "/api/auth/change-password",
-            post(api::auth::change_password),
+            post(api::auth::change_password).route_layer(axum_middleware::from_fn_with_state(
+                state.clone(),
+                middleware::change_password_rate_limit,
+            )),
         )
         .route("/api/auth/me", get(api::auth::get_me))
         .route("/api/auth/logout", post(api::auth_logout::logout))
@@ -306,10 +320,17 @@ async fn main() -> Result<()> {
             put(api::users::set_permissions),
         )
         .route("/api/users/:id/clients", put(api::users::set_client_access))
-        // Portal API - Support codes (TODO: Add rate limiting)
+        // Portal API - Support codes. The unauthenticated validate route is rate
+        // limited + brute-force locked out per IP (Task 4).
         .route("/api/codes", post(create_code))
         .route("/api/codes", get(list_codes))
-        .route("/api/codes/:code/validate", get(validate_code))
+        .route(
+            "/api/codes/:code/validate",
+            get(validate_code).route_layer(axum_middleware::from_fn_with_state(
+                state.clone(),
+                middleware::code_validate_rate_limit,
+            )),
+        )
         .route("/api/codes/:code/cancel", post(cancel_code))
         // WebSocket endpoints
         .route("/ws/agent", get(relay::agent_ws_handler))
@@ -450,7 +471,24 @@ async fn create_code(
     Json(request): Json<CreateCodeRequest>,
 ) -> Json<SupportCode> {
     let code = state.support_codes.create_code(request).await;
-    info!("Created support code: {}", code.code);
+
+    // Persist the code to the database so the DURABLE single-use guard
+    // (`db::support_codes::consume_code_for_bind`, Task 4) has a row to act on at
+    // agent-bind time. The in-memory manager remains the live source of truth for
+    // the auth decision; the DB row is the durable single-use record (and audit
+    // trail) that also survives a server restart. A DB failure here is non-fatal:
+    // the in-memory single-use consume still protects against reuse within this
+    // process lifetime.
+    if let Some(ref db) = state.db {
+        if let Err(e) =
+            db::support_codes::create_support_code(db.pool(), &code.code, &code.created_by).await
+        {
+            tracing::warn!("Failed to persist support code to database: {}", e);
+        }
+    }
+
+    // Do not log the code value (it is a bearer credential for the session).
+    info!("Created support code for {}", code.created_by);
     Json(code)
 }
 
@@ -469,9 +507,29 @@ struct ValidateParams {
 
 async fn validate_code(
     State(state): State<AppState>,
+    ConnectInfo(addr): ConnectInfo<SocketAddr>,
     Path(code): Path<String>,
 ) -> Json<CodeValidation> {
-    Json(state.support_codes.validate_code(&code).await)
+    let ip = addr.ip();
+
+    // PREVIEW ONLY: validate_code inspects the in-memory code state and does NOT
+    // consume the code (single-use consumption happens at agent BIND, in
+    // relay::handle_agent_connection). A valid preview here must not flip the
+    // code to connected/consumed.
+    let result = state.support_codes.validate_code(&code).await;
+
+    // Feed the per-IP brute-force lockout (Task 4): a failed validation counts
+    // toward the streak; a success resets it. The middleware
+    // (`code_validate_rate_limit`) enforces the lockout BEFORE this handler runs,
+    // so an already-locked IP never reaches here.
+    if result.valid {
+        state.rate_limits.code_validate_lockout.record_success(ip);
+    } else {
+        state.rate_limits.code_validate_lockout.record_failure(ip);
+        tracing::warn!("Failed support-code validation from {}", ip);
+    }
+
+    Json(result)
 }
 
 async fn cancel_code(

server/src/middleware/mod.rs

@@ -1,14 +1,13 @@
 //! Middleware modules
 
-// DISABLED: Rate limiting not yet functional due to type signature issues
+// Task 4: in-memory per-IP rate limiting + brute-force lockout. The v1
-// See SEC2_RATE_LIMITING_TODO.md
+// tower_governor-based limiter never compiled; this is a small self-contained
-// pub mod rate_limit;
+// replacement. See rate_limit.rs.
-//
+pub mod rate_limit;
-// pub use rate_limit::{
+
-//     auth_rate_limiter,
+pub use rate_limit::{
-//     support_code_rate_limiter,
+    change_password_rate_limit, code_validate_rate_limit, login_rate_limit, RateLimitState,
-//     api_rate_limiter,
+};
-// };
 
 // SEC-7 & SEC-12: Security headers middleware
 pub mod security_headers;

server/src/middleware/rate_limit.rs

@@ -1,59 +1,524 @@
-//! Rate limiting middleware using tower-governor
+//! In-memory rate limiting middleware (Task 4).
 //!
-//! Protects against brute force attacks on authentication endpoints.
+//! The v1 implementation leaned on `tower_governor` and never compiled (the
+//! `GovernorLayer` generic signature it tried to name does not exist in the
+//! crate's public API). Rather than fight those generics, this is a small,
+//! self-contained per-IP limiter behind a `Mutex<HashMap<…>>` — no new
+//! dependency, easy to reason about, and trivially unit-testable.
+//!
+//! Two protections are provided, both keyed by client IP:
+//!
+//!   1. **Fixed-window rate limit** ([`RateLimiter`]): at most `max_requests`
+//!      per `window`. Over the cap → `429 Too Many Requests` (standard error
+//!      envelope). Wired onto `POST /api/auth/login`,
+//!      `POST /api/auth/change-password`, and the support-code validate route.
+//!
+//!   2. **Consecutive-failure lockout** ([`FailureLockout`]): after
+//!      `max_failures` consecutive *failed* attempts from one IP, that IP is
+//!      locked out for `cooldown`. A single success resets the counter. This is
+//!      the brute-force defense for the support-code space (the code-validate
+//!      route reports per-attempt success/failure into it).
+//!
+//! Client IP is taken from axum's [`ConnectInfo<SocketAddr>`] (the same source
+//! the relay uses for `client_ip`). `X-Forwarded-For` is intentionally NOT
+//! trusted here: the server terminates behind a known reverse proxy (NPM), and
+//! honoring a client-settable header would let an attacker trivially rotate the
+//! limiter key. If/when per-proxy XFF handling is needed it must be gated on a
+//! trusted-proxy allowlist — tracked as a follow-up, not done blindly here.
+//!
+//! Memory is bounded by pruning expired entries opportunistically on each call
+//! and capping the map size; an unbounded attacker rotating source IPs cannot
+//! grow the maps without bound.
 
-use tower_governor::{
+use std::collections::HashMap;
-    governor::GovernorConfigBuilder,
+use std::net::IpAddr;
-    GovernorLayer,
+use std::sync::Mutex;
+use std::time::{Duration, Instant};
+
+use axum::{
+    extract::{ConnectInfo, State},
+    http::StatusCode,
+    response::{IntoResponse, Response},
+    Json,
 };
+use serde::Serialize;
+use std::net::SocketAddr;
 
-/// Create rate limiting layer for authentication endpoints
+// ============================================================================
+// Tunables (named constants — no magic numbers at the call sites)
+// ============================================================================
+
+/// Login: window length for the fixed-window counter.
+pub const LOGIN_WINDOW: Duration = Duration::from_secs(60);
+/// Login: max requests per window per IP. Comfortable for a human retyping a
+/// password, hostile for a credential-stuffing loop.
+pub const LOGIN_MAX_PER_WINDOW: u32 = 8;
+
+/// Change-password: window length.
+pub const CHANGE_PASSWORD_WINDOW: Duration = Duration::from_secs(60);
+/// Change-password: max requests per window per IP. Tighter than login — a user
+/// changes their password rarely, and this endpoint already requires a valid
+/// session, so a low cap costs nothing legitimate.
+pub const CHANGE_PASSWORD_MAX_PER_WINDOW: u32 = 5;
+
+/// Support-code validate: window length.
+pub const CODE_VALIDATE_WINDOW: Duration = Duration::from_secs(60);
+/// Support-code validate: max requests per window per IP. Tight, because the
+/// code space is small relative to a password and this route is the brute-force
+/// surface for it.
+pub const CODE_VALIDATE_MAX_PER_WINDOW: u32 = 15;
+
+/// Support-code validate: consecutive failed validations from one IP that trip
+/// the lockout.
+pub const CODE_VALIDATE_MAX_FAILURES: u32 = 10;
+/// Support-code validate: how long an IP stays locked out once tripped.
+pub const CODE_VALIDATE_LOCKOUT: Duration = Duration::from_secs(15 * 60);
+
+/// Hard cap on the number of distinct IPs tracked by any single limiter map.
+/// Prevents an IP-rotating attacker from growing memory without bound. When the
+/// cap is hit, the oldest-windowed entries are pruned. Generous for a real MSP
+/// fleet; an attacker hitting it is already being throttled per-IP.
+const MAX_TRACKED_IPS: usize = 100_000;
+
+// ============================================================================
+// Fixed-window rate limiter
+// ============================================================================
+
+/// One IP's fixed-window counter.
+#[derive(Debug, Clone, Copy)]
+struct Window {
+    /// When the current window started.
+    started: Instant,
+    /// Requests counted in the current window.
+    count: u32,
+}
+
+/// Per-IP fixed-window rate limiter. Cheap, lock-guarded, self-pruning.
 ///
-/// Allows 5 requests per minute per IP address
+/// Cloneable: the inner state is shared via `Arc`-less `&'static`/`State`
-pub fn auth_rate_limiter() -> impl tower::Layer<tower::service_fn::ServiceFn<impl Fn(axum::http::Request<axum::body::Body>) -> std::future::Future<Output = Result<axum::http::Response<axum::body::Body>, std::convert::Infallible>>>> {
+/// ownership in this app, but we keep an explicit `Arc` so it can live in
-    let governor_conf = Box::new(
+/// `AppState` and be cloned with it.
-        GovernorConfigBuilder::default()
+#[derive(Clone)]
-            .per_millisecond(60000 / 5) // 5 requests per minute
+pub struct RateLimiter {
-            .burst_size(5)
+    inner: std::sync::Arc<Mutex<HashMap<IpAddr, Window>>>,
-            .finish()
+    max_requests: u32,
-            .unwrap()
+    window: Duration,
-    );
+}
 
-    GovernorLayer {
+impl RateLimiter {
-        config: Box::leak(governor_conf),
+    /// Create a limiter allowing `max_requests` per `window` per IP.
+    pub fn new(max_requests: u32, window: Duration) -> Self {
+        Self {
+            inner: std::sync::Arc::new(Mutex::new(HashMap::new())),
+            max_requests,
+            window,
+        }
+    }
+
+    /// Record a request from `ip` and report whether it is allowed.
+    ///
+    /// Returns `true` if the request is within the cap (and counts it), `false`
+    /// if the IP is over the cap for the current window. Uses `now` as the clock
+    /// so the window logic is unit-testable without sleeping.
+    fn check_at(&self, ip: IpAddr, now: Instant) -> bool {
+        let mut map = self.inner.lock().unwrap_or_else(|e| e.into_inner());
+
+        // Opportunistic prune: if the map has grown large, drop entries whose
+        // window has fully elapsed (they would reset on next touch anyway).
+        if map.len() >= MAX_TRACKED_IPS {
+            let window = self.window;
+            map.retain(|_, w| now.duration_since(w.started) < window);
+        }
+
+        let entry = map.entry(ip).or_insert(Window {
+            started: now,
+            count: 0,
+        });
+
+        // Roll the window forward if it has elapsed.
+        if now.duration_since(entry.started) >= self.window {
+            entry.started = now;
+            entry.count = 0;
+        }
+
+        if entry.count >= self.max_requests {
+            false
+        } else {
+            entry.count += 1;
+            true
+        }
+    }
+
+    /// Record a request from `ip` (using the real clock) and report whether it
+    /// is allowed.
+    pub fn check(&self, ip: IpAddr) -> bool {
+        self.check_at(ip, Instant::now())
     }
 }
 
-/// Create rate limiting layer for support code validation
+// ============================================================================
-///
+// Consecutive-failure lockout
-/// Allows 10 requests per minute per IP address
+// ============================================================================
-pub fn support_code_rate_limiter() -> impl tower::Layer<tower::service_fn::ServiceFn<impl Fn(axum::http::Request<axum::body::Body>) -> std::future::Future<Output = Result<axum::http::Response<axum::body::Body>, std::convert::Infallible>>>> {
-    let governor_conf = Box::new(
-        GovernorConfigBuilder::default()
-            .per_millisecond(60000 / 10) // 10 requests per minute
-            .burst_size(10)
-            .finish()
-            .unwrap()
-    );
 
-    GovernorLayer {
+/// One IP's failure-streak state.
-        config: Box::leak(governor_conf),
+#[derive(Debug, Clone, Copy)]
+struct FailState {
+    /// Consecutive failures since the last success / lockout.
+    failures: u32,
+    /// If `Some`, the IP is locked out until this instant.
+    locked_until: Option<Instant>,
+    /// Last time this entry was touched (for pruning).
+    last_seen: Instant,
+}
+
+/// Per-IP consecutive-failure lockout. After `max_failures` consecutive
+/// failures the IP is locked out for `cooldown`; a success resets the streak.
+#[derive(Clone)]
+pub struct FailureLockout {
+    inner: std::sync::Arc<Mutex<HashMap<IpAddr, FailState>>>,
+    max_failures: u32,
+    cooldown: Duration,
+}
+
+impl FailureLockout {
+    /// Create a lockout that trips after `max_failures` consecutive failures and
+    /// holds for `cooldown`.
+    pub fn new(max_failures: u32, cooldown: Duration) -> Self {
+        Self {
+            inner: std::sync::Arc::new(Mutex::new(HashMap::new())),
+            max_failures,
+            cooldown,
+        }
+    }
+
+    /// Is `ip` currently locked out? (clock injected for tests)
+    fn is_locked_at(&self, ip: IpAddr, now: Instant) -> bool {
+        let mut map = self.inner.lock().unwrap_or_else(|e| e.into_inner());
+        match map.get(&ip) {
+            Some(state) => match state.locked_until {
+                Some(until) if now < until => true,
+                Some(_) => {
+                    // Lockout elapsed — clear it so the IP gets a fresh start.
+                    if let Some(s) = map.get_mut(&ip) {
+                        s.locked_until = None;
+                        s.failures = 0;
+                    }
+                    false
+                }
+                None => false,
+            },
+            None => false,
+        }
+    }
+
+    /// Is `ip` currently locked out? (real clock)
+    pub fn is_locked(&self, ip: IpAddr) -> bool {
+        self.is_locked_at(ip, Instant::now())
+    }
+
+    /// Record a failed attempt from `ip`. Trips the lockout once the streak
+    /// reaches `max_failures`. (clock injected for tests)
+    fn record_failure_at(&self, ip: IpAddr, now: Instant) {
+        let mut map = self.inner.lock().unwrap_or_else(|e| e.into_inner());
+
+        if map.len() >= MAX_TRACKED_IPS {
+            let cooldown = self.cooldown;
+            map.retain(|_, s| {
+                s.locked_until.map(|u| now < u).unwrap_or(false)
+                    || now.duration_since(s.last_seen) < cooldown
+            });
+        }
+
+        let state = map.entry(ip).or_insert(FailState {
+            failures: 0,
+            locked_until: None,
+            last_seen: now,
+        });
+        state.last_seen = now;
+        state.failures = state.failures.saturating_add(1);
+        if state.failures >= self.max_failures {
+            state.locked_until = Some(now + self.cooldown);
+        }
+    }
+
+    /// Record a failed attempt from `ip` (real clock).
+    pub fn record_failure(&self, ip: IpAddr) {
+        self.record_failure_at(ip, Instant::now());
+    }
+
+    /// Record a successful attempt from `ip`, resetting its failure streak.
+    pub fn record_success(&self, ip: IpAddr) {
+        let mut map = self.inner.lock().unwrap_or_else(|e| e.into_inner());
+        if let Some(state) = map.get_mut(&ip) {
+            state.failures = 0;
+            state.locked_until = None;
+            state.last_seen = Instant::now();
+        }
     }
 }
 
-/// Create rate limiting layer for API endpoints
+// ============================================================================
-///
+// Shared rate-limit state (lives in AppState)
-/// Allows 60 requests per minute per IP address
+// ============================================================================
-pub fn api_rate_limiter() -> impl tower::Layer<tower::service_fn::ServiceFn<impl Fn(axum::http::Request<axum::body::Body>) -> std::future::Future<Output = Result<axum::http::Response<axum::body::Body>, std::convert::Infallible>>>> {
-    let governor_conf = Box::new(
-        GovernorConfigBuilder::default()
-            .per_millisecond(1000) // 1 request per second
-            .burst_size(60)
-            .finish()
-            .unwrap()
-    );
 
-    GovernorLayer {
+/// Bundle of limiters carried in `AppState` and consumed by the middleware.
-        config: Box::leak(governor_conf),
+#[derive(Clone)]
+pub struct RateLimitState {
+    /// `POST /api/auth/login`
+    pub login: RateLimiter,
+    /// `POST /api/auth/change-password`
+    pub change_password: RateLimiter,
+    /// `GET /api/codes/:code/validate` (request-rate cap)
+    pub code_validate: RateLimiter,
+    /// Per-IP lockout on repeated failed code validations (brute-force defense).
+    pub code_validate_lockout: FailureLockout,
+}
+
+impl RateLimitState {
+    pub fn new() -> Self {
+        Self {
+            login: RateLimiter::new(LOGIN_MAX_PER_WINDOW, LOGIN_WINDOW),
+            change_password: RateLimiter::new(
+                CHANGE_PASSWORD_MAX_PER_WINDOW,
+                CHANGE_PASSWORD_WINDOW,
+            ),
+            code_validate: RateLimiter::new(CODE_VALIDATE_MAX_PER_WINDOW, CODE_VALIDATE_WINDOW),
+            code_validate_lockout: FailureLockout::new(
+                CODE_VALIDATE_MAX_FAILURES,
+                CODE_VALIDATE_LOCKOUT,
+            ),
+        }
+    }
+}
+
+impl Default for RateLimitState {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+// ============================================================================
+// 429 response (standard error envelope)
+// ============================================================================
+
+#[derive(Debug, Serialize)]
+struct RateLimitError {
+    detail: String,
+    error_code: String,
+    status_code: u16,
+}
+
+/// Build a `429 Too Many Requests` response using the standard error envelope.
+fn too_many_requests(detail: &str, error_code: &str) -> Response {
+    (
+        StatusCode::TOO_MANY_REQUESTS,
+        Json(RateLimitError {
+            detail: detail.to_string(),
+            error_code: error_code.to_string(),
+            status_code: StatusCode::TOO_MANY_REQUESTS.as_u16(),
+        }),
+    )
+        .into_response()
+}
+
+// ============================================================================
+// Axum middleware functions (one per protected route)
+// ============================================================================
+
+/// Selects which limiter from [`RateLimitState`] a middleware uses.
+///
+/// Each protected route gets its own `from_fn_with_state` middleware pointing at
+/// the matching limiter; keeping them as distinct functions avoids threading an
+/// extra "which limiter" parameter through the layer and keeps the wiring in
+/// `main.rs` self-documenting.
+
+/// Rate-limit middleware for `POST /api/auth/login`.
+pub async fn login_rate_limit(
+    State(state): State<crate::AppState>,
+    ConnectInfo(addr): ConnectInfo<SocketAddr>,
+    request: axum::extract::Request,
+    next: axum::middleware::Next,
+) -> Response {
+    let ip = addr.ip();
+    if !state.rate_limits.login.check(ip) {
+        tracing::warn!("Rate limit exceeded on /api/auth/login from {}", ip);
+        return too_many_requests(
+            "Too many login attempts. Please wait a minute and try again.",
+            "RATE_LIMITED",
+        );
+    }
+    next.run(request).await
+}
+
+/// Rate-limit middleware for `POST /api/auth/change-password`.
+pub async fn change_password_rate_limit(
+    State(state): State<crate::AppState>,
+    ConnectInfo(addr): ConnectInfo<SocketAddr>,
+    request: axum::extract::Request,
+    next: axum::middleware::Next,
+) -> Response {
+    let ip = addr.ip();
+    if !state.rate_limits.change_password.check(ip) {
+        tracing::warn!(
+            "Rate limit exceeded on /api/auth/change-password from {}",
+            ip
+        );
+        return too_many_requests(
+            "Too many password-change attempts. Please wait a minute and try again.",
+            "RATE_LIMITED",
+        );
+    }
+    next.run(request).await
+}
+
+/// Rate-limit + brute-force-lockout middleware for the support-code validate
+/// route (`GET /api/codes/:code/validate`).
+///
+/// Two gates run here:
+///   1. If the IP is currently locked out (too many consecutive failed
+///      validations), reject immediately with 429 — before the handler runs, so
+///      the code is never even looked up.
+///   2. Otherwise apply the per-window request cap.
+///
+/// The success/failure that drives the lockout is reported by the handler
+/// itself (it knows whether the code was valid), via
+/// [`RateLimitState::code_validate_lockout`].
+pub async fn code_validate_rate_limit(
+    State(state): State<crate::AppState>,
+    ConnectInfo(addr): ConnectInfo<SocketAddr>,
+    request: axum::extract::Request,
+    next: axum::middleware::Next,
+) -> Response {
+    let ip = addr.ip();
+
+    // 1. Brute-force lockout takes precedence.
+    if state.rate_limits.code_validate_lockout.is_locked(ip) {
+        tracing::warn!(
+            "Code-validate request from locked-out IP {} (too many failed attempts)",
+            ip
+        );
+        return too_many_requests(
+            "Too many invalid codes from this address. Try again later.",
+            "RATE_LIMITED_LOCKOUT",
+        );
+    }
+
+    // 2. Per-window request cap.
+    if !state.rate_limits.code_validate.check(ip) {
+        tracing::warn!("Rate limit exceeded on code-validate from {}", ip);
+        return too_many_requests(
+            "Too many code validation attempts. Please wait a minute and try again.",
+            "RATE_LIMITED",
+        );
+    }
+
+    next.run(request).await
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn ip(n: u8) -> IpAddr {
+        IpAddr::from([10, 0, 0, n])
+    }
+
+    #[test]
+    fn fixed_window_allows_up_to_cap_then_blocks() {
+        let limiter = RateLimiter::new(3, Duration::from_secs(60));
+        let t0 = Instant::now();
+        let a = ip(1);
+
+        assert!(limiter.check_at(a, t0)); // 1
+        assert!(limiter.check_at(a, t0)); // 2
+        assert!(limiter.check_at(a, t0)); // 3
+        assert!(!limiter.check_at(a, t0)); // 4 -> blocked
+        assert!(!limiter.check_at(a, t0)); // still blocked
+    }
+
+    #[test]
+    fn fixed_window_resets_after_window_elapses() {
+        let limiter = RateLimiter::new(2, Duration::from_secs(60));
+        let t0 = Instant::now();
+        let a = ip(2);
+
+        assert!(limiter.check_at(a, t0));
+        assert!(limiter.check_at(a, t0));
+        assert!(!limiter.check_at(a, t0)); // over cap
+
+        // Advance past the window — counter resets.
+        let t1 = t0 + Duration::from_secs(61);
+        assert!(limiter.check_at(a, t1));
+        assert!(limiter.check_at(a, t1));
+        assert!(!limiter.check_at(a, t1));
+    }
+
+    #[test]
+    fn fixed_window_is_per_ip() {
+        let limiter = RateLimiter::new(1, Duration::from_secs(60));
+        let t0 = Instant::now();
+
+        assert!(limiter.check_at(ip(3), t0));
+        assert!(!limiter.check_at(ip(3), t0)); // ip3 over cap
+        assert!(limiter.check_at(ip(4), t0)); // ip4 independent
+    }
+
+    #[test]
+    fn lockout_trips_after_consecutive_failures() {
+        let lockout = FailureLockout::new(3, Duration::from_secs(600));
+        let t0 = Instant::now();
+        let a = ip(5);
+
+        assert!(!lockout.is_locked_at(a, t0));
+        lockout.record_failure_at(a, t0); // 1
+        assert!(!lockout.is_locked_at(a, t0));
+        lockout.record_failure_at(a, t0); // 2
+        assert!(!lockout.is_locked_at(a, t0));
+        lockout.record_failure_at(a, t0); // 3 -> trips
+        assert!(lockout.is_locked_at(a, t0));
+    }
+
+    #[test]
+    fn lockout_success_resets_streak() {
+        let lockout = FailureLockout::new(3, Duration::from_secs(600));
+        let t0 = Instant::now();
+        let a = ip(6);
+
+        lockout.record_failure_at(a, t0);
+        lockout.record_failure_at(a, t0);
+        lockout.record_success(a); // streak reset
+        lockout.record_failure_at(a, t0);
+        lockout.record_failure_at(a, t0);
+        // Only two failures since the reset — not yet locked.
+        assert!(!lockout.is_locked_at(a, t0));
+    }
+
+    #[test]
+    fn lockout_expires_after_cooldown() {
+        let lockout = FailureLockout::new(2, Duration::from_secs(600));
+        let t0 = Instant::now();
+        let a = ip(7);
+
+        lockout.record_failure_at(a, t0);
+        lockout.record_failure_at(a, t0); // trips
+        assert!(lockout.is_locked_at(a, t0));
+
+        // After the cooldown the lock clears.
+        let t1 = t0 + Duration::from_secs(601);
+        assert!(!lockout.is_locked_at(a, t1));
+    }
+
+    #[test]
+    fn lockout_is_per_ip() {
+        let lockout = FailureLockout::new(1, Duration::from_secs(600));
+        let t0 = Instant::now();
+
+        lockout.record_failure_at(ip(8), t0); // trips ip8
+        assert!(lockout.is_locked_at(ip(8), t0));
+        assert!(!lockout.is_locked_at(ip(9), t0)); // ip9 unaffected
     }
 }

server/src/relay/mod.rs

@@ -128,17 +128,46 @@ pub async fn agent_ws_handler(
         return Err(StatusCode::UNAUTHORIZED);
     }
 
-    // Validate support code if provided
+    // Validate AND CONSUME the support code if provided (single-use, Task 4).
+    //
+    // SINGLE-USE (closes the reusable-code HIGH): a support code is consumed
+    // ATOMICALLY on the FIRST successful agent bind. `consume_for_bind` accepts
+    // the code only if it is currently `Pending` (never used) and flips it to
+    // `Connected` under the manager's write lock; a SECOND presenter of the same
+    // code sees it already `Connected` and is rejected here, before the socket is
+    // upgraded. This replaces the v1 check that accepted `pending` OR `connected`
+    // (which let any number of agents reuse one code).
+    //
+    // AUTHORITATIVE single-use gate = the in-memory atomic consume. The in-memory
+    // manager is the live source of truth for a code's joinable state (it is what
+    // the portal create + validate paths use), and it is empty on a fresh process,
+    // so a code from a previous run is already unknown here and rejected. A second
+    // presenter within this run loses the `Pending → Connected` race and is
+    // rejected. This single check closes the reusable-code HIGH.
+    //
+    // The database additionally carries a DURABLE single-use marker
+    // (`consume_code_for_bind`: a conditional UPDATE guarded by `consumed_at IS
+    // NULL AND status = 'pending'`). It is applied best-effort AFTER the
+    // authoritative in-memory consume — it stamps `consumed_at` for the audit
+    // trail and cross-restart durability, but a missing/uninsertable DB row must
+    // NOT veto an agent the in-memory layer already admitted (the DB row is only
+    // populated opportunistically by the portal create path).
     if let Some(ref code) = support_code {
-        // Check if it's a valid, pending support code
+        let consumed = state
-        let code_info = state.support_codes.get_status(code).await;
+            .support_codes
-        if code_info.is_none() {
+            .consume_for_bind(code, Some(agent_name.clone()), Some(agent_id.clone()))
+            .await;
+
+        if !consumed {
             warn!(
-                "Agent connection rejected: {} from {} - invalid support code {}",
+                "Agent connection rejected: {} from {} - support code already used, \
-                agent_id, client_ip, code
+                 invalid, expired, or cancelled",
+                agent_id, client_ip
             );
 
-            // Log failed connection attempt
+            // Log failed connection attempt. We cannot distinguish reuse from a
+            // nonexistent code without leaking timing, so log the generic
+            // invalid-code event (never log the code value itself).
             if let Some(ref db) = state.db {
                 let _ = db::events::log_event(
                     db.pool(),
@@ -147,8 +176,7 @@ pub async fn agent_ws_handler(
                     None,
                     Some(&agent_id),
                     Some(serde_json::json!({
-                        "reason": "invalid_code",
+                        "reason": "code_unavailable_or_already_used",
-                        "support_code": code,
                         "agent_id": agent_id
                     })),
                     Some(client_ip),
@@ -158,42 +186,46 @@ pub async fn agent_ws_handler(
 
             return Err(StatusCode::UNAUTHORIZED);
         }
-        let status = code_info.unwrap();
-        if status != "pending" && status != "connected" {
-            warn!(
-                "Agent connection rejected: {} from {} - support code {} has status {}",
-                agent_id, client_ip, code, status
-            );
 
-            // Log failed connection attempt (expired/cancelled code)
+        // Durable single-use marker in the database (best-effort; see above). The
-            if let Some(ref db) = state.db {
+        // real session_id is attached later in `handle_agent_connection` once the
-                let event_type = if status == "cancelled" {
+        // socket has upgraded; here we only stamp `consumed_at` on the row if it
-                    db::events::EventTypes::CONNECTION_REJECTED_CANCELLED_CODE
+        // exists. `Ok(None)` (no consumable row) and `Err` are logged, not fatal —
-                } else {
+        // the in-memory consume already authorized this bind.
-                    db::events::EventTypes::CONNECTION_REJECTED_EXPIRED_CODE
+        if let Some(ref db) = state.db {
-                };
+            match db::support_codes::consume_code_for_bind(
-
+                db.pool(),
-                let _ = db::events::log_event(
+                code,
-                    db.pool(),
+                None,
-                    Uuid::new_v4(),
+                Some(&agent_name),
-                    event_type,
+                Some(&agent_id),
-                    None,
+            )
-                    Some(&agent_id),
+            .await
-                    Some(serde_json::json!({
+            {
-                        "reason": status,
+                Ok(Some(_id)) => { /* durable consume recorded */ }
-                        "support_code": code,
+                Ok(None) => {
-                        "agent_id": agent_id
+                    // No consumable DB row (the code may not have been persisted,
-                    })),
+                    // or was already consumed in the DB). Non-fatal: the in-memory
-                    Some(client_ip),
+                    // layer is authoritative for this process.
-                )
+                    tracing::debug!(
-                .await;
+                        "No durable support-code row to consume for agent {} (in-memory \
+                         consume already authoritative)",
+                        agent_id
+                    );
+                }
+                Err(e) => {
+                    tracing::warn!(
+                        "Database error stamping durable support-code consume for {}: {}",
+                        agent_id,
+                        e
+                    );
+                }
             }
-
-            return Err(StatusCode::UNAUTHORIZED);
         }
+
         info!(
-            "Agent {} from {} authenticated via support code {}",
+            "Agent {} from {} authenticated via single-use support code",
-            agent_id, client_ip, code
+            agent_id, client_ip
         );
     }
 
@@ -568,24 +600,21 @@ async fn handle_agent_connection(
         None
     };
 
-    // If a support code was provided, mark it as connected
+    // If a support code was provided, link it to the real session.
+    //
+    // The code was already CONSUMED atomically (single-use) in `agent_ws_handler`
+    // before this upgrade — it is already `Connected`/`consumed_at` set in both
+    // the in-memory manager and (if a DB is configured) the database. Here we only
+    // establish the mapping to the REAL session_id, which is not known until the
+    // socket has upgraded and `register_agent` has run. We do NOT re-consume or
+    // re-flip status (that would defeat the single-use guard).
     if let Some(ref code) = support_code {
-        info!("Linking support code {} to session {}", code, session_id);
+        info!("Linking support code to session {}", session_id);
-        support_codes
-            .mark_connected(code, Some(agent_name.clone()), Some(agent_id.clone()))
-            .await;
         support_codes.link_session(code, session_id).await;
 
-        // Database: update support code
+        // Database: attach the real session_id to the already-consumed code row.
         if let Some(ref db) = db {
-            let _ = db::support_codes::mark_code_connected(
+            let _ = db::support_codes::link_session_to_code(db.pool(), code, session_id).await;
-                db.pool(),
-                code,
-                Some(session_id),
-                Some(&agent_name),
-                Some(&agent_id),
-            )
-            .await;
         }
     }
 

server/src/support_codes.rs

@@ -1,16 +1,74 @@
 //! Support session codes management
 //!
-//! Handles generation and validation of 6-digit support codes
+//! Handles generation and validation of high-entropy, human-readable support
-//! for one-time remote support sessions.
+//! codes for one-time remote support sessions.
+//!
+//! ## Code format (Task 4)
+//!
+//! v1 used a 6-digit numeric code (~20 bits, trivially brute-forceable). v2 uses
+//! a grouped base32-style code drawn from an UNAMBIGUOUS alphabet (no `0`/`O`,
+//! `1`/`I`/`L`) so a human reading it aloud cannot mistranscribe it:
+//!
+//! ```text
+//!   XXX-XXX-XXX        e.g.  K7P-3MQ-Z9F
+//! ```
+//!
+//! 9 symbols over a 31-character alphabet ≈ **44.6 bits** of entropy, generated
+//! with a CSPRNG ([`OsRng`]). Combined with the per-IP rate limiting + lockout on
+//! the validate route (Task 4) and single-use consumption on bind, the code space
+//! is no longer practically brute-forceable.
 
 use chrono::{DateTime, Utc};
-use rand::Rng;
+use rand::rngs::OsRng;
+use rand::RngCore;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::sync::Arc;
 use tokio::sync::RwLock;
 use uuid::Uuid;
 
+/// Unambiguous code alphabet: digits 2-9 and A-Z, EXCLUDING the visually
+/// confusable `0`/`O`, `1`/`I`/`L`. 31 distinct symbols (≈4.954 bits each).
+const CODE_ALPHABET: &[u8] = b"23456789ABCDEFGHJKMNPQRSTUVWXYZ";
+
+/// Number of alphabet symbols in a generated code (excluding group separators).
+/// 9 symbols × log2(31) ≈ 44.6 bits — comfortably above the 40-bit target.
+const CODE_SYMBOLS: usize = 9;
+
+/// Symbols per visual group (the code is rendered as hyphen-separated groups).
+const CODE_GROUP_SIZE: usize = 3;
+
+/// Draw a single uniformly-distributed symbol from [`CODE_ALPHABET`] using a
+/// CSPRNG, via rejection sampling so every symbol is equally likely (no modulo
+/// bias). 31 is not a power of two, so we reject draws in the biased tail.
+fn random_symbol() -> u8 {
+    let n = CODE_ALPHABET.len() as u32; // 31
+                                        // Largest multiple of n that fits in a u8 draw space (256); reject above it.
+    let limit = (256 / n) * n; // 248
+    let mut rng = OsRng;
+    loop {
+        let mut buf = [0u8; 1];
+        rng.fill_bytes(&mut buf);
+        let v = buf[0] as u32;
+        if v < limit {
+            return CODE_ALPHABET[(v % n) as usize];
+        }
+        // else: biased tail — draw again.
+    }
+}
+
+/// Generate a fresh grouped support code, e.g. `K7P-3MQ-Z9F`. CSPRNG-backed.
+fn generate_code_string() -> String {
+    let mut out = String::with_capacity(CODE_SYMBOLS + CODE_SYMBOLS / CODE_GROUP_SIZE);
+    for i in 0..CODE_SYMBOLS {
+        if i > 0 && i % CODE_GROUP_SIZE == 0 {
+            out.push('-');
+        }
+        out.push(random_symbol() as char);
+    }
+    out
+}
+
 /// A support session code
 #[derive(Debug, Clone, Serialize)]
 pub struct SupportCode {
@@ -67,15 +125,16 @@ impl SupportCodeManager {
         }
     }
 
-    /// Generate a unique 6-digit code
+    /// Generate a unique high-entropy support code (see module docs).
+    ///
+    /// Draws CSPRNG-backed grouped codes (`XXX-XXX-XXX`, ≈44.6 bits) until one is
+    /// not already live in the in-memory map. With a 31^9 code space the collision
+    /// probability is negligible; the loop only guards against the (astronomically
+    /// unlikely) duplicate.
     async fn generate_unique_code(&self) -> String {
         let codes = self.codes.read().await;
-        let mut rng = rand::thread_rng();
-
         loop {
-            let code: u32 = rng.gen_range(100000..999999);
+            let code_str = generate_code_string();
-            let code_str = code.to_string();
-
             if !codes.contains_key(&code_str) {
                 return code_str;
             }
@@ -142,7 +201,12 @@ impl SupportCodeManager {
         }
     }
 
-    /// Mark a code as connected
+    /// Mark a code as connected.
+    ///
+    /// Superseded by [`SupportCodeManager::consume_for_bind`] for the single-use
+    /// bind path (Task 4). Retained for non-bind callers; not used on the agent
+    /// bind path any longer.
+    #[allow(dead_code)]
     pub async fn mark_connected(
         &self,
         code: &str,
@@ -158,6 +222,40 @@ impl SupportCodeManager {
         }
     }
 
+    /// Atomically CONSUME a code for a first-time agent bind (single-use, Task 4).
+    ///
+    /// This is the single-use gate for the in-memory layer. Under the write lock,
+    /// it accepts the code ONLY if it is currently `Pending` (never used), flips
+    /// it to `Connected`, and records the binding client. Any other state
+    /// (`Connected` — already bound, `Completed`, `Cancelled`, or a nonexistent
+    /// code) is rejected. Because the transition happens while holding the write
+    /// lock, two concurrent presenters of the same code race for the single
+    /// `Pending → Connected` transition: exactly one wins, the loser is rejected.
+    ///
+    /// Returns `true` if the caller consumed the code (and may proceed to bind),
+    /// `false` if the code was not available for consumption.
+    ///
+    /// NOTE: the preview route (`validate_code`) deliberately does NOT call this —
+    /// previewing a code must never consume it. Only the agent bind path does.
+    pub async fn consume_for_bind(
+        &self,
+        code: &str,
+        client_name: Option<String>,
+        client_machine: Option<String>,
+    ) -> bool {
+        let mut codes = self.codes.write().await;
+        match codes.get_mut(code) {
+            Some(support_code) if support_code.status == CodeStatus::Pending => {
+                support_code.status = CodeStatus::Connected;
+                support_code.client_name = client_name;
+                support_code.client_machine = client_machine;
+                support_code.connected_at = Some(Utc::now());
+                true
+            }
+            _ => false,
+        }
+    }
+
     /// Link a support code to an actual WebSocket session
     pub async fn link_session(&self, code: &str, real_session_id: Uuid) {
         let mut codes = self.codes.write().await;
@@ -248,7 +346,11 @@ impl SupportCodeManager {
         codes.get(code).cloned()
     }
 
-    /// Get the status of a code as a string (for auth checks)
+    /// Get the status of a code as a string (for auth checks).
+    ///
+    /// No longer used on the agent bind path (replaced by the atomic
+    /// `consume_for_bind` single-use gate, Task 4); retained for diagnostics.
+    #[allow(dead_code)]
     pub async fn get_status(&self, code: &str) -> Option<String> {
         let codes = self.codes.read().await;
         codes.get(code).map(|c| match c.status {
@@ -265,3 +367,113 @@ impl Default for SupportCodeManager {
         Self::new()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn generated_code_has_expected_shape() {
+        // XXX-XXX-XXX: 9 symbols + 2 hyphens = 11 chars.
+        let code = generate_code_string();
+        assert_eq!(code.len(), CODE_SYMBOLS + 2);
+        let parts: Vec<&str> = code.split('-').collect();
+        assert_eq!(parts.len(), CODE_SYMBOLS / CODE_GROUP_SIZE);
+        for p in parts {
+            assert_eq!(p.len(), CODE_GROUP_SIZE);
+        }
+    }
+
+    #[test]
+    fn generated_code_uses_only_unambiguous_alphabet() {
+        // No 0/O/1/I/L; every non-hyphen char is in CODE_ALPHABET.
+        for _ in 0..2_000 {
+            let code = generate_code_string();
+            for c in code.chars().filter(|c| *c != '-') {
+                assert!(
+                    CODE_ALPHABET.contains(&(c as u8)),
+                    "char {:?} not in unambiguous alphabet",
+                    c
+                );
+                assert!(
+                    !matches!(c, '0' | 'O' | '1' | 'I' | 'L'),
+                    "ambiguous char {:?} leaked into a code",
+                    c
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn generated_codes_are_distinct_in_practice() {
+        // With ~44 bits of entropy, 1000 draws should be unique.
+        use std::collections::HashSet;
+        let mut seen = HashSet::new();
+        for _ in 0..1_000 {
+            assert!(seen.insert(generate_code_string()), "unexpected collision");
+        }
+    }
+
+    #[tokio::test]
+    async fn consume_for_bind_is_single_use() {
+        let mgr = SupportCodeManager::new();
+        let code = mgr
+            .create_code(CreateCodeRequest {
+                technician_id: None,
+                technician_name: Some("tech".to_string()),
+            })
+            .await
+            .code;
+
+        // First bind consumes the code.
+        assert!(
+            mgr.consume_for_bind(&code, Some("agent".into()), Some("a1".into()))
+                .await
+        );
+        // Second presenter is rejected — single use.
+        assert!(
+            !mgr.consume_for_bind(&code, Some("agent2".into()), Some("a2".into()))
+                .await
+        );
+    }
+
+    #[tokio::test]
+    async fn consume_for_bind_rejects_unknown_code() {
+        let mgr = SupportCodeManager::new();
+        assert!(!mgr.consume_for_bind("NOP-E00-000", None, None).await);
+    }
+
+    #[tokio::test]
+    async fn consume_for_bind_rejects_cancelled_code() {
+        let mgr = SupportCodeManager::new();
+        let code = mgr
+            .create_code(CreateCodeRequest {
+                technician_id: None,
+                technician_name: Some("tech".to_string()),
+            })
+            .await
+            .code;
+        assert!(mgr.cancel_code(&code).await);
+        // A cancelled code is not Pending → cannot be consumed.
+        assert!(!mgr.consume_for_bind(&code, None, None).await);
+    }
+
+    #[tokio::test]
+    async fn preview_validate_does_not_consume() {
+        let mgr = SupportCodeManager::new();
+        let code = mgr
+            .create_code(CreateCodeRequest {
+                technician_id: None,
+                technician_name: Some("tech".to_string()),
+            })
+            .await
+            .code;
+
+        // Previewing the code many times must not consume it...
+        for _ in 0..5 {
+            assert!(mgr.validate_code(&code).await.valid);
+        }
+        // ...so a first real bind still succeeds.
+        assert!(mgr.consume_for_bind(&code, None, None).await);
+    }
+}

specs/v2-secure-session-core/plan.md

@@ -1,7 +1,8 @@
 # v2 Secure Session Core — Implementation Plan
 
 > Spec created: 2026-05-29
-> Status: in progress — Tasks 1-3 DONE 2026-05-29 (Task 3 code-reviewed APPROVED). Viewer-token authz
+> Status: in progress — Tasks 1-4 IMPLEMENTED 2026-05-29 (Task 4 self-reviewed, pending Code Review;
+> Tasks 1-3 code-reviewed APPROVED). Task 4 completes the KEYSTONE (secure auth/session core). Viewer-token authz
 > STRENGTH split IMPLEMENTED 2026-05-29 (self-reviewed; no Rust toolchain on this machine — not yet
 > `cargo check`-verified; pending Code Review). This was the REQUIRED Phase-1-exit follow-up: the gate
 > previously used `view` (held by EVERY default role incl. `viewer`) but a viewer token granted input
@@ -179,7 +180,59 @@ Reference: audit Pass E (`reports/2026-05-29-gc-audit.md` §"Pass 5"); `relay/mo
 
 ---
 
-## Task 4 (KEYSTONE): Working rate limiting + single-use support codes
+## Task 4 (KEYSTONE) [IMPLEMENTED 2026-05-29 — self-reviewed; no Rust toolchain on this machine, not yet `cargo check`-verified; pending Code Review]: Working rate limiting + single-use support codes
+
+> [IMPLEMENTED] Closes the keystone (Tasks 1–4). Three parts:
+>
+> A. RATE LIMITING — replaced the non-compiling tower_governor layer with a small
+>    self-contained in-memory limiter (`middleware/rate_limit.rs`): a per-IP
+>    fixed-window `RateLimiter` (`Mutex<HashMap<IpAddr, Window>>`, no new dep) +
+>    a per-IP consecutive-failure `FailureLockout`, bundled as `RateLimitState`
+>    in `AppState`. Keyed by `ConnectInfo<SocketAddr>` IP (same source the relay
+>    uses); X-Forwarded-For intentionally NOT trusted (proxy-spoofable). 429 with
+>    the standard error envelope on limit. Re-enabled `pub mod rate_limit`. Wired
+>    per-route via `route_layer(from_fn_with_state(...))` onto `POST
+>    /api/auth/login` (8/min/IP), `POST /api/auth/change-password` (5/min/IP), and
+>    `GET /api/codes/:code/validate` (15/min/IP). Named consts for every limit.
+>    LOCKOUT: after 10 consecutive failed code-validations from an IP, that IP is
+>    locked out 15 min; the validate handler reports success/failure into the
+>    lockout, the middleware enforces it BEFORE the handler runs. Unit tests cover
+>    window allow/block/reset, per-IP isolation, and lockout trip/reset/expire
+>    (clock injected, no sleeps).
+>
+> B. SINGLE-USE CODES — the agent bind path now CONSUMES the code atomically on
+>    first bind. In-memory: new `SupportCodeManager::consume_for_bind` accepts
+>    ONLY a `Pending` code and flips it to `Connected` under the write lock (a 2nd
+>    presenter loses the race → rejected). This replaces the v1 pre-upgrade check
+>    that accepted `pending` OR `connected` (the reusable-code HIGH). DB: new
+>    `db::support_codes::consume_code_for_bind` — a single conditional UPDATE
+>    `... SET consumed_at = NOW(), status='connected' WHERE code=$1 AND consumed_at
+>    IS NULL AND status='pending' AND (expires_at IS NULL OR expires_at > NOW())
+>    RETURNING id`; zero rows ⇒ not consumable. The in-memory consume is
+>    AUTHORITATIVE (the live source of truth); the DB UPDATE is a durable/audit
+>    mirror applied best-effort after it (a missing DB row does not veto a bind the
+>    in-memory layer admitted). To make the durable record meaningful, the portal
+>    `create_code` handler now also inserts the code into `connect_support_codes`.
+>    Validate/preview path is UNCHANGED and explicitly does NOT consume (test
+>    `preview_validate_does_not_consume`).
+>
+> C. WIDER CODE — replaced the 6-digit numeric generator with a grouped
+>    base32-style code `XXX-XXX-XXX` (9 symbols over a 31-char UNAMBIGUOUS alphabet
+>    excluding 0/O/1/I/L ≈ 44.6 bits), CSPRNG-backed (`OsRng`, rejection sampling
+>    to avoid modulo bias). The new code (11 chars incl. hyphens) does NOT fit the
+>    `VARCHAR(10)` column from migration 001, so migration `006_widen_support_code.sql`
+>    widens `connect_support_codes.code` AND `connect_sessions.support_code` to
+>    TEXT (idempotent). Unit tests cover shape, charset (no ambiguous chars), and
+>    practical uniqueness.
+>
+> DEPS: none added; `tower_governor` REMOVED from Cargo.toml (it never compiled).
+> No code/secret/support-code value logged on any path. Runtime `sqlx::query`.
+> Files: `server/src/middleware/rate_limit.rs` (rebuilt), `server/src/middleware/mod.rs`,
+> `server/src/main.rs` (AppState field + 3 route wirings + create_code DB insert +
+> validate handler lockout feed), `server/src/support_codes.rs` (new generator +
+> `consume_for_bind` + tests), `server/src/db/support_codes.rs`
+> (`consume_code_for_bind`), `server/src/relay/mod.rs` (atomic consume on bind),
+> `server/migrations/006_widen_support_code.sql` [new], `server/Cargo.toml`.
 
 Files touched: `server/src/middleware/rate_limit.rs` (rebuild — v1 is non-compiling),
 `server/src/middleware/mod.rs`, `server/src/api/auth.rs` (login), `server/src/api/` (code validate),