feat: harden auth, shutdown, and session bundle (0.35.0)

Three features bundled into one release:

- rate-limit /auth/login, /register, /me/password (token bucket,
  5 req/sec sustained with 10-request burst by default; 429 +
  Retry-After header on hit; tracing::warn! per hit so operators
  see attack patterns; AUTH_RATE_PER_SEC / AUTH_RATE_BURST env knobs)
- handle SIGTERM for graceful container stops (replaces bare
  ctrl_c() with a select over ctrl_c + SignalKind::terminate() so
  docker compose stop runs the daemon shutdown path instead of
  letting Chromium leak past SIGKILL)
- clear session.user on 401 from any API call (setOn401Hook in
  api/client.ts, registered from session.svelte.ts gated on
  $app/environment::browser so the SSR bundle never installs it;
  fixes "logged in but no bookmarks/collections" mid-session
  expiry state)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

backend/src/api/auth.rs

@@ -82,6 +82,7 @@ async fn register(
     jar: CookieJar,
     Json(input): Json<Credentials>,
 ) -> AppResult<impl IntoResponse> {
+    check_auth_rate_limit(&state, "register")?;
     let username = input.username.trim();
     validate_username(username)?;
     validate_password(&input.password)?;
@@ -97,6 +98,7 @@ async fn login(
     jar: CookieJar,
     Json(input): Json<Credentials>,
 ) -> AppResult<impl IntoResponse> {
+    check_auth_rate_limit(&state, "login")?;
     let username = input.username.trim();
     if username.is_empty() || input.password.is_empty() {
         return Err(AppError::InvalidInput(
@@ -172,6 +174,7 @@ async fn change_password(
     jar: CookieJar,
     Json(input): Json<ChangePassword>,
 ) -> AppResult<impl IntoResponse> {
+    check_auth_rate_limit(&state, "change_password")?;
     if !verify_password(&input.current_password, &user.password_hash) {
         return Err(AppError::Unauthenticated);
     }
@@ -332,6 +335,33 @@ fn build_expired_cookie(cfg: &AuthConfig) -> Cookie<'static> {
     builder.build()
 }
 
+/// Consume one token from the shared auth rate limiter. Called at the
+/// start of `register`, `login`, and `change_password` so credential
+/// stuffing / spraying / username-probe loops are throttled by the
+/// configured budget (default 5/sec with a 10-request burst).
+///
+/// All three endpoints share one bucket — they all expose the same
+/// argon2-verify-or-create work and the same enumeration channels, so
+/// any one of them in a tight loop should trip the limit. `endpoint`
+/// is included in the rate-limit-hit log line so operators can tell
+/// which endpoint is being probed.
+fn check_auth_rate_limit(state: &AppState, endpoint: &'static str) -> AppResult<()> {
+    use crate::auth::rate_limit::AcquireResult;
+    match state.auth_limiter.try_acquire() {
+        AcquireResult::Allowed => Ok(()),
+        AcquireResult::Denied { retry_after_secs } => {
+            tracing::warn!(
+                endpoint,
+                retry_after_secs,
+                "auth rate limit hit; returning 429"
+            );
+            Err(AppError::TooManyRequests {
+                retry_after_secs: Some(retry_after_secs),
+            })
+        }
+    }
+}
+
 fn validate_username(u: &str) -> AppResult<()> {
     if u.is_empty() {
         return Err(AppError::InvalidInput("username is required".into()));

backend/src/app.rs

@@ -12,6 +12,7 @@ use tokio_util::sync::CancellationToken;
 use tower_http::cors::{AllowOrigin, CorsLayer};
 use tower_http::trace::TraceLayer;
 
+use crate::auth::rate_limit::AuthRateLimiter;
 use crate::config::{AuthConfig, Config, CrawlerConfig, CrawlerModePref, UploadConfig};
 use crate::crawler::browser_manager::{self, BrowserManager};
 use crate::crawler::content::{self, SyncOutcome};
@@ -31,6 +32,10 @@ pub struct AppState {
     pub storage: Arc<dyn Storage>,
     pub auth: AuthConfig,
     pub upload: UploadConfig,
+    /// Shared rate limiter guarding the `/auth/*` mutation endpoints.
+    /// One instance per AppState so tests stay isolated across the
+    /// same process.
+    pub auth_limiter: Arc<AuthRateLimiter>,
 }
 
 /// Bundle returned by [`build`]. The router is what `axum::serve` consumes;
@@ -65,11 +70,13 @@ pub async fn build(config: Config) -> anyhow::Result<AppHandle> {
         None
     };
 
+    let auth_limiter = Arc::new(AuthRateLimiter::new(config.auth.rate_limit));
     let state = AppState {
         db,
         storage,
         auth: config.auth.clone(),
         upload: config.upload.clone(),
+        auth_limiter,
     };
     let router = router(state).layer(cors_layer(&config.cors_allowed_origins));
     Ok(AppHandle { router, daemon })

backend/src/auth/mod.rs

@@ -7,4 +7,5 @@
 
 pub mod extractor;
 pub mod password;
+pub mod rate_limit;
 pub mod token;

backend/src/auth/rate_limit.rs

@@ -0,0 +1,179 @@
+//! Per-process token-bucket rate limiter for the auth endpoints.
+//!
+//! Protects `/auth/login`, `/auth/register`, and `/auth/me/password`
+//! from credential stuffing / password spraying / username probing.
+//!
+//! The current deploy puts SvelteKit's hooks.server.ts proxy in front
+//! of axum without forwarding the original client IP (no
+//! `X-Forwarded-For`), so per-IP buckets would all collapse to the
+//! proxy container's address. Until the proxy learns to forward the
+//! peer address, a single global bucket gives equivalent protection
+//! against mass-attack patterns and trades a small DoS surface
+//! (legitimate users sharing the limit) for simplicity.
+//!
+//! Each `AppState` carries its own [`AuthRateLimiter`] instance, so
+//! tests run in isolated buckets and won't bleed across `#[sqlx::test]`
+//! cases that share a process.
+
+use std::sync::Mutex;
+use std::time::Instant;
+
+/// Tunable limits. `per_sec == 0` disables the limiter — used by the
+/// test harness and by anyone who wants to opt out via env config.
+#[derive(Clone, Copy, Debug)]
+pub struct RateLimitConfig {
+    pub per_sec: u32,
+    pub burst: u32,
+}
+
+impl Default for RateLimitConfig {
+    /// Disabled by default. The production `AuthConfig::from_env`
+    /// overrides to a real limit; the test harness keeps the default
+    /// so existing tests don't flake against shared buckets.
+    fn default() -> Self {
+        Self {
+            per_sec: 0,
+            burst: 0,
+        }
+    }
+}
+
+/// Production defaults: 5 requests/sec sustained, 10-request burst.
+/// Tight enough to make brute force impractical, loose enough that a
+/// real user mistyping their password three times in a row doesn't
+/// hit it.
+pub const PRODUCTION_PER_SEC: u32 = 5;
+pub const PRODUCTION_BURST: u32 = 10;
+
+struct Bucket {
+    tokens: f64,
+    last_refill: Instant,
+}
+
+/// Outcome of [`AuthRateLimiter::try_acquire`]. When `Denied`, the
+/// caller can use `retry_after_secs` for a `Retry-After: N` header
+/// (RFC 6585 §4) so well-behaved clients back off correctly rather
+/// than retrying in a tight loop.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AcquireResult {
+    Allowed,
+    Denied { retry_after_secs: u64 },
+}
+
+/// Single-bucket token-bucket limiter. `try_acquire` is cheap (one
+/// mutex acquire, no allocations) so the auth path doesn't pay a real
+/// cost for the check.
+pub struct AuthRateLimiter {
+    cfg: RateLimitConfig,
+    bucket: Mutex<Bucket>,
+}
+
+impl AuthRateLimiter {
+    pub fn new(cfg: RateLimitConfig) -> Self {
+        Self {
+            cfg,
+            bucket: Mutex::new(Bucket {
+                tokens: cfg.burst as f64,
+                last_refill: Instant::now(),
+            }),
+        }
+    }
+
+    /// Consume one token if available. Returns `Denied` with a
+    /// rounded-up seconds-until-refill so the caller can emit a
+    /// `Retry-After` header.
+    pub fn try_acquire(&self) -> AcquireResult {
+        if self.cfg.per_sec == 0 {
+            return AcquireResult::Allowed;
+        }
+        let now = Instant::now();
+        let mut bucket = self.bucket.lock().expect("rate limiter mutex poisoned");
+        let elapsed = now.duration_since(bucket.last_refill).as_secs_f64();
+        bucket.tokens =
+            (bucket.tokens + elapsed * f64::from(self.cfg.per_sec)).min(f64::from(self.cfg.burst));
+        bucket.last_refill = now;
+        if bucket.tokens >= 1.0 {
+            bucket.tokens -= 1.0;
+            AcquireResult::Allowed
+        } else {
+            // ceil((1 - tokens) / per_sec), minimum 1 — a `Retry-After: 0`
+            // would tell clients to retry immediately, which is what we're
+            // actively trying to discourage.
+            let deficit = 1.0 - bucket.tokens;
+            let wait_secs = (deficit / f64::from(self.cfg.per_sec)).ceil() as u64;
+            AcquireResult::Denied {
+                retry_after_secs: wait_secs.max(1),
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn disabled_limiter_always_allows() {
+        let rl = AuthRateLimiter::new(RateLimitConfig {
+            per_sec: 0,
+            burst: 0,
+        });
+        for _ in 0..1000 {
+            assert_eq!(rl.try_acquire(), AcquireResult::Allowed);
+        }
+    }
+
+    #[test]
+    fn burst_lets_through_initial_window_then_blocks() {
+        // 0 refill, burst 3 → first three pass, fourth blocks.
+        let rl = AuthRateLimiter::new(RateLimitConfig {
+            per_sec: 1,
+            burst: 3,
+        });
+        assert_eq!(rl.try_acquire(), AcquireResult::Allowed);
+        assert_eq!(rl.try_acquire(), AcquireResult::Allowed);
+        assert_eq!(rl.try_acquire(), AcquireResult::Allowed);
+        match rl.try_acquire() {
+            AcquireResult::Denied { retry_after_secs } => {
+                // Bucket is at ~0 tokens, refill rate 1/sec → ~1s wait.
+                assert!(
+                    retry_after_secs >= 1,
+                    "retry_after must be at least 1s, got {retry_after_secs}"
+                );
+            }
+            AcquireResult::Allowed => panic!("fourth request must be denied"),
+        }
+    }
+
+    #[test]
+    fn tokens_refill_over_time() {
+        // 10/sec → after ~120ms we should have at least one token back.
+        let rl = AuthRateLimiter::new(RateLimitConfig {
+            per_sec: 10,
+            burst: 1,
+        });
+        assert_eq!(rl.try_acquire(), AcquireResult::Allowed);
+        assert!(matches!(rl.try_acquire(), AcquireResult::Denied { .. }));
+        std::thread::sleep(std::time::Duration::from_millis(150));
+        assert_eq!(
+            rl.try_acquire(),
+            AcquireResult::Allowed,
+            "token should have refilled"
+        );
+    }
+
+    #[test]
+    fn retry_after_scales_inversely_with_refill_rate() {
+        // 1/sec → wait ~1s after burst exhausted.
+        // 10/sec → wait <1s, but we clamp to a minimum of 1s.
+        let slow = AuthRateLimiter::new(RateLimitConfig {
+            per_sec: 1,
+            burst: 1,
+        });
+        slow.try_acquire();
+        match slow.try_acquire() {
+            AcquireResult::Denied { retry_after_secs } => assert_eq!(retry_after_secs, 1),
+            _ => panic!("expected Denied"),
+        }
+    }
+}

backend/src/config.rs

@@ -22,6 +22,7 @@ pub struct AuthConfig {
     pub cookie_secure: bool,
     pub cookie_domain: Option<String>,
     pub session_ttl_days: i64,
+    pub rate_limit: crate::auth::rate_limit::RateLimitConfig,
 }
 
 impl Default for AuthConfig {
@@ -30,6 +31,11 @@ impl Default for AuthConfig {
             cookie_secure: true,
             cookie_domain: None,
             session_ttl_days: 30,
+            // Disabled by default so the test harness inherits a
+            // non-throttling limiter. Production `from_env` overrides
+            // to the [`PRODUCTION_PER_SEC`]/[`PRODUCTION_BURST`]
+            // defaults.
+            rate_limit: crate::auth::rate_limit::RateLimitConfig::default(),
         }
     }
 }
@@ -145,6 +151,16 @@ impl Config {
                     .ok()
                     .filter(|s| !s.is_empty()),
                 session_ttl_days: env_i64("SESSION_TTL_DAYS", 30),
+                rate_limit: crate::auth::rate_limit::RateLimitConfig {
+                    per_sec: env_u64(
+                        "AUTH_RATE_PER_SEC",
+                        crate::auth::rate_limit::PRODUCTION_PER_SEC.into(),
+                    ) as u32,
+                    burst: env_u64(
+                        "AUTH_RATE_BURST",
+                        crate::auth::rate_limit::PRODUCTION_BURST.into(),
+                    ) as u32,
+                },
             },
             upload: UploadConfig {
                 max_request_bytes: env_usize("MAX_REQUEST_BYTES", 200 * 1024 * 1024),

backend/src/error.rs

@@ -21,6 +21,11 @@ pub enum AppError {
     PayloadTooLarge(String),
     #[error("unsupported media type: {0}")]
     UnsupportedMediaType(String),
+    /// 429 with an optional `Retry-After` header value (in seconds).
+    #[error("too many requests")]
+    TooManyRequests {
+        retry_after_secs: Option<u64>,
+    },
     /// Semantic per-field validation failure. `details` is rendered into the
     /// envelope so the client can highlight the bad field(s).
     #[error("validation failed")]
@@ -51,6 +56,7 @@ impl AppError {
             AppError::Conflict(_) => "conflict",
             AppError::PayloadTooLarge(_) => "payload_too_large",
             AppError::UnsupportedMediaType(_) => "unsupported_media_type",
+            AppError::TooManyRequests { .. } => "too_many_requests",
             AppError::ValidationFailed { .. } => "validation_failed",
             AppError::Database(sqlx::Error::RowNotFound) => "not_found",
             AppError::Database(_) => "internal_error",
@@ -79,6 +85,31 @@ impl IntoResponse for AppError {
             AppError::UnsupportedMediaType(msg) => {
                 (StatusCode::UNSUPPORTED_MEDIA_TYPE, msg.clone(), None)
             }
+            AppError::TooManyRequests { retry_after_secs } => {
+                // Emit `Retry-After: N` (RFC 6585 §4) so a well-behaved
+                // client can back off correctly. Done by building the
+                // response by hand below — the `(status, headers,
+                // body)` tuple shape doesn't fit the standard
+                // `(status, body)` IntoResponse path for the other
+                // variants.
+                let body = json!({
+                    "error": {
+                        "code": code,
+                        "message": "too many requests; slow down",
+                    }
+                });
+                let mut resp = (StatusCode::TOO_MANY_REQUESTS, Json(body)).into_response();
+                if let Some(secs) = retry_after_secs {
+                    // `HeaderValue: From<u64>` skips both the
+                    // intermediate `String` allocation and the
+                    // fallible-by-shape `from_str` path.
+                    resp.headers_mut().insert(
+                        axum::http::header::RETRY_AFTER,
+                        axum::http::HeaderValue::from(*secs),
+                    );
+                }
+                return resp;
+            }
             AppError::ValidationFailed { message, details } => (
                 StatusCode::UNPROCESSABLE_ENTITY,
                 message.clone(),

backend/src/main.rs

@@ -17,10 +17,7 @@ async fn main() -> anyhow::Result<()> {
     tracing::info!(%addr, "mangalord listening");
     let listener = tokio::net::TcpListener::bind(addr).await?;
     axum::serve(listener, router)
-        .with_graceful_shutdown(async {
-            let _ = tokio::signal::ctrl_c().await;
-            tracing::info!("ctrl-c received; shutting down");
-        })
+        .with_graceful_shutdown(shutdown_signal())
         .await?;
 
     // Drain background tasks (crawler daemon) before exiting so Chromium
@@ -30,3 +27,33 @@ async fn main() -> anyhow::Result<()> {
     }
     Ok(())
 }
+
+/// Wait for either Ctrl-C (interactive shell) or SIGTERM (Docker /
+/// Kubernetes / Podman / systemd stop) and log which arrived. Without
+/// the SIGTERM branch, `docker compose stop` runs out its grace period
+/// and skips straight to SIGKILL — the daemon never gets the
+/// `daemon.shutdown().await` path, leaking Chromium.
+async fn shutdown_signal() {
+    use tokio::signal::unix::{signal, SignalKind};
+    let mut sigterm = match signal(SignalKind::terminate()) {
+        Ok(s) => s,
+        Err(e) => {
+            // SignalKind::terminate() is supported on every Unix the
+            // tokio runtime runs on; if registration fails we still
+            // honour Ctrl-C so the process is at least
+            // interactive-shutdownable.
+            tracing::warn!(error = %e, "could not install SIGTERM handler; falling back to ctrl_c only");
+            let _ = tokio::signal::ctrl_c().await;
+            tracing::info!("ctrl-c received; shutting down");
+            return;
+        }
+    };
+    tokio::select! {
+        _ = tokio::signal::ctrl_c() => {
+            tracing::info!("ctrl-c received; shutting down");
+        }
+        _ = sigterm.recv() => {
+            tracing::info!("SIGTERM received; shutting down");
+        }
+    }
+}