feather_reader/

web.rs

//! The axum web layer — server-rendered HTML + a dash of htmx, **no SPA**.
//!
//! This module owns the HTTP surface: [`router`] builds an [`axum::Router`] over
//! the shared [`AppState`], wiring the store, feed, atproto, and config seams into
//! a small set of typography-first, dark-mode-ready views rendered with
//! [`askama`] templates (under `templates/`). Progressive enhancement is a single
//! vendored `htmx` script plus a tiny keyboard handler (`static/keyboard.js`);
//! every interaction also works as a plain HTML form POST, so the reader is fully
//! usable with JavaScript disabled.
//!
//! ## HTTP surface
//!
//! * `GET  /health` — liveness + version, as `text/plain`.
//! * `GET  /` — the reader: a folders/feeds sidebar (from the PDS records layer)
//!   plus the main article list. Query params pick the scope (`?feed=…` /
//!   `?folder=…` / all) and the view (`?view=unread|all|starred`).
//! * `GET  /entries/{id}` — the clean, distraction-free reader for one entry,
//!   with prev/next within the current list.
//! * `POST /entries/{id}/read` — mark an entry read/unread (htmx row swap).
//! * `POST /entries/{id}/star` — star/unstar; writes a
//!   `community.lexicon.rss.saved` record to the user's PDS.
//! * `POST /read-all` — mark-all-read (per feed via `?feed=…`, else everything).
//! * `POST /subscriptions` — subscribe by URL (autodiscover → PDS record).
//! * `POST /subscriptions/{rkey}/delete` — unsubscribe (delete the PDS record).
//! * `POST /subscriptions/{rkey}/rename` — retitle / move a feed to a folder.
//! * `POST /folders` — create a folder record.
//! * `POST /folders/{rkey}/rename` — rename a folder record.
//! * `POST /folders/{rkey}/delete` — delete a folder record.
//! * `POST /opml` — OPML import (multipart upload *or* pasted textarea) → bulk
//!   subscription records in the PDS.
//! * `GET  /opml/export` — OPML export (records → a downloadable document).
//! * `GET /login` + `POST /login` + `/oauth/callback` + `/logout` — the atproto
//!   OAuth sign-in flow (routed through the sidecar).
//! * `GET /claim?t=<token>` — the follow→invite bot's claim link: an opaque token
//!   reserving a pre-minted invite code; behaves like a successful `/beta/redeem`
//!   (sets the reserving cookie → `/login`).
//! * `POST /bot/claims` — headless, shared-secret (`X-Bot-Secret`) mint of a claim
//!   code + token/url for the bot to post. Cap-aware (409 when full).
//!
//! ## Identity — a cookie-resolved atproto session
//!
//! Per-request identity comes from a **signed session cookie** (`fr_session`)
//! keyed by the logged-in DID, set by [`oauth_callback`] and read by
//! [`current_session`] / [`current_did`]. For local runs without the sidecar,
//! [`Config::dev_did`] (env `FEATHERREADER_DEV_DID`) supplies a fallback identity.
//! All PDS writes route through the [`crate::atproto::SidecarClient`]; a live-PDS
//! write needs a real OAuth session, but the full write path is built and unit-
//! tested to the sidecar boundary.

use std::collections::HashMap;
use std::net::IpAddr;
use std::sync::Mutex;
use std::time::{Duration, Instant};

use askama::Template;
use axum::{
    extract::{ConnectInfo, DefaultBodyLimit, Multipart, Path, Query, State},
    http::{header, HeaderMap, StatusCode},
    middleware::{self, Next},
    response::{Html, IntoResponse, Redirect, Response},
    routing::{get, post},
    Form, Router,
};
use serde::Deserialize;
use std::net::SocketAddr;
use tower_http::services::{ServeDir, ServeFile};
use tower_http::set_header::SetResponseHeaderLayer;
use tower_http::trace::TraceLayer;
use tracing::{info, warn};

use crate::config::Config;
use crate::lexicon::{self, Folder, Saved, Subscription};
use crate::safe_link::SafeLink;
use crate::{feed, store, AppState, Session, VERSION};

// The OPML import/export module lives at `src/opml.rs` but isn't declared in the
// crate root (`lib.rs`), which is outside this phase's edit surface. Wire it in
// here via an explicit path so the reader's OPML routes can use the canonical
// `parse_opml` / `to_opml` without duplicating that logic.
#[path = "opml.rs"]
mod opml;

/// The name of the signed session cookie.
const SESSION_COOKIE: &str = "fr_session";

/// The name of the short-lived signed **invite** cookie.
///
/// Set by `POST /beta/redeem` on a valid, capacity-ok code and consumed by the
/// OAuth callback. It reserves *intent* to redeem a specific code before the
/// visitor ever starts the OAuth handshake, so a non-invited visitor can't burn
/// a sidecar handshake (pre-handshake gate). It carries the invite code, HMAC-
/// signed with the same key as the session cookie.
const INVITE_COOKIE: &str = "fr_invite";

/// Browser-binding cookie for an in-flight OAuth login (Rust backend only).
///
/// `state` alone cannot stop a login CSRF: it lives in a server-global table, so
/// a stolen `state` replayed from ANOTHER browser matches just as well as from
/// the one that started the flow. This cookie is what makes the callback
/// browser-specific — the pending row stores only its hash, and a callback that
/// cannot present it is refused.
const OAUTH_BINDING_COOKIE: &str = "fr_oauth";

/// How long an in-flight login may sit, matching the pending row's own TTL.
const OAUTH_BINDING_MAX_AGE_SECS: i64 = 600;

/// TTL (seconds) for a minted invite code and for the reserving invite cookie.
/// Short enough that a reserved-but-unclaimed seat frees quickly.
const INVITE_TTL_SECS: i64 = 1800;

/// The canonical AGPL-3.0 source repository — surfaced in the footer, the
/// sign-in pitch, and `/about`.
const REPO_URL: &str = "https://github.com/justin-stanley/feather-reader";

/// The tip / support link (cloud plan public-experiment UI).
const KOFI_URL: &str = "https://ko-fi.com/justinstanley";

/// The published crate on crates.io — surfaced on the signed-out landing page.
const CRATES_URL: &str = "https://crates.io/crates/feather-reader";

/// The Content-Security-Policy applied to every response.
///
/// Tuned to keep the app fully working while neutralising injected script:
/// * `default-src 'self'` — same-origin baseline.
/// * `script-src 'self'` — only our vendored `htmx.min.js` + `keyboard.js` from
///   `/static`; **no** `'unsafe-inline'`, so an injected `<script>` or a
///   `javascript:` href (F4) cannot execute. (The design's templates carry no
///   inline event handlers — every control is wired in `keyboard.js`.)
/// * `style-src 'self' 'unsafe-inline'` — the linked stylesheet plus the small
///   inline styles htmx toggles for its request indicators.
/// * `img-src 'self' https: data:` — feed content routinely embeds remote
///   images; allow https + data URIs but not other schemes.
/// * `form-action 'self'`, `base-uri 'self'`, `frame-ancestors 'none'` — lock
///   down form posts, `<base>` hijacking, and clickjacking.
/// * `object-src 'none'` — no plugins.
const CONTENT_SECURITY_POLICY: &str = "default-src 'self'; \
     script-src 'self'; \
     style-src 'self' 'unsafe-inline'; \
     img-src 'self' https: data:; \
     font-src 'self'; \
     connect-src 'self'; \
     form-action 'self'; \
     base-uri 'self'; \
     frame-ancestors 'none'; \
     object-src 'none'";

/// The resolved identity for the current request.
///
/// `did` is the primary key for all per-user local state; `handle` is display
/// only; `sid` is the opaque server-side session id the cookie carried (needed
/// so logout can revoke exactly this session). Sourced from the signed cookie
/// (real login) or, if none, the configured dev DID fallback.
#[derive(Clone, Debug)]
struct CurrentUser {
    did: String,
    handle: Option<String>,
    /// The opaque session id, if this identity came from a real cookie session
    /// (absent for the dev-DID fallback, which has no server-side session row).
    sid: Option<String>,
}

/// Resolve the current request's session from the signed cookie, falling back to
/// the configured dev DID (env `FEATHERREADER_DEV_DID`) for local runs.
///
/// The cookie carries an opaque server-minted session id (not the DID). We
/// verify its HMAC, look the id up in the registry, and — crucially —
/// **re-check the DID against the closed-beta gate on every request**
/// ([`store::has_beta_access`]), not just at the OAuth callback, so revoking a
/// DID's beta seat takes effect immediately for already-issued cookies. (The
/// gate replaced the old static `ALLOWED_DIDS` check; `ALLOWED_DIDS` remains the
/// admin-bootstrap seed, granted a seat at startup via `ensure_seed`.)
async fn current_session(state: &AppState, headers: &HeaderMap) -> Option<CurrentUser> {
    if let Some(sid) = cookie::verify_session(headers, &state.config.cookie_secret) {
        if let Some(session) = state.sessions.get(&sid) {
            if store::has_beta_access(&state.db, &session.did)
                .await
                .unwrap_or(false)
            {
                return Some(CurrentUser {
                    did: session.did,
                    handle: session.handle,
                    sid: Some(sid),
                });
            }
            // DID no longer holds a beta seat: treat as logged out (and drop the
            // stale server-side session so the dead cookie can't linger).
            state.sessions.remove(&sid);
        }
    }
    // No valid cookie: dev fallback only if explicitly configured *and* still
    // inside the beta gate (seeded via ensure_seed / a redeemed code).
    if let Some(did) = state.config.dev_did.clone() {
        if store::has_beta_access(&state.db, &did)
            .await
            .unwrap_or(false)
        {
            return Some(CurrentUser {
                did,
                handle: None,
                sid: None,
            });
        }
    }
    None
}

/// The current request's DID, or `None` when logged out (no cookie, no dev DID).
async fn current_did(state: &AppState, headers: &HeaderMap) -> Option<String> {
    current_session(state, headers).await.map(|u| u.did)
}

/// Build the application router over shared [`AppState`].
///
/// Wires the reader routes, the health check, and the `/static` asset mount
/// (the stylesheet, vendored htmx, and the keyboard handler, served from
/// `static/` via [`ServeDir`]). A [`TraceLayer`] gives per-request tracing.
pub fn router(state: AppState) -> Router {
    // The shared per-IP rate limiter for the abuse-prone paths (login, redeem,
    // and the write endpoints). One instance is cloned into the state closure of
    // the `rate_limit` middleware.
    let limiter = RateLimiter::shared();
    // The trusted client-IP source for the limiter (a proxy header the operator
    // controls, or the socket peer when unset). Bundled with the limiter so the
    // middleware derives a spoof-resistant IP.
    let rl_state = RateLimitState {
        limiter,
        trusted_header: state.config.trusted_ip_header.clone(),
    };

    Router::new()
        .route("/health", get(health))
        .route("/about", get(about))
        .route("/stats", get(stats))
        .route("/privacy", get(privacy))
        .route("/terms", get(terms))
        .route("/manage", get(manage))
        .route("/", get(index))
        .route("/entries/{id}", get(entry_view))
        .route("/entries/{id}/read", post(mark_read))
        .route("/entries/{id}/star", post(toggle_star))
        .route("/saved/{rkey}/delete", post(unsave_record))
        .route("/read-all", post(mark_all_read))
        .route("/subscriptions", post(add_subscription))
        .route("/subscriptions/{rkey}/delete", post(delete_subscription))
        .route("/subscriptions/{rkey}/rename", post(rename_subscription))
        .route("/folders", post(create_folder))
        .route("/folders/{rkey}/rename", post(rename_folder))
        .route("/folders/{rkey}/delete", post(delete_folder))
        // OPML import takes untrusted uploads: cap the body so a huge upload
        // can't OOM (residual body-cap), on top of the streamed feed-fetch cap.
        .route(
            "/opml",
            post(import_opml).layer(DefaultBodyLimit::max(OPML_BODY_LIMIT)),
        )
        .route("/opml/export", get(export_opml))
        .route("/login", get(login_form).post(login_submit))
        .route(
            "/beta/redeem",
            get(beta_redeem_form).post(beta_redeem_submit),
        )
        // The follow→invite bot's claim link: a public skeet points a new
        // follower here with an opaque token that reserves a pre-minted code.
        .route("/claim", get(claim))
        // Headless bot mint endpoint (shared-secret, not OAuth). Mints a claim
        // code + returns its token/url for the bot to post.
        .route("/bot/claims", post(bot_mint_claim))
        .route("/admin/invites", post(admin_mint_invites))
        .route("/admin/metrics", get(admin_metrics))
        .route("/oauth/client-metadata.json", get(oauth_client_metadata))
        .route("/oauth/jwks.json", get(oauth_jwks))
        .route("/account/delete", post(account_delete))
        .route("/oauth/callback", get(oauth_callback))
        .route("/logout", post(logout))
        .nest_service("/static", ServeDir::new("static"))
        // Browsers (and some feed clients) request /favicon.ico at the root
        // regardless of the <link rel="icon"> tags; serve the same icon that
        // lives under /static so the bare path stops 404-ing.
        .route_service("/favicon.ico", ServeFile::new("static/favicon.ico"))
        // Cache-Control (viral/CDN plan): `public, max-age=300` on the cacheable
        // logged-out landing + static assets, `no-store` on anything that
        // rendered a session's private view. Runs *inside* the security layers so
        // the CSP/nosniff/frame headers are untouched.
        .layer(middleware::from_fn(cache_control))
        // Per-IP rate limit on the abuse-prone paths (429 over the limit). Runs
        // as a middleware so it sees the matched path + the peer IP.
        .layer(middleware::from_fn_with_state(rl_state, rate_limit))
        .layer(TraceLayer::new_for_http())
        // Baseline security headers on *every* response (F4). The CSP is the
        // backstop that neutralises any XSS that slips past sanitization; the
        // others harden sniffing, framing, and referrer leakage.
        .layer(static_header_layer(
            "content-security-policy",
            CONTENT_SECURITY_POLICY,
        ))
        .layer(static_header_layer("x-content-type-options", "nosniff"))
        .layer(static_header_layer(
            "referrer-policy",
            "strict-origin-when-cross-origin",
        ))
        .layer(static_header_layer("x-frame-options", "DENY"))
        .with_state(state)
}

/// Body-size ceiling for the OPML import upload: **1 MiB, deliberately below
/// axum's 2 MiB default.**
///
/// The value used to BE the framework default, which made the route's own
/// `DefaultBodyLimit` layer a no-op: removing the layer changed nothing, so
/// nothing could test it, and the ceiling this route wanted was whatever the
/// framework happened to pick. Sized to this route instead — one outline is
/// ~92 bytes, so 1 MiB carries ~11 000 of them against a per-DID cap
/// (`max_subs_per_did`, default 500) the import trims to anyway. Anything
/// larger is not a subscription list.
///
/// Being strictly tighter than the default is what makes the layer both real
/// and pinnable: `opml_import_over_the_route_cap_is_refused_below_the_framework_default`
/// uploads a payload that only this limit refuses.
const OPML_BODY_LIMIT: usize = 1024 * 1024;

/// axum's own `DefaultBodyLimit` (2 MiB as of axum 0.8), for the test that
/// uploads a payload between the two ceilings.
///
/// **What matters is only that it EXCEEDS [`OPML_BODY_LIMIT`]**, not that this
/// number is exact — axum does not export it, so it cannot be imported. The
/// exceeding is what the test's mutation demonstrates: with the route's layer
/// removed, a payload of this size is accepted. If axum ever lowers its
/// default below ours, that mutation stops failing and the compile-time
/// assertion below is the thing to revisit.
#[cfg(test)]
const AXUM_DEFAULT_BODY_LIMIT: usize = 2 * 1024 * 1024;

/// The route's cap must stay strictly tighter than the framework's, or its
/// layer is a no-op again. A compile error, not a test failure: this is a
/// property of the two constants, and nothing should be able to build a binary
/// where it is false.
#[cfg(test)]
const _: () = assert!(
    OPML_BODY_LIMIT < AXUM_DEFAULT_BODY_LIMIT,
    "OPML_BODY_LIMIT must be tighter than axum's default, or the route's layer does nothing"
);

/// A response-header layer that sets `name: value` on every response, overriding
/// any existing header of that name. `name`/`value` must be valid static header
/// tokens (they are, for our fixed security headers).
fn static_header_layer(
    name: &'static str,
    value: &'static str,
) -> SetResponseHeaderLayer<header::HeaderValue> {
    SetResponseHeaderLayer::overriding(
        header::HeaderName::from_static(name),
        header::HeaderValue::from_static(value),
    )
}

// ---------------------------------------------------------------------------
// Per-IP rate limiting (token bucket, self-contained — no extra crate)
// ---------------------------------------------------------------------------

/// The abuse-prone paths the rate limiter guards (429 over the limit): the OAuth
/// kick-off and callback, the invite redeem, logout, the mutating write
/// endpoints, and mark-read/star/mark-all. Plain read-only navigation is
/// intentionally *not* limited.
///
/// The criterion is **does this path make an outbound request**, not "does it
/// mutate" — the two diverge, and every miss so far has been on the outbound
/// side. This is an allowlist a new route has to be added to by hand, which is
/// exactly why it has now been missed three times: `/saved/` (fixed), then
/// `/oauth/callback` and `/logout`. The callback was the bad one — it is the
/// only path here reachable with no session at all.
///
/// Known and deliberate gaps: `GET /`, `GET /manage` and `GET /opml/export` each
/// make PDS calls but are ordinary authenticated navigation, and throttling them
/// would degrade normal reading. They are bounded by needing a valid session.
fn is_rate_limited_path(path: &str, method: &axum::http::Method) -> bool {
    use axum::http::Method;
    // `/claim` is a GET (a link the bot posts), but it consumes a reservation and
    // a claim token in a public URL is grabbable, so it MUST be per-IP limited
    // like the other abuse-prone entry points — not just `/login`.
    // `/oauth/callback` is a GET, is UNAUTHENTICATED, and every hit performs a
    // real outbound round-trip — a sidecar `resolve_session` or a full token
    // exchange against a PDS. Anyone could spend one outbound request per hit.
    // It is the only entry point here that needs no session at all.
    if method != Method::POST
        && !(method == Method::GET
            && (path == "/login" || path == "/claim" || path == "/oauth/callback"))
    {
        return false;
    }
    match path {
        // `/logout` and `/oauth/callback` are here because they make outbound
        // calls, not because they mutate: logout revokes at the PDS (up to two
        // round-trips) and the callback exchanges a code. The list is by
        // *network cost*, which is what the limiter is actually for.
        "/login" | "/claim" | "/oauth/callback" | "/logout" | "/beta/redeem" | "/subscriptions"
        | "/opml" | "/read-all" | "/admin/invites" | "/bot/claims" | "/account/delete"
        | "/folders" => true,
        // Every per-record subscription/folder mutation (delete/rename) and the
        // star/mark-read taps make a sidecar/PDS round-trip, so limit them too.
        p => {
            (p.starts_with("/entries/") && (p.ends_with("/read") || p.ends_with("/star")))
                // Unsaving makes a DPoP-signed deleteRecord round-trip to the
                // PDS, which is exactly the reason the neighbours above are
                // limited. It was added as a new route and not added here.
                || p.starts_with("/saved/")
                || p.starts_with("/subscriptions/")
                || p.starts_with("/folders/")
        }
    }
}

/// Middleware state for [`rate_limit`]: the shared limiter plus the trusted
/// client-IP header (if any). Cloned into every request; both fields are cheap.
#[derive(Clone)]
struct RateLimitState {
    limiter: RateLimiter,
    /// The lowercased proxy header the operator trusts for the client IP, or
    /// `None` to trust only the socket peer. See [`client_ip`].
    trusted_header: Option<String>,
}

/// A tiny per-IP token-bucket rate limiter. Each IP gets [`RATE_BURST`] tokens
/// that refill at [`RATE_REFILL_PER_SEC`]/sec; a request costs one token and is
/// rejected (429) when the bucket is empty. Self-contained (no `tower_governor`
/// dependency → no network fetch at build, deterministic offline CI).
#[derive(Clone)]
struct RateLimiter {
    inner: std::sync::Arc<Mutex<RateLimiterState>>,
}

/// The limiter's shared state: the buckets plus when they were last swept.
struct RateLimiterState {
    buckets: HashMap<IpAddr, Bucket>,
    last_sweep: Instant,
}

/// One IP's token bucket: a fractional token count + the last-refill instant.
struct Bucket {
    tokens: f64,
    last: Instant,
}

/// Burst capacity per IP — how many requests can arrive back-to-back.
const RATE_BURST: f64 = 20.0;
/// Steady-state refill rate (tokens/sec) once the burst is spent.
const RATE_REFILL_PER_SEC: f64 = 1.0;
/// Evict idle buckets older than this so the map can't grow unbounded.
const RATE_IDLE_EVICT: Duration = Duration::from_secs(3600);

/// How often the idle sweep may actually run.
///
/// The sweep used to run on EVERY guarded request — an O(n) scan of the whole
/// map to find entries that, by construction, can only age out on an hour
/// boundary. `GET /login` and `GET /claim` are guarded and unauthenticated, so
/// under any volume of distinct source IPs the server spent its single shared
/// core re-walking a map whose contents had not changed. Once a minute is
/// plenty: it bounds bucket lifetime at `RATE_IDLE_EVICT + RATE_SWEEP_EVERY`.
const RATE_SWEEP_EVERY: Duration = Duration::from_secs(60);

/// Most buckets kept. At roughly 100 bytes each this is ~1 MB — a bound, not a
/// target, sized so ordinary traffic never reaches it.
///
/// The idle eviction above was the only bound, and it is a TIME bound, which
/// says nothing about how many distinct IPs can arrive inside one hour.
/// `net.rs` bounds the equivalent structure by count (`MAX_PINNED_CLIENTS`);
/// this one did not.
const MAX_RATE_BUCKETS: usize = 10_000;

/// When the cap is hit, evict down to this fraction of it rather than removing
/// a single entry — so the O(n) eviction happens once per `cap/8` requests
/// instead of once per request while the map sits full.
const RATE_EVICT_DOWN_TO: usize = MAX_RATE_BUCKETS * 7 / 8;

impl RateLimiter {
    /// A fresh, shared limiter (cloned into the middleware state).
    fn shared() -> Self {
        Self {
            inner: std::sync::Arc::new(Mutex::new(RateLimiterState {
                buckets: HashMap::new(),
                last_sweep: Instant::now(),
            })),
        }
    }

    /// Charge one token for `ip`; returns `true` if allowed, `false` if the
    /// bucket is empty (→ 429).
    fn check(&self, ip: IpAddr) -> bool {
        self.check_at(ip, Instant::now())
    }

    /// [`check`](Self::check) with the clock injected, so the sweep and eviction
    /// paths below are reachable in a test without sleeping through an hour.
    fn check_at(&self, ip: IpAddr, now: Instant) -> bool {
        let mut state = match self.inner.lock() {
            Ok(m) => m,
            // A poisoned lock shouldn't take the site down — fail open.
            Err(p) => p.into_inner(),
        };

        // Idle sweep, at most once per `RATE_SWEEP_EVERY`.
        if now.duration_since(state.last_sweep) >= RATE_SWEEP_EVERY {
            state
                .buckets
                .retain(|_, b| now.duration_since(b.last) < RATE_IDLE_EVICT);
            state.last_sweep = now;
        }

        // Hard size bound, independent of the time bound above.
        //
        // Evicting LEAST-RECENTLY-USED is what makes this safe to do at all. An
        // attacker cannot use eviction to clear their OWN throttled bucket: that
        // bucket is by definition the most recently touched, so it is the last
        // thing this removes. Going quiet long enough to become the oldest entry
        // is exactly what the refill already grants for free.
        if state.buckets.len() >= MAX_RATE_BUCKETS && !state.buckets.contains_key(&ip) {
            let mut by_age: Vec<(IpAddr, Instant)> =
                state.buckets.iter().map(|(k, b)| (*k, b.last)).collect();
            by_age.sort_unstable_by_key(|(_, last)| *last);
            for (victim, _) in by_age
                .into_iter()
                .take(state.buckets.len().saturating_sub(RATE_EVICT_DOWN_TO))
            {
                state.buckets.remove(&victim);
            }
            warn!(
                buckets = state.buckets.len(),
                "rate-limit bucket cap reached; evicted the least recently seen clients"
            );
        }

        let bucket = state.buckets.entry(ip).or_insert(Bucket {
            tokens: RATE_BURST,
            last: now,
        });
        let elapsed = now.duration_since(bucket.last).as_secs_f64();
        bucket.tokens = (bucket.tokens + elapsed * RATE_REFILL_PER_SEC).min(RATE_BURST);
        bucket.last = now;
        if bucket.tokens >= 1.0 {
            bucket.tokens -= 1.0;
            true
        } else {
            false
        }
    }
}

/// The **trusted** client IP for a request.
///
/// Security: a naive limiter that trusts the *left-most* `X-Forwarded-For` hop
/// is fully bypassable — the left-most value is attacker-supplied (any client
/// can send `X-Forwarded-For: <random>`), so each forged value lands in a fresh
/// bucket and the per-IP limit never bites. We therefore derive the IP only from
/// a source the operator controls:
///
/// * If `trusted_header` is configured (e.g. `Fly-Client-IP`,
///   `CF-Connecting-IP`), we read the client IP from THAT header only — it is
///   set by the proxy we run in front and overwrites any client-supplied copy.
///   We take the LAST value if the header happens to be a comma list (the hop
///   the trusted proxy appended), which is also the correct read for a
///   right-most-`X-Forwarded-For` deployment where the operator points
///   `trusted_header` at `x-forwarded-for`.
/// * Otherwise we ignore all forwarding headers and use the socket peer
///   (`ConnectInfo`) — correct for a direct bind with no proxy.
///
/// Returns `None` only when neither source yields a parseable IP (the limiter
/// then fails open for that one request).
fn client_ip(
    headers: &HeaderMap,
    conn: Option<&SocketAddr>,
    trusted_header: Option<&str>,
) -> Option<IpAddr> {
    if let Some(name) = trusted_header {
        if let Some(raw) = headers.get(name).and_then(|v| v.to_str().ok()) {
            // Right-most hop is the one the trusted proxy appended; earlier
            // entries may be client-forged, so never trust the left-most.
            if let Some(last) = raw.split(',').next_back() {
                if let Ok(ip) = last.trim().parse::<IpAddr>() {
                    return Some(ip);
                }
            }
        }
        // Trusted header absent/unparseable → fall through to the socket peer.
    }
    conn.map(|s| s.ip())
}

/// Rate-limit middleware: 429 on the abuse-prone paths once an IP's bucket is
/// empty; every other request (and every non-guarded path) passes through. The
/// peer `SocketAddr` is read from the request extension `ConnectInfo` sets (via
/// `into_make_service_with_connect_info`), preferring `X-Forwarded-For`.
async fn rate_limit(
    State(rl): State<RateLimitState>,
    req: axum::extract::Request,
    next: Next,
) -> Response {
    let path = req.uri().path().to_string();
    let method = req.method().clone();
    if is_rate_limited_path(&path, &method) {
        let conn = req
            .extensions()
            .get::<ConnectInfo<SocketAddr>>()
            .map(|c| c.0);
        let ip = client_ip(req.headers(), conn.as_ref(), rl.trusted_header.as_deref());
        // Deliberately fail OPEN when no client IP is derivable (no trusted
        // header / no socket peer): there is no per-IP key to enforce, and a
        // blanket 429 would self-DoS every guarded path (incl. /login). This is
        // safe precisely because we never key on an attacker-forged XFF — see
        // `rate_limit_ignores_spoofed_xff_rotation`.
        if let Some(ip) = ip {
            if !rl.limiter.check(ip) {
                warn!(%ip, %path, "rate limit exceeded");
                return (
                    StatusCode::TOO_MANY_REQUESTS,
                    [(header::RETRY_AFTER, "1")],
                    "rate limit exceeded\n",
                )
                    .into_response();
            }
        }
    }
    next.run(req).await
}

// ---------------------------------------------------------------------------
// Cache-Control (viral / CDN vs. private authenticated views)
// ---------------------------------------------------------------------------

/// Cache-Control middleware. Emits `public, max-age=300` on the cacheable
/// logged-out surfaces (the `/login` landing without a handle, `/about`,
/// `/privacy`, `/terms`, and the `/static/*` assets) and `no-store` on the
/// authenticated app pages, so a CDN /
/// browser can hold the viral landing while never caching a signed-in user's
/// private view. Never overrides a handler that already set Cache-Control.
async fn cache_control(req: axum::extract::Request, next: Next) -> Response {
    let path = req.uri().path().to_string();
    // The logged-out landing is only cacheable when it's the bare form — a
    // `?handle=` GET kicks off OAuth (a redirect), which must not be cached.
    let is_login_landing = path == "/login"
        && req.method() == axum::http::Method::GET
        && !req.uri().query().unwrap_or("").contains("handle=");
    let public = is_login_landing
        || path == "/about"
        || path == "/privacy"
        || path == "/terms"
        || path.starts_with("/static/");

    let mut resp = next.run(req).await;
    if resp.headers().contains_key(header::CACHE_CONTROL) {
        return resp;
    }
    let value = if public {
        "public, max-age=300"
    } else {
        "no-store"
    };
    if let Ok(hv) = header::HeaderValue::from_str(value) {
        resp.headers_mut().insert(header::CACHE_CONTROL, hv);
    }
    resp
}

// ---------------------------------------------------------------------------
// Health
// ---------------------------------------------------------------------------

/// Run `/health`'s database probe. **The single path, so a test cannot assert
/// on a string the handler is free to ignore** — a named constant alone was not
/// enough: the test read the constant while the handler passed `query_scalar`
/// whatever it liked, so degrading the real call to `SELECT 1` shipped green.
async fn health_db_probe(pool: &store::Pool) -> Result<Option<i64>, sqlx::Error> {
    sqlx::query_scalar::<_, i64>(HEALTH_DB_PROBE_SQL)
        .fetch_optional(pool)
        .await
}

/// The statement `/health` uses to prove the database is readable.
///
/// **A named constant so the test can assert on the query that actually runs.**
/// `the_health_probe_opens_a_real_table` used to `EXPLAIN` a hand-typed copy of
/// this string, so degrading the real probe to `SELECT 1` — which opens no page
/// and therefore cannot detect a broken database — left the suite green.
const HEALTH_DB_PROBE_SQL: &str = "SELECT 1 FROM feeds LIMIT 1";

/// How long `/health` will wait for its database ping before calling it broken.
///
/// Under `fly.toml`'s 3 s check timeout, so a hung pool produces a 503 this
/// handler chose rather than a timeout Fly inferred — the difference between a
/// log line that says why and one that says nothing.
const HEALTH_DB_TIMEOUT: Duration = Duration::from_secs(2);

/// Floor for the poll-heartbeat staleness threshold. **Reported, never fatal** —
/// see the handler for why.
///
/// The threshold itself is derived from the configured tick
/// ([`health_tick_stale_secs`]): hardcoding 15 minutes meant an operator who
/// raised `FEATHERREADER_POLL_TICK_SECS` above 900 got a permanent `poller:
/// stale` in the body the deployment docs now tell them to alert on.
const HEALTH_TICK_STALE_FLOOR_SECS: i64 = 15 * 60;

/// How long without a completed tick before the poller reads as stale: several
/// tick intervals, floored, so a normally-paced loop never trips it and a
/// genuinely wedged one always does.
fn health_tick_stale_secs(tick: Duration) -> i64 {
    let tick = i64::try_from(tick.as_secs()).unwrap_or(i64::MAX);
    tick.saturating_mul(5).max(HEALTH_TICK_STALE_FLOOR_SECS)
}

/// The poll tick this instance is configured for. Read from the same env var
/// `scheduler.rs` reads, because the scheduler lives in the binary crate and the
/// handler cannot see its constants.
fn configured_poll_tick() -> Duration {
    std::env::var("FEATHERREADER_POLL_TICK_SECS")
        .ok()
        .and_then(|v| v.trim().parse::<u64>().ok())
        .filter(|s| *s > 0)
        .map_or(DEFAULT_POLL_TICK_SECS, Duration::from_secs)
}

/// Mirrors `scheduler::DEFAULT_POLL_TICK`, which lives in the BINARY crate and
/// so cannot be imported here. Duplicated deliberately and named, rather than
/// left as a bare `60` inside the parse chain, so the drift is at least visible
/// if the scheduler's value ever moves.
const DEFAULT_POLL_TICK_SECS: Duration = Duration::from_secs(60);

/// Grace period after boot before a poller that has never ticked is called
/// `stale` rather than `not-yet-ticked`.
///
/// Without this the two are indistinguishable forever, which matters precisely
/// in the case the startup delays were added for: in a crash loop with 30 s+ boot
/// cycles the poller never reaches its first tick, so `/health` reported the
/// benign `not-yet-ticked` on every single probe and the heartbeat could not
/// detect the failure mode it exists for. `run_poller` returning early — a failed
/// HTTP client build — has the same shape and was equally invisible.
///
/// Sized off the poller's own startup delay plus its tick, with slack.
const HEALTH_FIRST_TICK_GRACE_SECS: i64 = 5 * 60;

/// `GET /health` — does this process still work, and what are its loops doing?
///
/// This used to return a constant string, touching no database, no pool and no
/// scheduler state — while being the ONLY automated signal in `fly.toml`, whose
/// sole other failure detector is a child process exiting. It proved the HTTP
/// listener was up and nothing else.
///
/// **What can fail the check: the database, and only the database.** A process
/// that cannot reach its store serves nothing, so a restart is the right
/// response and this returns 503. The probe is a read (`SELECT 1`), which in WAL
/// mode is not blocked by any writer — so the retention sweep, the poller and a
/// login burst cannot make this flap. That property is the reason it is a read
/// and not, say, a write canary.
///
/// **What is reported but never fails the check: everything else.** A stale poll
/// heartbeat, a watermark pause, a missing OAuth runtime — all real problems,
/// and none of them a reason to stop serving.
///
/// That last clause is the whole justification, and it is NOT the one this
/// comment used to give. It said "Fly restarts on a failed check", which is
/// false — verified against Fly's own docs, which state it three times: *"your
/// Machines won't automatically restart or stop due to failing their health
/// checks"*. A failing `[[http_service.checks]]` check makes Fly Proxy stop
/// ROUTING to the Machine. Nothing restarts it. That capability existed on Apps
/// V1 (`restart_limit`) and has no successor on Machines.
///
/// The corrected model makes the conclusion stronger, not weaker. With one
/// Machine there is no healthy peer to shift traffic to, so a 503 here is not a
/// failover — it is a total outage that lasts exactly as long as the condition,
/// and it also fails a `fly deploy` (rolling strategy, no auto-rollback). So the
/// question the status code answers is not "would a restart fix this" but **"can
/// this process still serve a useful request at all"**. A stale poller can. A
/// database it cannot read cannot.
///
/// Re-registration is automatic: the proxy keeps probing and routes again the
/// moment the check passes. That is what makes a 503 recoverable without
/// intervention — not a restart, which never comes.
///
/// The body is machine facts only — no user counts, no DIDs, no feed URLs — so
/// it is publishable on the same terms as `/stats`. It is also the non-session
/// diagnostic for an OAuth outage: when nobody can log in, `/admin/metrics`
/// (which needs a live admin session) is exactly as unreachable as the thing it
/// would diagnose, while this is reachable with `curl`.
async fn health(State(state): State<AppState>) -> Response {
    let now = chrono::Utc::now().timestamp();
    let rh = &state.runtime_health;

    use crate::runtime_health::DbProbe;
    let db = match rh.begin_db_probe() {
        // A probe is already in flight; report its predecessor rather than
        // starting a second one. See `RuntimeHealth::begin_db_probe`.
        Err(borrowed) => borrowed,
        Ok(probe) => {
            // **Spawned, so the probe cannot be cancelled by the caller.**
            //
            // Axum drops the handler future when a client disconnects. With the
            // probe inline, that dropped it mid-flight and released the claim
            // WITHOUT recording a verdict — which let an unauthenticated caller
            // manufacture the no-verdict state on demand and freeze what every
            // other caller, Fly's check included, reads. Running it detached
            // means the verdict is always recorded and the claim is always
            // released after it.
            let pool = state.db.clone();
            let task = tokio::spawn(async move {
                // **`SELECT 1` was not a database probe.** It compiles to
                // `Init/Integer/ResultRow/Halt` — there is no `OpenRead`, so it
                // never touches a b-tree, never reads a page, and never consults
                // the file. Against a corrupted database it returns success
                // while every real query returns SQLITE_CORRUPT. Reading one row
                // from a real table costs the same and actually proves what the
                // check claims. `LIMIT 1` keeps it to a single page; an empty
                // table still opens the b-tree root, which is the part that
                // matters.
                let verdict =
                    match tokio::time::timeout(HEALTH_DB_TIMEOUT, health_db_probe(&pool)).await {
                        Ok(Ok(_)) => DbProbe::Ok,
                        // Coarse, not the raw error. An unauthenticated caller
                        // learning exactly which failure it hit is an
                        // attack-progress oracle; the detail belongs in the log,
                        // which gets it here.
                        Ok(Err(err)) => {
                            warn!(%err, "health: database probe failed");
                            DbProbe::Failed("unavailable".to_string())
                        }
                        Err(_) => {
                            warn!(
                                timeout_s = HEALTH_DB_TIMEOUT.as_secs(),
                                "health: database probe timed out (pool exhausted?)"
                            );
                            DbProbe::Failed("timeout".to_string())
                        }
                    };
                probe.record(verdict.clone());
                verdict
            });
            // A panicking task drops the guard, which releases the claim without
            // a verdict — the only remaining path to that state, and not one a
            // caller can drive.
            task.await.unwrap_or(DbProbe::Unknown)
        }
    };

    let uptime = rh.uptime_secs(now);
    let poller = if !rh.schedulers_enabled() {
        // Not a fault. Dev runs and the seam tests disable the loops on purpose,
        // and reporting that as "stale" would be a false alarm on every one.
        "disabled".to_string()
    } else {
        match rh.secs_since_poll_tick(now) {
            // "Never ticked" is benign right after boot and alarming well after
            // it — so it is read against UPTIME, not left permanently benign.
            None => match uptime {
                Some(up) if up > HEALTH_FIRST_TICK_GRACE_SECS => {
                    format!("stale never-ticked {up}s")
                }
                _ => "not-yet-ticked".to_string(),
            },
            Some(secs) if secs > health_tick_stale_secs(configured_poll_tick()) => {
                format!("stale {secs}s")
            }
            Some(secs) => format!("ok {secs}s"),
        }
    };

    // **Only a MEASURED failure fails the check.**
    //
    // `Unknown` means no probe has completed — a concurrent request arrived
    // before the first one finished, or a previous owner was cancelled before
    // recording. It is reported and returns 200, because an unmeasured database
    // is not evidence of a broken one, and this endpoint is reachable by
    // unauthenticated callers who can manufacture that state. Treating it as a
    // failure handed them a lever on the only signal the platform acts on.
    let mut body = String::new();
    let status = match &db {
        DbProbe::Ok => {
            body.push_str(&format!("ok featherreader/{VERSION}\n"));
            body.push_str("db: ok\n");
            StatusCode::OK
        }
        // **Not `ok`.** The first token is the state, and this one is neither
        // healthy nor failed. It used to print a line byte-identical to the
        // healthy branch, which mattered because `fly.toml` tells operators to
        // alert on the BODY for everything the status code deliberately ignores
        // — so a monitor keying on `^ok` read green in exactly the state this
        // enum exists to make visible.
        DbProbe::Unknown => {
            body.push_str(&format!("unknown featherreader/{VERSION}\n"));
            body.push_str("db: unknown (no probe has completed yet)\n");
            StatusCode::OK
        }
        DbProbe::Failed(why) => {
            body.push_str(&format!("FAIL featherreader/{VERSION}\n"));
            body.push_str(&format!("db: {why}\n"));
            StatusCode::SERVICE_UNAVAILABLE
        }
    };
    // Uptime answers the first question anyone asks about a container under a
    // supervisor that tears the machine down whenever a child exits: is this
    // thing restarting? Nothing else on any surface could tell you.
    body.push_str(&format!(
        "uptime: {}\n",
        match uptime {
            Some(secs) => format!("{secs}s"),
            None => "unknown".to_string(),
        }
    ));
    body.push_str(&format!("poller: {poller}\n"));
    body.push_str(&format!(
        "polling-paused: {}\n",
        if rh.watermark_paused() { "yes" } else { "no" }
    ));
    // Deliberately NOT the measured database size. `/health` is the one path
    // exempted from the Caddy origin lock, so it answers direct hits to the Fly
    // IP that never passed Cloudflare — which caps what belongs here at the
    // class of facts `/stats` already publishes to anyone. "Polling is paused"
    // is that; the exact byte count is a precise internal number that adds
    // nothing an operator cannot get from `/stats` or the logs.
    body.push_str(&format!(
        "backend: {}\n",
        state.config.repo_backend.as_str()
    ));
    body.push_str(&format!(
        "oauth-runtime: {}\n",
        if state.oauth.is_some() {
            "built"
        } else {
            "absent"
        }
    ));

    // Never cached: a stale health response is worse than none, and Cloudflare
    // sits in front of this.
    let mut resp = (status, body).into_response();
    if let Ok(hv) = header::HeaderValue::from_str("no-store") {
        resp.headers_mut().insert(header::CACHE_CONTROL, hv);
    }
    resp
}

/// `GET /about` — the public-experiment page: the full disclaimer (experimental,
/// no SLA, may pause anytime), the OSS / self-host pitch, and the tip link.
/// Readable whether or not a session exists.
///
/// Optionally carries one quiet line about network adoption
/// (`design/NETWORK-SPEC.md` §4.4). With `FEATHERREADER_SHOW_ADOPTION` off — the
/// default — the handler issues **zero** queries and the page is byte-identical
/// to what it was before the probe existed.
async fn about(State(state): State<AppState>) -> Response {
    let adoption = if state.config.show_adoption {
        adoption_line(&state).await
    } else {
        None
    };
    render(&AboutTemplate {
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
        adoption,
    })
}

/// `POST /saved/:rkey/delete` — remove a saved record that has no local entry.
///
/// The normal star toggle is keyed on an entry id, which a PDS-only saved row
/// does not have. This deletes the record straight from the repo by its rkey,
/// and then clears any LOCAL star for the same article.
///
/// That second step is not belt-and-braces. "Has no local entry" is how the
/// starred view classifies a record, and it decides that through `sub_ref` — so
/// an article that really is cached, and really is starred, lands here whenever
/// the reader has unsubscribed from its feed. Deleting only the record left
/// `entry_state.starred = 1` behind: invisible, because the starred list is
/// `sub_ref`-scoped too, until a resubscribe brought the star back with nothing
/// in the PDS backing it. A reader who clicks "remove" gets it removed from both
/// places it lives.
async fn unsave_record(
    State(state): State<AppState>,
    headers: HeaderMap,
    Path(rkey): Path<String>,
) -> Response {
    let Some(did) = current_did(&state, &headers).await else {
        return (StatusCode::UNAUTHORIZED, "sign in first\n").into_response();
    };

    // Read the record's identity BEFORE deleting it — afterwards there is
    // nothing left to learn it from. Best-effort: a failure here must not block
    // the deletion the reader actually asked for, so it degrades to the old
    // behaviour (record gone, local star possibly stale) and says so.
    let identity = match state.repo().list_saved(&did).await {
        Ok(records) => records
            .into_iter()
            .find(|(k, _)| *k == rkey)
            .map(|(_, rec)| (rec.url, rec.entry_id)),
        Err(err) => {
            warn!(%err, %did, %rkey, "could not read the saved record before deleting it; \
                                      a local star for the same article may survive");
            None
        }
    };

    match state.repo().remove_saved(&did, &rkey).await {
        Ok(()) => info!(%did, %rkey, "removed a saved record with no cached entry"),
        Err(err) => {
            warn!(%err, %did, %rkey, "could not remove the saved record");
            return (StatusCode::BAD_GATEWAY, "could not remove that item\n").into_response();
        }
    }

    // Deliberately AFTER the delete: the PDS is the source of truth for what was
    // saved, so clearing the local star before knowing the record is gone would
    // be the desync in the other direction.
    if let Some((url, guid)) = identity {
        match store::clear_star_by_identity(&state.db, &did, Some(&url), guid.as_deref()).await {
            Ok(0) => {}
            Ok(n) => {
                info!(%did, %rkey, cleared = n, "cleared the local star for an unsaved record")
            }
            Err(err) => warn!(%err, %did, %rkey, "could not clear the local star after unsaving"),
        }
    }
    // htmx swaps the row out; a plain form post goes back to the starred list.
    if is_htmx(&headers) {
        return (StatusCode::OK, "").into_response();
    }
    Redirect::to("/?view=starred").into_response()
}

/// What the poller is doing, as one word for `/stats`.
///
/// **Parity with `/health` is the point.** `polling_paused` alone reported
/// "running" for three different states including the two where nothing polls,
/// on the page added to answer exactly that. The first attempt at fixing it
/// added `off` and `starting` and claimed parity — but left out `stale`, so a
/// poll loop that ticked once at boot and then WEDGED still read as running.
/// That is the wedged-loop case `/health`'s heartbeat exists for, and the
/// original finding's exact shape surviving its own fix.
///
/// Shares the staleness threshold with `/health` rather than picking its own, so
/// the two pages cannot disagree about what "stale" means.
fn fetching_state(rh: &crate::runtime_health::RuntimeHealth, now_unix: i64) -> &'static str {
    if !rh.schedulers_enabled() {
        return "off";
    }
    // Checked before the pause: a wedged poller cannot clear a pause either, so
    // reporting "paused" would name the symptom and hide the cause.
    match rh.secs_since_poll_tick(now_unix) {
        None => {
            // Never ticked. Benign at boot, a dead loop long after — read
            // against uptime, exactly as `/health` does.
            match rh.uptime_secs(now_unix) {
                Some(up) if up > HEALTH_FIRST_TICK_GRACE_SECS => "stale",
                _ => "starting",
            }
        }
        Some(secs) if secs > health_tick_stale_secs(configured_poll_tick()) => "stale",
        _ if rh.watermark_paused() => "paused",
        _ => "running",
    }
}

/// `GET /stats` — public poll health.
async fn stats(State(state): State<AppState>) -> Response {
    let now = chrono::Utc::now();
    let health = match store::poll_health(
        &state.db,
        &now.to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
        &(now - chrono::Duration::hours(1)).to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
    )
    .await
    {
        Ok(health) => health,
        Err(err) => {
            warn!(%err, "could not compute poll health");
            return (StatusCode::INTERNAL_SERVER_ERROR, "stats unavailable\n").into_response();
        }
    };

    // Percentage of a zero-feed instance is 100, not a divide-by-zero: a fresh
    // instance is not behind on anything.
    let polled_pct = if health.feeds_tracked == 0 {
        100
    } else {
        health.polled_last_hour * 100 / health.feeds_tracked
    };

    render(&StatsTemplate {
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
        feeds_tracked: health.feeds_tracked,
        polled_last_hour: health.polled_last_hour,
        polled_pct,
        overdue: health.overdue,
        last_poll: humanise_ago(health.last_poll_secs_ago),
        oldest_poll: if health.never_polled > 0 {
            "never".to_string()
        } else {
            humanise_ago(health.oldest_poll_secs_ago)
        },
        never_polled: health.never_polled,
        poll_interval_mins: state.config.poll_interval.as_secs() as i64 / 60,
        // **The two states that actually stop feeds updating.**
        //
        // Neither was visible anywhere. `overdue` and `polled_last_hour` move in
        // both and distinguish neither — and `overdue` moves the WRONG WAY for
        // backoff, since backoff is applied by pushing `next_poll` forward, so a
        // feed failing every fetch drops out of the backlog and makes the page
        // read healthier. Both of these are machine facts with no per-feed
        // detail, so they sit inside the page's stated contract.
        in_backoff: health.in_backoff,
        badly_broken: health.badly_broken,
        failure_kinds: health.failure_kinds,
        fetching: fetching_state(&state.runtime_health, now.timestamp()),
    })
}

/// "3h 11m ago", or "never" when there has been no poll at all.
///
/// `None` must not render as `0` — on a fresh instance that would read as
/// "polled just now", which is the opposite of the truth.
fn humanise_ago(secs: Option<i64>) -> String {
    let Some(secs) = secs else {
        return "never".to_string();
    };
    match secs {
        s if s < 60 => format!("{s}s ago"),
        s if s < 3600 => format!("{}m ago", s / 60),
        s => format!("{}h {}m ago", s / 3600, (s % 3600) / 60),
    }
}

/// The `/about` adoption line's data, or `None` (no successful probe yet, an
/// observation of zero, or a store failure).
///
/// A read failure degrades to `None` plus a `warn!` rather than propagating: the
/// probe is never allowed to affect the reader, and that rule applies at the
/// display end too — a locked or corrupt DB costs the About page one log line,
/// not a 500.
async fn adoption_line(state: &AppState) -> Option<AdoptionLine> {
    match store::latest_network_stat(&state.db, store::ADOPTION_STAT_KEY).await {
        // A legitimate zero renders nothing rather than a sad "0 accounts".
        Ok(Some(stat)) if stat.value > 0 => Some(AdoptionLine {
            repos: stat.value,
            truncated: stat.truncated,
            observed_on: stat
                .observed_at
                .split('T')
                .next()
                .unwrap_or_default()
                .to_string(),
        }),
        Ok(_) => None,
        Err(err) => {
            warn!(%err, "about: adoption stat read failed; omitting the line");
            None
        }
    }
}

/// `GET /privacy` — the plain-language privacy page: no account/tracking, data
/// lives in the user's PDS, what the server caches, and the session-token
/// handling. A static render; readable whether or not a session exists.
async fn privacy() -> Response {
    render(&PrivacyTemplate {
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
    })
}

/// `GET /terms` — the terms of use: the experimental / as-is disclaimer,
/// acceptable use, the AGPL/self-host note, and the liability limitation. A
/// static render; readable whether or not a session exists.
async fn terms() -> Response {
    render(&TermsTemplate {
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
    })
}

// ---------------------------------------------------------------------------
// View models
// ---------------------------------------------------------------------------

/// A feed as shown in the sidebar (title + its unread count + a stable scope key
/// and the PDS subscription rkey for management actions).
struct FeedView {
    /// PDS subscription rkey — addresses the record for rename/unsubscribe.
    rkey: String,
    /// Canonical feed URL — the sidebar filter key (`?feed=<url>`).
    url: String,
    title: String,
    unread: i64,
    /// Whether this feed is the currently-selected scope.
    selected: bool,
    /// The feed's current folder `at://` URI (from its subscription record), or
    /// `None` if un-foldered. Drives the pre-selected `<option>` in the manage
    /// rename row so an untouched folder dropdown does not silently un-folder the
    /// feed on save.
    folder: Option<String>,
}

/// A folder grouping in the sidebar, sourced from the PDS `folder` records.
struct FolderView {
    /// PDS folder rkey — addresses the record for rename/delete.
    rkey: String,
    /// The folder's `at://` URI — the sidebar filter key (`?folder=<uri>`).
    uri: String,
    name: String,
    feeds: Vec<FeedView>,
    /// Whether this folder is the currently-selected scope.
    selected: bool,
}

/// One entry as shown in the article list / after an htmx swap.
struct EntryRow {
    id: i64,
    title: String,
    feed_title: String,
    published: String,
    read: bool,
    starred: bool,
    /// The reader link href, already carrying the scope/view query so opening an
    /// entry and paging back stays within the list it came from.
    link: SafeLink,
    /// Whether the article itself is in this instance's cache.
    ///
    /// `false` for a saved record that exists in the reader's PDS but whose
    /// entry was never cached here — starred in another atproto reader, or
    /// starred here and since evicted. There is no local row, so the row has no
    /// usable `id`: it links straight out to the article and carries no
    /// mark-read control, because there is nothing local to mark.
    cached: bool,
    /// The PDS record key, for un-saving a row that has no local entry.
    rkey: String,
}

/// A folder as an option in the "move feed to folder" select.
struct FolderOption {
    uri: String,
    name: String,
}

/// The shared navigation "rail" model: the same DOM element is the
/// mobile drawer and the desktop sidebar, so every chrome page (list / reader /
/// manage) renders it from this one struct. Feed management lives on `/manage`,
/// not here — the rail is navigation only.
struct Nav {
    /// `@handle` for the identity chip (falls back to the DID's tail).
    handle: String,
    /// Two-letter avatar initials for the identity chip.
    avatar: String,
    /// The active filter: `"unread" | "all" | "starred"` (drives `aria-current`).
    view: String,
    /// The scope query suffix (`feed=…` / `folder=…`) carried onto filter links,
    /// empty for the unscoped "everything" views.
    scope_qs: String,
    /// Folders (each with its feeds) then un-foldered feeds, for the rail lists.
    /// Per-feed `selected` flags drive the rail's feed `aria-current`.
    folders: Vec<FolderView>,
    loose_feeds: Vec<FeedView>,
    /// Whether the "Manage feeds" rail tool is the current page.
    manage_active: bool,
}

/// The reader index (`GET /`).
#[derive(Template)]
#[template(path = "index.html")]
struct IndexTemplate {
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
    flash: String,
    /// The shared rail (drawer + desktop sidebar) navigation model.
    nav: Nav,
    /// The article list for the selected scope + view.
    entries: Vec<EntryRow>,
    /// The list heading (the selected view/feed/folder name).
    heading: String,
    /// Whether a feed scope is active (enables per-feed mark-all-read).
    feed_scope: Option<String>,
    /// Total CACHED entries in this scope + view across ALL pages. The count used
    /// to be `entries.len()`, which was the same number only because the list was
    /// unpaged — the thing this change exists to stop.
    ///
    /// The pager is derived from this, so it must not include the uncached PDS
    /// rows below: they are appended to the last page rather than paged, and
    /// counting them here advertised a page the clamp could never reach.
    total: i64,
    /// How many of `total` are PDS saved records the cache cannot show.
    ///
    /// A subset of `total`, not an addition to it — the heading says "N entries
    /// (M saved elsewhere)". An earlier version rendered "N entries, plus M",
    /// which double counted once `total` started including them, against an M
    /// that had become page-local in the same commit while the template stayed
    /// put.
    uncached_total: i64,
    /// 1-based current page.
    page: i64,
    /// Total pages, at least 1 (an empty list is page 1 of 1).
    page_count: i64,
    /// Link to the previous (newer) page, or `None` on the first.
    prev_href: Option<String>,
    /// Link to the next (older) page, or `None` on the last.
    next_href: Option<String>,
}

/// The feed-management page (`GET /manage`) — subscribe / your-feeds / OPML.
#[derive(Template)]
#[template(path = "manage.html")]
struct ManageTemplate {
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
    flash: String,
    nav: Nav,
    /// All folders as move-targets for the subscribe folder select.
    folder_options: Vec<FolderOption>,
    /// Folders (each with feeds) + loose feeds, for the "Your feeds" list.
    folders: Vec<FolderView>,
    loose_feeds: Vec<FeedView>,
}

/// The optional one-line adoption fact at the bottom of `/about`
/// (`design/NETWORK-SPEC.md` §4.4). `None` whenever the display flag is off, no
/// probe has succeeded yet, or the read failed — the line then simply does not
/// render.
struct AdoptionLine {
    /// Repos a relay has indexed as holding the subscription collection.
    repos: i64,
    /// The probe hit its page cap, so the copy must say "at least".
    truncated: bool,
    /// Observation date, `YYYY-MM-DD` (UTC), sliced from the stored RFC3339 stamp.
    observed_on: String,
}

/// The public-experiment `/about` page — disclaimer + OSS pitch + tip link, plus
/// the optional adoption line.
#[derive(Template)]
#[template(path = "about.html")]
struct AboutTemplate {
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
    adoption: Option<AdoptionLine>,
}

/// The public `/stats` page — is the poller keeping up?
///
/// Aggregate only, deliberately. It is published to anyone, so it carries no
/// user counts and no per-feed detail: a reader does not need to know how many
/// people use an instance or which feeds are failing. What it does answer is the
/// question that decides whether an instance can take more readers — whether the
/// poller is servicing the feeds it already has.
///
/// The counts below are aggregate machine facts, which is why they fit that
/// contract: "12 feeds are in backoff" names no feed and no reader, while
/// answering the question the page was previously unable to answer at all.
#[derive(Template)]
#[template(path = "stats.html")]
struct StatsTemplate {
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
    feeds_tracked: i64,
    polled_last_hour: i64,
    polled_pct: i64,
    overdue: i64,
    last_poll: String,
    oldest_poll: String,
    never_polled: i64,
    poll_interval_mins: i64,
    /// Feeds in error backoff. Invisible before, and excluded from `overdue`.
    in_backoff: i64,
    /// Of those, the ones retried hours apart rather than minutes. **Not
    /// "effectively dead"** — see `store::BADLY_BROKEN_ERRORS`; they recover on
    /// their next successful poll, and most of this instance's did.
    badly_broken: i64,
    /// Failing feeds by cause, descending — counts only, never which feed.
    failure_kinds: Vec<(String, i64)>,
    /// What the poller is actually doing: `running`, `paused` (at the size
    /// watermark), `starting` (no tick completed yet) or `off` (schedulers
    /// disabled). Three of those four used to render as "running".
    fetching: &'static str,
}

/// The public `/privacy` page — what the server holds vs. what lives in the
/// user's PDS. Carries the same `repo_url`/`kofi_url`/`version` the shared
/// footer include needs.
#[derive(Template)]
#[template(path = "privacy.html")]
struct PrivacyTemplate {
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
}

/// The public `/terms` page — the as-is / no-warranty terms of use. Carries the
/// same fields the shared footer include needs.
#[derive(Template)]
#[template(path = "terms.html")]
struct TermsTemplate {
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
}

/// The signed-out landing page (`GET /` with no session) — the public front
/// door at feather-reader.com. A static render, no session required.
#[derive(Template)]
#[template(path = "landing.html")]
struct LandingTemplate {
    version: &'static str,
    repo_url: &'static str,
    crates_url: &'static str,
    kofi_url: &'static str,
}

/// The single-entry reader view (`GET /entries/:id`).
#[derive(Template)]
#[template(path = "entry.html")]
struct EntryTemplate {
    version: &'static str,
    repo_url: &'static str,
    kofi_url: &'static str,
    nav: Nav,
    id: i64,
    title: String,
    feed_title: String,
    author: Option<String>,
    published: String,
    /// The entry's own link, for `entry.html`'s two `href`s.
    ///
    /// `Option<SafeLink>`, not `Option<String>`: the column it comes from holds
    /// a remote feed's `<link>`. Ingest scheme-checks it, but that guard is a
    /// long way from the `href` and holds only while every future writer to
    /// `entries.url` remembers to go through `feed.rs` — the same procedural
    /// defence that, on the saved-record row, turned out to be deletable with
    /// all 679 tests still green. `None` is the refusal: the template's
    /// no-URL branch already renders a disabled open-original button.
    url: Option<SafeLink>,
    content_html: Option<String>,
    read: bool,
    starred: bool,
    /// The query string to carry the reading context back to the list.
    back_qs: String,
    /// Prev/next entry ids within the current list, for keyboard/paging nav.
    prev_id: Option<i64>,
    next_id: Option<i64>,
    /// Rendered inline (not an out-of-band swap fragment): always `false` here.
    oob: bool,
}

/// The htmx swap fragment for a single entry row (`entry_row.html`).
#[derive(Template)]
#[template(path = "entry_row.html")]
struct EntryRowTemplate {
    e: EntryRow,
}

/// The reader's action-bar fragment (`entry_actionbar.html`) returned as an
/// out-of-band swap after a mark-read / star toggle FROM THE READER, so the
/// button's hidden value + `aria-pressed` update in place (the reader `<li>`
/// isn't in the DOM to swap, unlike the list view's `entry_row.html`).
#[derive(Template)]
#[template(path = "entry_actionbar.html")]
struct EntryActionBarTemplate {
    id: i64,
    read: bool,
    starred: bool,
    /// Emit the `hx-swap-oob` attribute: `true` for the handler's OOB response.
    oob: bool,
}

/// The login stub (`GET /login`).
#[derive(Template)]
#[template(path = "login.html")]
struct LoginTemplate {
    repo_url: &'static str,
    error: String,
    /// A neutral/success banner (e.g. the post-delete "signed out" confirmation),
    /// distinct from `error`. Empty renders nothing.
    flash: String,
}

/// The closed-beta invite-redeem page (`GET /beta/redeem`).
#[derive(Template)]
#[template(path = "beta_redeem.html")]
struct BetaRedeemTemplate {
    repo_url: &'static str,
    error: String,
    /// When true the seat cap is full: hide the form and show the "capacity
    /// full — try self-hosting" message instead.
    capacity_full: bool,
}

// ---------------------------------------------------------------------------
// Rendering + error helpers
// ---------------------------------------------------------------------------

/// Render an askama template into an HTML response, mapping a render failure to
/// a `500` rather than panicking (no `unwrap` in the request path).
fn render<T: Template>(tmpl: &T) -> Response {
    match tmpl.render() {
        Ok(body) => Html(body).into_response(),
        Err(err) => {
            warn!(%err, "template render failed");
            (StatusCode::INTERNAL_SERVER_ERROR, "template render error").into_response()
        }
    }
}

/// A minimal web error type so handlers can `?`-propagate `anyhow` failures and
/// still return an `impl IntoResponse`. Renders as a `500` with a short message
/// by default; a handler may override the status (e.g. `413` for an over-cap
/// upload) via [`WebError::with_status`].
struct WebError {
    err: anyhow::Error,
    status: StatusCode,
}

impl<E: Into<anyhow::Error>> From<E> for WebError {
    fn from(err: E) -> Self {
        WebError {
            err: err.into(),
            status: StatusCode::INTERNAL_SERVER_ERROR,
        }
    }
}

impl WebError {
    /// Attach an explicit HTTP status to render instead of the default `500`.
    fn with_status(err: impl Into<anyhow::Error>, status: StatusCode) -> Self {
        WebError {
            err: err.into(),
            status,
        }
    }
}

impl IntoResponse for WebError {
    fn into_response(self) -> Response {
        warn!(error = %self.err, status = %self.status, "request failed");
        let body = if self.status == StatusCode::INTERNAL_SERVER_ERROR {
            "internal error"
        } else {
            self.status.canonical_reason().unwrap_or("error")
        };
        (self.status, body).into_response()
    }
}

/// Map an axum [`MultipartError`] to a [`WebError`] that preserves the error's
/// own HTTP status. When a request exceeds the route's `DefaultBodyLimit` the
/// multipart extractor reports `413 Payload Too Large`; a malformed body reports
/// `400`. Either way this avoids collapsing the failure into a generic `500`.
fn multipart_response(err: axum::extract::multipart::MultipartError) -> WebError {
    let status = err.status();
    WebError::with_status(err, status)
}

/// A short, human display of a feed/site title for the sidebar/list, falling
/// back to the host of a URL and finally to the raw string.
fn display_title(title: Option<&str>, url: &str) -> String {
    if let Some(t) = title {
        let t = t.trim();
        if !t.is_empty() {
            return t.to_string();
        }
    }
    url::Url::parse(url)
        .ok()
        .and_then(|u| u.host_str().map(str::to_string))
        .unwrap_or_else(|| url.to_string())
}

/// A display `@handle` for the identity chip: the stored handle if present,
/// else the tail of the DID so the chip is never empty.
fn display_handle(handle: Option<&str>, did: &str) -> String {
    match handle {
        Some(h) if !h.trim().is_empty() => format!("@{}", h.trim().trim_start_matches('@')),
        _ => did.rsplit(':').next().unwrap_or(did).to_string(),
    }
}

/// Two-letter, lowercase avatar initials from a handle/DID.
fn avatar_initials(handle: Option<&str>, did: &str) -> String {
    let source = handle
        .map(|h| h.trim().trim_start_matches('@'))
        .filter(|h| !h.is_empty())
        .unwrap_or_else(|| did.rsplit(':').next().unwrap_or(did));
    let letters: String = source
        .chars()
        .filter(|c| c.is_alphanumeric())
        .take(2)
        .collect::<String>()
        .to_lowercase();
    if letters.is_empty() {
        "fr".to_string()
    } else {
        letters
    }
}

/// Trim a stored RFC3339 timestamp down to the `YYYY-MM-DD` date for calm,
/// low-noise display. Falls back to the raw string if it doesn't look like one.
fn display_date(published: Option<&str>) -> String {
    // CHARACTERS, not bytes. `p[..10]` panics when byte 10 lands inside a
    // multi-byte character, and every caller used to pass a timestamp the feed
    // parser had produced. The saved-record path passes `createdAt` straight off
    // a PDS record, which the lexicon types as a bare string with no validation
    // — written by whatever atproto client the reader used. A `createdAt` of
    // "日本語日本語日本" took down the whole starred view, and there is no
    // catch-panic layer in the stack, so the page stayed down until the record
    // was removed from the very view that would not render.
    match published {
        Some(p) => p.chars().take(10).collect(),
        None => String::new(),
    }
}

/// Percent-encode a value for use in a query string (RFC 3986 unreserved kept).
/// Small and dependency-free — the `url` crate's form-encoding isn't exposed for
/// a bare value, and this keeps the scope-preserving links honest.
fn qenc(s: &str) -> String {
    let mut out = String::with_capacity(s.len() * 3);
    for b in s.bytes() {
        match b {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
                out.push(b as char)
            }
            _ => out.push_str(&format!("%{b:02X}")),
        }
    }
    out
}

// ---------------------------------------------------------------------------
// Reader: index
// ---------------------------------------------------------------------------

/// Query for `GET /` — the scope + view selector.
#[derive(Debug, Deserialize, Default)]
struct IndexQuery {
    /// Filter to a single feed by its canonical URL.
    #[serde(default)]
    feed: Option<String>,
    /// Filter to a folder by its `at://` URI (shows every feed in the folder).
    #[serde(default)]
    folder: Option<String>,
    /// `unread` (default) | `all` | `starred`.
    #[serde(default)]
    view: Option<String>,
    /// 1-based page within the selected scope + view. Absent/0 means page 1.
    #[serde(default)]
    page: Option<u32>,
    /// Optional flash message (e.g. after an action redirect).
    #[serde(default)]
    flash: Option<String>,
}

/// Rows per page in the reader's list views.
///
/// The list projection no longer carries article bodies ([`store::EntryListRow`]),
/// so a page is on the order of tens of kilobytes rather than the tens or
/// hundreds of megabytes an unbounded list of full entries could reach. The page
/// bound is the second half of that fix: without it, a reader with a long
/// backlog still decides how much memory a single request allocates.
const ENTRIES_PER_PAGE: i64 = 100;

/// How many pages `total` entries occupy. An empty list is page 1 of 1, so the
/// pager reads "1 / 1" rather than "1 / 0".
fn page_count_for(total: i64) -> i64 {
    ((total + ENTRIES_PER_PAGE - 1) / ENTRIES_PER_PAGE).max(1)
}

/// Ceiling on the reader's prev/next id list.
///
/// Unlike the page above, this genuinely spans the whole list — prev/next is the
/// reader's position within it — so it is bounded by count rather than paged. At
/// 8 bytes per id this is ~40 KB at the cap. Past it the neighbour links stop
/// resolving; the article itself still opens, and the list view still pages.
const PREV_NEXT_MAX: i64 = 5_000;

/// Ceiling on the cached-starred identity set matched against PDS saved records.
///
/// Deliberately generous: under-reading this set makes a cached article look
/// uncached, and an uncached starred row's button deletes the PDS RECORD rather
/// than un-starring the entry. Truncating here would change what a click
/// destroys, so the cap exists only as a backstop against an absurd starred
/// count, not as a routine bound.
const STARRED_IDENTITY_MAX: i64 = 20_000;

/// Most uncached PDS saved records this handler will hold in memory for one
/// request.
///
/// **A memory bound, not a visibility bound.** These rows are PAGED alongside
/// the cached entries, so `ENTRIES_PER_PAGE` decides how many are rendered and
/// this only caps how many are collected before slicing. An earlier version used
/// it to cap what was SHOWN, which left everything past it invisible and —
/// because the un-save control lives on the row, and nothing else in the app
/// lists these — unremovable.
///
/// Well above the PDS list ceiling's practical reach for one reader, so a reader
/// meeting it has thousands of saved records and gets a logged, ordered prefix
/// rather than a failure.
const MAX_UNCACHED_SAVED_ROWS: usize = 5_000;

/// A subscription resolved against the local cache: the PDS record + its
/// (possibly-missing) cached feed row.
struct ResolvedSub {
    rkey: String,
    sub: Subscription,
    feed: Option<store::Feed>,
}

/// Pull the user's subscriptions (source of truth = PDS), ensure each has a
/// local cache row so unread counts work, and return them resolved. Best-effort
/// on the sidecar: a failure falls back to the local cache alone.
async fn resolve_subscriptions(state: &AppState, did: &str) -> Vec<ResolvedSub> {
    let pool = &state.db;
    let subs = match state.repo().list_subscriptions_sorted(did).await {
        Ok(s) => s,
        Err(err) => {
            warn!(%err, %did, "could not list PDS subscriptions; showing this DID's cached subscriptions only");
            // Fail CLOSED: the PDS is the source of truth for what this DID
            // follows. When it is unreachable we must NOT widen the caller's
            // authorization surface. Serve from the DID's OWN last-known
            // `sub_ref` projection (its own feeds, possibly stale) and leave
            // `sub_ref` untouched — never synthesize from every cached feed,
            // which would grant cross-tenant read+mutate during any outage.
            // A DB failure here is NOT the same as "this DID follows nothing",
            // but `unwrap_or_default` rendered it as exactly that: an empty
            // sidebar and an empty reader, which arrives as "all my feeds
            // vanished". It still degrades to empty — there is nothing better to
            // show — but it says so, so the support ticket and the log line can
            // be matched up.
            let feeds = store::feeds_for_did(pool, did).await.unwrap_or_else(|err| {
                warn!(%err, %did, "the PDS is unreachable AND the local subscription \
                                   projection could not be read; rendering an EMPTY \
                                   feed list, which is not the same as having none");
                Vec::new()
            });
            return feeds
                .into_iter()
                .map(|f| ResolvedSub {
                    rkey: String::new(),
                    sub: Subscription::new(f.url.clone(), now_rfc3339()),
                    feed: Some(f),
                })
                .collect();
        }
    };

    // **Deliberately NOT truncated to `max_subs_per_did`.**
    //
    // The PDS list is unbounded in practice — any client can write subscription
    // records, and only the 20,000-record list ceiling stops it — and the first
    // attempt at bounding it truncated the list right here. That was the wrong
    // place: `sync_sub_refs` below writes `sub_ref` from exactly this set, and
    // `sub_ref` is THE per-DID authorization hook, so dropping entries silently
    // removed the reader's ability to read OR mutate those feeds. A query-shape
    // problem would have become an access problem.
    //
    // The shape problem was the scope filter emitting one SQL placeholder per
    // feed; `store::list_query_sql` now passes the whole set as a single
    // `json_each` bind, so there is no size to defend against here and nothing
    // to truncate. `max_subs_per_did` stays what it is — a policy cap on ADDING
    // feeds — rather than becoming a silent read-time filter.
    let mut out = Vec::with_capacity(subs.len());
    for (rkey, sub) in subs {
        let feed = match store::get_feed_by_url(pool, &sub.url).await {
            Ok(Some(f)) => Some(f),
            Ok(None) => {
                // `sub.url` came out of an atproto record. The lexicon is open —
                // ANY client can write a subscription into a user's repo — so
                // this is untrusted input on the hot path of `GET /`, and it was
                // being stored with none of the three checks the add and import
                // paths apply. Two of those are capacity ceilings; this one is
                // the invariant in `FeedPrivacy`'s doc comment, which promises a
                // private feed URL is "never stored". Writing a
                // `…/feed/private/<token>` into the SHARED `feeds` table breaks
                // that promise even though `net::guarded_get` still refuses to
                // fetch it.
                if !feed::is_storable_feed_url(&sub.url, state.config.standard_site)
                    || feed::classify_feed_privacy(&sub.url).is_private()
                {
                    warn!(
                        %did,
                        "skipping cache row for a subscription URL that is private or not http(s)"
                    );
                    out.push(ResolvedSub {
                        rkey,
                        sub,
                        feed: None,
                    });
                    continue;
                }
                // Upsert a cache row so the sidebar reflects the real follow-list.
                //
                // A silent failure here is a support ticket with no evidence: no
                // `feeds` row means the poller never selects this subscription,
                // so the reader sees "I added a feed and it never updates" while
                // the PDS record looks perfect. Logged with the URL so the
                // failing subscription is identifiable.
                if let Err(err) = store::upsert_feed(
                    pool,
                    &store::NewFeed {
                        url: sub.url.clone(),
                        title: sub.title.clone(),
                        site_url: sub.site_url.clone(),
                        ..Default::default()
                    },
                )
                .await
                {
                    warn!(%err, url = %sub.url, %did, "could not cache a subscribed feed; \
                                                       it will not be polled");
                }
                store::get_feed_by_url(pool, &sub.url).await.ok().flatten()
            }
            Err(err) => {
                warn!(%err, url = %sub.url, "get_feed_by_url failed");
                None
            }
        };
        out.push(ResolvedSub { rkey, sub, feed });
    }
    // Mirror the caller's resolved subscription set into `sub_ref`, so every
    // scoped entry/feed read + read/star mutation authorizes against exactly
    // the feeds this DID follows right now. This is THE per-DID isolation hook.
    sync_sub_refs(pool, did, &out).await;
    out
}

/// Refresh the `sub_ref` projection for `did` to exactly the feed ids present
/// in `subs`. Best-effort: a failure here only degrades the scoped reads (they
/// fail closed / show fewer rows), never leaks another user's entries.
async fn sync_sub_refs(pool: &store::Pool, did: &str, subs: &[ResolvedSub]) {
    let feed_ids: Vec<i64> = subs
        .iter()
        .filter_map(|s| s.feed.as_ref().map(|f| f.id))
        .collect();
    if let Err(err) = store::replace_sub_refs(pool, did, &feed_ids).await {
        warn!(%err, %did, "failed to sync sub_ref projection");
    }
}

/// `GET /` — the reader. Renders the sidebar (folders + feeds from the PDS
/// records layer) and the article list for the selected scope + view.
async fn index(
    State(state): State<AppState>,
    headers: HeaderMap,
    Query(q): Query<IndexQuery>,
) -> Result<Response, WebError> {
    let user = match current_session(&state, &headers).await {
        Some(u) => u,
        // Signed out: serve the public landing page rather than bouncing to
        // /login. /login remains the entry point for the actual OAuth sign-in.
        None => {
            return Ok(render(&LandingTemplate {
                version: VERSION,
                repo_url: REPO_URL,
                crates_url: CRATES_URL,
                kofi_url: KOFI_URL,
            }))
        }
    };
    let did = user.did.clone();
    let pool = &state.db;

    let subs = resolve_subscriptions(&state, &did).await;

    // View: unread (default) | all | starred.
    let view = match q.view.as_deref() {
        Some("all") => "all",
        Some("starred") => "starred",
        _ => "unread",
    }
    .to_string();
    let list_view = list_view_of(q.view.as_deref());

    // Which feed URLs are in scope?
    let scope_urls = scope_urls_for(&subs, q.feed.as_deref(), q.folder.as_deref());
    // …and the feed ids they resolve to. Scope is applied inside the query now,
    // so a page is a page of rows the reader will actually see. Filtering after
    // a `LIMIT` would have made pages arbitrarily short — sometimes empty — for
    // any scope narrower than the whole subscription list.
    let scope_ids = scoped_feed_ids(&subs, &scope_urls);

    let feed_title_by_id = |id: i64| -> String {
        subs.iter()
            .find(|s| s.feed.as_ref().map(|f| f.id) == Some(id))
            .map(|s| {
                display_title(
                    s.sub
                        .title
                        .as_deref()
                        .or(s.feed.as_ref().and_then(|f| f.title.as_deref())),
                    &s.sub.url,
                )
            })
            .unwrap_or_default()
    };

    // **One page of the chosen view, filtered, ordered and bounded in SQL.**
    //
    // All three views used to materialize every matching entry — `SELECT e.*`,
    // no `LIMIT`, article bodies included — and the "all" view additionally ran
    // one such query PER SUBSCRIBED FEED and merged the results in memory. None
    // of the row fields below read the body. See `store::EntryListRow`.
    // **Saved records the cache cannot show.**
    //
    // The starred view is built from local `entries`, so a saved record whose
    // article was never cached here is invisible — the case that matters is
    // starring in ANOTHER atproto reader, which is the portability the shared
    // lexicon exists for. Those rows are rendered from the PDS record alone.
    let mut uncached: Vec<EntryRow> = Vec::new();
    if view == "starred" {
        // **Match against every SUBSCRIBED cached starred entry, not `source`.**
        //
        // `source` has already been filtered by feed/folder. Matching against it
        // meant an entry that IS cached but sits outside the current filter
        // looked uncached — so it rendered as a "not cached" row whose star
        // button deletes the PDS RECORD instead of un-starring the entry. A
        // scope filter must not change what is destroyed. Paging is the same
        // hazard in a new form: matching against the visible PAGE would make
        // every cached article outside it look uncached. Hence a dedicated
        // identity query over the whole starred set — urls and guids only, no
        // bodies — rather than reusing `source`.
        //
        // One gap remains BY DESIGN, and is handled at the other end. This query
        // still carries the `sub_ref` predicate, so a starred, cached entry in a
        // feed the reader has UNSUBSCRIBED from is absent here and its record
        // renders as uncached. That is the right rendering — the article is no
        // longer part of any feed the reader follows, and the PDS record is what
        // still holds it — but it means the un-save button is the record-deleting
        // one. `unsave_record` therefore clears the local star too, so the two
        // stores agree however the row got classified. Dropping the predicate
        // here instead would have made the row link to `/entries/{id}`, which is
        // `sub_ref`-scoped and would 404.
        //
        // **Three ways this can be unusable, and all three fail CLOSED.** With an
        // incomplete identity set, a cached article looks uncached and renders an
        // un-save button that deletes the PDS RECORD. Showing no uncached rows
        // loses rows for one render; getting this wrong loses data permanently,
        // so every uncertain case suppresses them.
        let identities = match store::starred_identities(pool, &did, STARRED_IDENTITY_MAX).await {
            Ok(store::StarredIdentities::All(rows)) => Some(rows),
            // The cap is a memory backstop, and reaching it means the set is an
            // arbitrary subset. It used to return that subset with no way to
            // tell, so every starred article outside it got the destructive
            // button.
            Ok(store::StarredIdentities::Truncated) => {
                warn!(
                    %did,
                    cap = STARRED_IDENTITY_MAX,
                    "cached-starred set exceeded its cap; suppressing uncached saved rows \
                     rather than rendering record-deleting buttons for cached articles"
                );
                None
            }
            Err(err) => {
                warn!(%err, %did, "cached-starred identity lookup failed; \
                                    suppressing uncached saved rows this render");
                None
            }
        };
        // The escape hatch asks whether this DID has ANY cached starred entry —
        // not whether the current SCOPE does. `total` is narrowed by
        // `?feed=`/`?folder=` while the identity set spans every feed, so
        // comparing them waved the fail-closed condition through for any narrow
        // scope: a record whose `feedUrl` matched the filter while its cached
        // entry lived under another feed rendered as uncached.
        let identities_ok = identities.is_some();
        let identities = identities.unwrap_or_default();
        let cached_urls: std::collections::HashSet<&str> = identities
            .iter()
            .filter_map(|(url, _)| url.as_deref())
            .collect();
        let cached_guids: std::collections::HashSet<&str> =
            identities.iter().map(|(_, guid)| guid.as_str()).collect();

        // Collected in full here, sliced per page later. They sort after every
        // cached row, so the two lists form one sequence that the pager walks —
        // see the slice below. Collected BEFORE the page is chosen because the
        // page count depends on how many there are.
        // Bounded like everything else on this page. These come from the PDS
        // (up to the 20,000-record list ceiling) and are appended whole to the
        // last page, so `ENTRIES_PER_PAGE` does not constrain them at all. The
        // cap is generous — a reader with more saved-elsewhere records than this
        // is not the case being designed for — but a response has to have a size
        // an operator can reason about.
        let mut uncached_dropped = 0usize;
        match state.repo().list_saved_sorted(&did).await {
            Ok(saved) if identities_ok => {
                for (rkey, item) in saved {
                    let known = cached_urls.contains(item.url.as_str())
                        || item
                            .entry_id
                            .as_deref()
                            .is_some_and(|g| cached_guids.contains(g));
                    if known {
                        continue;
                    }
                    // And the scope filter applies to these rows too. Without
                    // it, `?feed=X` still listed saved records from every other
                    // feed — the filter silently did nothing for them.
                    if let Some(urls) = &scope_urls {
                        match item.feed_url.as_deref() {
                            Some(feed_url) if urls.iter().any(|u| u == feed_url) => {}
                            // A saved record with no `feedUrl` cannot be placed
                            // in any feed's scope, so it belongs only to the
                            // unfiltered view.
                            _ => continue,
                        }
                    }
                    // **`safe_link` FIRST, and a failure no longer drops the row.**
                    //
                    // `item.url` is attacker-controlled — a saved record written
                    // by any client — and it lands in an `href`. Askama escapes
                    // HTML metacharacters but not SCHEMES, so `javascript:`
                    // survives escaping intact. This project already built the
                    // helper for exactly that, and `feed.rs` uses it on the
                    // equivalent link; this path was simply not routed through it.
                    //
                    // The real defect was what a failure DID: it `continue`d, so
                    // the row vanished entirely — no badge, no count, nothing —
                    // and the only trace was a `debug!` below any realistic
                    // filter. That makes the record unremovable FROM HERE, because
                    // the un-save button lives on the row; the reader has to open
                    // a different atproto client to get rid of it. A bad URL is a
                    // reason to withhold the LINK, not the row.
                    //
                    // The check also moved ABOVE the poll nudge. That is ordering
                    // hygiene rather than a fix: the nudge keys on `feed_url`, not
                    // on the URL being rejected here, and is already gated on the
                    // reader actually subscribing to that feed — so it was never
                    // reachable by an unusable `item.url`. Deciding whether a
                    // record is renderable before doing anything outbound on its
                    // behalf is simply the order that stays correct if either of
                    // those two facts later stops being true.
                    let link = SafeLink::external(&item.url);
                    if link.is_empty() {
                        warn!(
                            %did, %rkey,
                            "a saved record has an unusable URL; rendering it without a link \
                             so it can still be removed"
                        );
                    }

                    // Opportunistic re-fetch: if the reader still subscribes to
                    // the feed, make it due now. If the article is still inside
                    // the feed's window the poller caches it normally and this
                    // row becomes a real entry on its own — no synthetic rows in
                    // the shared cache, which every subscriber would otherwise
                    // see as a content-less entry.
                    // **Bound the WORK, not just the response.** This check sat
                    // after the nudge and the `subs` scan below, so every render
                    // still walked all ≤20,000 PDS records, ran a subs-length
                    // string scan per record, and issued up to that many
                    // `mark_feed_due` round-trips on a 5-connection pool — then
                    // discarded everything past the cap. A cap that runs after
                    // the expensive part is a cap on the output only.
                    if uncached.len() >= MAX_UNCACHED_SAVED_ROWS {
                        uncached_dropped += 1;
                        continue;
                    }
                    if let Some(feed_url) = item.feed_url.as_deref() {
                        if subs.iter().any(|s| s.sub.url == feed_url) {
                            // Bounded to one nudge per feed per poll interval —
                            // see `mark_feed_due`. Unbounded, a reload loop here
                            // becomes outbound amplification.
                            let stale_before = (chrono::Utc::now()
                                - chrono::Duration::from_std(state.config.poll_interval)
                                    .unwrap_or_else(|_| chrono::Duration::hours(1)))
                            .to_rfc3339_opts(chrono::SecondsFormat::Secs, true);
                            if let Err(err) =
                                store::mark_feed_due(pool, feed_url, &stale_before).await
                            {
                                tracing::debug!(%err, %feed_url, "could not nudge a feed for a saved article");
                            }
                        }
                    }
                    uncached.push(EntryRow {
                        id: 0,
                        title: item
                            .title
                            .clone()
                            .filter(|t| !t.trim().is_empty())
                            // Falling back to the URL is fine for a link we are
                            // willing to render, and wrong for one we are not:
                            // it would put the exact string `safe_link` just
                            // rejected into the page as the record's name. The
                            // rkey is what the un-save button acts on, so it is
                            // the honest identifier for a row that has nothing
                            // else trustworthy to show.
                            .unwrap_or_else(|| {
                                if link.is_empty() {
                                    format!("Saved item {rkey}")
                                } else {
                                    item.url.clone()
                                }
                            }),
                        feed_title: item.feed_url.clone().unwrap_or_default(),
                        published: display_date(Some(&item.created_at)),
                        read: false,
                        starred: true,
                        // Empty = "render this row without an anchor". The
                        // template branches on it, so the rejected URL never
                        // reaches an `href` even as an escaped string.
                        link,
                        cached: false,
                        rkey,
                    });
                }
            }
            // Identity lookup was unusable — see the fail-closed note above.
            Ok(_) => {}
            Err(err) => warn!(%err, %did, "could not list saved records from the PDS"),
        }
        if uncached_dropped > 0 {
            warn!(
                %did,
                dropped = uncached_dropped,
                cap = MAX_UNCACHED_SAVED_ROWS,
                "more saved records than this instance will hold in one response; the \
                 rest are not reachable from here"
            );
        }
    }

    // **One sequence, two sources.** The cached rows come from SQL, the uncached
    // PDS records follow them, and the pager walks the concatenation.
    //
    // The first version appended the uncached rows to the last page only and
    // kept them out of `total`, which left everything past a cap invisible AND
    // unremovable — the un-save button lives on the row, and there is no other
    // surface in the app that lists these. That is the same "unremovable FROM
    // HERE" hazard the `safe_link` fix above exists to prevent, reintroduced
    // forty lines later by a bound meant to protect memory.
    //
    // Paging the concatenation makes every record reachable and needs no cap on
    // what is RENDERED — one page is one page either way. The version before
    // that inflated `total` while clamping on the cached count, which advertised
    // a page the clamp could never reach; both numbers come from the same total
    // now, which is what makes that impossible rather than merely fixed.
    let total_cached =
        store::count_entries_for_view(pool, &did, list_view, scope_ids.as_deref()).await?;
    let uncached_len = uncached.len();
    let total = total_cached + uncached_len as i64;
    // Clamped to the range that exists. Past the end the list is empty, and the
    // empty state renders instead of the pager — which would strand a reader who
    // typed a page number, or who paged to the end and then marked entries read
    // out from under their own URL. Showing the last page is the answer to both.
    let page = i64::from(q.page.unwrap_or(1).max(1)).min(page_count_for(total));
    let offset = (page - 1) * ENTRIES_PER_PAGE;
    // Past the cached rows this returns nothing, which is exactly right: the
    // page is then made up entirely of uncached ones.
    let source = store::list_entries(
        pool,
        &did,
        list_view,
        scope_ids.as_deref(),
        ENTRIES_PER_PAGE,
        offset,
    )
    .await?;
    // **Both halves of the page are computed from the COUNT alone.**
    //
    // `total_cached` (a COUNT) and `source` (a SELECT) are separate unsynchronised
    // queries, so they can disagree about how many cached rows exist. Any part of
    // the page composition that reads `source.len()` inherits that disagreement.
    //
    // `cached_allotment` is this page's cached share according to the snapshot,
    // and it is what the uncached `skip`/`take` are derived from — so consecutive
    // pages tile the uncached list exactly, whichever way the count drifted.
    // `source` is then truncated to it only to avoid rendering rows the next page
    // will also claim.
    //
    // The previous version took `skip` from the count but `take` from
    // `source.len()`, which agreed only when the count UNDERSTATED. Overstating —
    // an un-star or a retention delete landing between the two queries — made
    // page N render `uncached[0..70]` while page N+1 rendered `uncached[50..80]`,
    // putting twenty rows, each carrying the record-DELETING un-save button, on
    // two pages at once. The comment claimed that shape was impossible; it was
    // merely rarer.
    let cached_allotment = (total_cached - offset).clamp(0, ENTRIES_PER_PAGE) as usize;
    let cached_here = cached_allotment.min(source.len());
    // Only compose when there is something to compose WITH. `uncached` is empty
    // on every view but `starred`, and truncating there just drops trailing rows
    // that no page then shows — the poller inserting between the COUNT and the
    // SELECT was enough to trigger it.
    let source = if uncached_len == 0 {
        &source[..]
    } else {
        &source[..cached_here]
    };
    let uncached_page: Vec<EntryRow> = {
        let skip = (offset - total_cached).max(0) as usize;
        let take = (ENTRIES_PER_PAGE as usize) - cached_allotment;
        uncached.into_iter().skip(skip).take(take).collect()
    };
    // This page's slice, used only to append below. The heading needs the
    // WHOLE-list figure, which is the set's size before slicing.
    let uncached_total = uncached_len as i64;

    // The scope/view suffix carried onto every entry link (built once).
    let entry_scope_qs = {
        let mut parts = Vec::new();
        if let Some(f) = q.feed.as_deref() {
            parts.push(format!("feed={}", qenc(f)));
        }
        if let Some(f) = q.folder.as_deref() {
            parts.push(format!("folder={}", qenc(f)));
        }
        if view != "unread" {
            parts.push(format!("view={}", qenc(&view)));
        }
        parts.join("&")
    };
    let entries: Vec<EntryRow> = source
        .iter()
        .map(|e| EntryRow {
            id: e.id,
            title: e
                .title
                .clone()
                .filter(|t| !t.trim().is_empty())
                .unwrap_or_else(|| "(untitled)".to_string()),
            feed_title: feed_title_by_id(e.feed_id),
            published: display_date(e.published.as_deref()),
            // Both bits ride along on the row's own `entry_state` join now. They
            // used to be membership tests against the full unread and starred
            // sets, which is why those two lists were fetched in their entirety
            // on every render even when the page showed a hundred rows.
            read: e.read,
            starred: e.starred,
            link: SafeLink::entry(e.id, &entry_scope_qs),
            cached: true,
            rkey: String::new(),
        })
        .collect();

    // The uncached slice for this page follows the cached rows.
    let mut entries = entries;
    entries.extend(uncached_page);
    let entries = entries;

    let selected_feed = q.feed.as_deref();
    let selected_folder = q.folder.as_deref();

    // Build the shared sidebar (folders + loose feeds, with unread counts).
    let (folder_views, loose_feeds, _folder_options) =
        build_sidebar(&state, &did, &subs, selected_feed, selected_folder).await;

    // Heading + scope query-string suffix.
    let (heading, scope_qs) = if let Some(feed_url) = selected_feed {
        let name = subs
            .iter()
            .find(|s| s.sub.url == feed_url)
            .map(|s| {
                display_title(
                    s.sub
                        .title
                        .as_deref()
                        .or(s.feed.as_ref().and_then(|f| f.title.as_deref())),
                    &s.sub.url,
                )
            })
            .unwrap_or_else(|| display_title(None, feed_url));
        (name, format!("feed={}", qenc(feed_url)))
    } else if let Some(folder_uri) = selected_folder {
        let name = folder_views
            .iter()
            .find(|f| f.uri == folder_uri)
            .map(|f| f.name.clone())
            .unwrap_or_else(|| "Folder".to_string());
        (name, format!("folder={}", qenc(folder_uri)))
    } else {
        let h = match view.as_str() {
            "all" => "All",
            "starred" => "Starred",
            _ => "Unread",
        };
        (h.to_string(), String::new())
    };

    let feed_scope = selected_feed.map(str::to_string);
    let nav = build_nav(&user, &view, scope_qs, folder_views, loose_feeds, false);

    // Pager links. `entry_scope_qs` already carries feed/folder/view, so the
    // page number is the only thing appended — which keeps a paged link
    // identical to an unpaged one in every other respect.
    let page_href = |n: i64| -> String {
        let mut parts = Vec::new();
        if !entry_scope_qs.is_empty() {
            parts.push(entry_scope_qs.clone());
        }
        if n > 1 {
            parts.push(format!("page={n}"));
        }
        if parts.is_empty() {
            "/".to_string()
        } else {
            format!("/?{}", parts.join("&"))
        }
    };
    let prev_href = (page > 1).then(|| page_href(page - 1));
    let next_href = (page * ENTRIES_PER_PAGE < total).then(|| page_href(page + 1));

    let tmpl = IndexTemplate {
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
        flash: q.flash.unwrap_or_default(),
        nav,
        entries,
        heading,
        feed_scope,
        total,
        // Whole-list figure, so it sits beside `total` without double counting.
        // The per-page slice is composed above and is not a heading number.
        uncached_total,
        page,
        page_count: page_count_for(total),
        prev_href,
        next_href,
    };
    Ok(render(&tmpl))
}

/// Query for `GET /manage` — carries an optional flash after an action redirect.
#[derive(Debug, Deserialize, Default)]
struct ManageQuery {
    #[serde(default)]
    flash: Option<String>,
}

/// `GET /manage` — the feed-management page. Renders the rail plus the subscribe
/// / your-feeds / OPML surfaces; the forms POST to the existing routes
/// (`/subscriptions`, `/folders`, `/opml`, …). A read/render route only — no
/// mutation logic of its own.
async fn manage(
    State(state): State<AppState>,
    headers: HeaderMap,
    Query(q): Query<ManageQuery>,
) -> Result<Response, WebError> {
    let user = match current_session(&state, &headers).await {
        Some(u) => u,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let did = user.did.clone();

    let subs = resolve_subscriptions(&state, &did).await;
    let (folder_views, loose_feeds, folder_options) =
        build_sidebar(&state, &did, &subs, None, None).await;

    // Clone the sidebar for the rail; the page body reuses folders/loose feeds.
    let nav = build_nav(
        &user,
        "unread",
        String::new(),
        folder_views.iter().map(clone_folder_view).collect(),
        loose_feeds.iter().map(clone_feed_view).collect(),
        true,
    );

    let tmpl = ManageTemplate {
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
        flash: q.flash.unwrap_or_default(),
        nav,
        folder_options,
        folders: folder_views,
        loose_feeds,
    };
    Ok(render(&tmpl))
}

/// Shallow clone helpers so `/manage` can hand the same sidebar to both the rail
/// (`Nav`) and the page body without an extra DB round-trip.
fn clone_feed_view(f: &FeedView) -> FeedView {
    FeedView {
        rkey: f.rkey.clone(),
        url: f.url.clone(),
        title: f.title.clone(),
        unread: f.unread,
        selected: f.selected,
        folder: f.folder.clone(),
    }
}

fn clone_folder_view(f: &FolderView) -> FolderView {
    FolderView {
        rkey: f.rkey.clone(),
        uri: f.uri.clone(),
        name: f.name.clone(),
        feeds: f.feeds.iter().map(clone_feed_view).collect(),
        selected: f.selected,
    }
}

/// The set of feed URLs a scope covers: `Some([one url])` for a single-feed
/// scope, `Some([urls…])` for a folder (its member feeds), or `None` for the
/// unscoped "everything" view. A folder scope takes the feed scope when both are
/// somehow present (feed wins, matching the query precedence elsewhere).
fn scope_urls_for(
    subs: &[ResolvedSub],
    feed: Option<&str>,
    folder: Option<&str>,
) -> Option<Vec<String>> {
    if let Some(feed_url) = feed {
        Some(vec![feed_url.to_string()])
    } else {
        folder.map(|folder_uri| {
            subs.iter()
                .filter(|s| s.sub.folder.as_deref() == Some(folder_uri))
                .map(|s| s.sub.url.clone())
                .collect()
        })
    }
}

/// The `at://` URI for a folder record given the owner DID + rkey.
fn folder_uri(did: &str, rkey: &str) -> String {
    format!("at://{did}/{}/{rkey}", lexicon::nsid::FOLDER)
}

/// Build the sidebar folder/loose-feed views (with per-feed unread counts) for a
/// DID — the shared source for both the reader index and the rail on every
/// chrome page. `selected_feed` / `selected_folder` drive `aria-current`.
async fn build_sidebar(
    state: &AppState,
    did: &str,
    subs: &[ResolvedSub],
    selected_feed: Option<&str>,
    selected_folder: Option<&str>,
) -> (Vec<FolderView>, Vec<FeedView>, Vec<FolderOption>) {
    let pool = &state.db;
    // Counted in SQL. This used to fetch every unread ENTRY — article bodies and
    // all — purely to `.filter().count()` them in Rust, on every page that
    // renders chrome, which made the sidebar the most frequently executed
    // instance of the unbounded-projection problem.
    let unread_counts = store::unread_counts_by_feed(pool, did)
        .await
        .unwrap_or_else(|err| {
            warn!(%err, %did, "sidebar unread counts failed; rendering zeroes");
            Default::default()
        });
    let folders = state
        .repo()
        .list_folders_sorted(did)
        .await
        .unwrap_or_default();

    let unread_count = |feed_id: Option<i64>| -> i64 {
        feed_id
            .and_then(|id| unread_counts.get(&id).copied())
            .unwrap_or(0)
    };
    let mk_feed_view = |s: &ResolvedSub| FeedView {
        rkey: s.rkey.clone(),
        url: s.sub.url.clone(),
        title: display_title(
            s.sub
                .title
                .as_deref()
                .or(s.feed.as_ref().and_then(|f| f.title.as_deref())),
            &s.sub.url,
        ),
        unread: unread_count(s.feed.as_ref().map(|f| f.id)),
        selected: selected_feed == Some(s.sub.url.as_str()),
        folder: s.sub.folder.clone(),
    };

    let mut folder_views = Vec::with_capacity(folders.len());
    for (rkey, folder) in &folders {
        let uri = folder_uri(did, rkey);
        let feeds: Vec<FeedView> = subs
            .iter()
            .filter(|s| s.sub.folder.as_deref() == Some(uri.as_str()))
            .map(mk_feed_view)
            .collect();
        folder_views.push(FolderView {
            rkey: rkey.clone(),
            uri: uri.clone(),
            name: folder.name.clone(),
            feeds,
            selected: selected_folder == Some(uri.as_str()),
        });
    }

    let known_uris: std::collections::HashSet<String> =
        folders.iter().map(|(r, _)| folder_uri(did, r)).collect();
    let loose_feeds: Vec<FeedView> = subs
        .iter()
        .filter(|s| {
            s.sub
                .folder
                .as_deref()
                .map(|f| !known_uris.contains(f))
                .unwrap_or(true)
        })
        .map(mk_feed_view)
        .collect();

    let folder_options: Vec<FolderOption> = folders
        .iter()
        .map(|(rkey, folder)| FolderOption {
            name: folder.name.clone(),
            uri: folder_uri(did, rkey),
        })
        .collect();

    (folder_views, loose_feeds, folder_options)
}

/// Assemble the shared rail [`Nav`] for a chrome page.
fn build_nav(
    user: &CurrentUser,
    view: &str,
    scope_qs: String,
    folders: Vec<FolderView>,
    loose_feeds: Vec<FeedView>,
    manage_active: bool,
) -> Nav {
    Nav {
        handle: display_handle(user.handle.as_deref(), &user.did),
        avatar: avatar_initials(user.handle.as_deref(), &user.did),
        view: view.to_string(),
        scope_qs,
        folders,
        loose_feeds,
        manage_active,
    }
}

// ---------------------------------------------------------------------------
// Reader: single entry
// ---------------------------------------------------------------------------

/// Query for `GET /entries/:id` — carries the reading context (scope + view) so
/// prev/next and "back" stay within the list the reader came from.
#[derive(Debug, Deserialize, Default)]
struct EntryQuery {
    #[serde(default)]
    feed: Option<String>,
    #[serde(default)]
    folder: Option<String>,
    #[serde(default)]
    view: Option<String>,
}

/// `GET /entries/:id` — the clean reader view for one entry, with prev/next
/// within the current reading list.
async fn entry_view(
    State(state): State<AppState>,
    headers: HeaderMap,
    Path(id): Path<i64>,
    Query(q): Query<EntryQuery>,
) -> Result<Response, WebError> {
    let user = match current_session(&state, &headers).await {
        Some(u) => u,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let did = user.did.clone();
    let pool = &state.db;

    // Resolve subscriptions FIRST: this refreshes the `sub_ref` projection so
    // the per-DID entry gate below authorizes against the caller's current PDS
    // subscription set (not another user's cached feeds).
    let subs = resolve_subscriptions(&state, &did).await;

    let entry = match get_entry_by_id(pool, &did, id).await? {
        Some(e) => e,
        None => return Ok((StatusCode::NOT_FOUND, "entry not found").into_response()),
    };

    let feed_title = feed_title_by_entry(pool, entry.feed_id).await;

    let read = entry_is_read(pool, &did, id).await?;
    let starred = entry_is_starred(pool, &did, id).await?;

    // Reconstruct the current list to compute prev/next, so paging in the reader
    // matches what the list showed.
    let (prev_id, next_id) = neighbors_in_scope(&state, &did, &q, id).await;

    let back_qs = scope_query(&q);

    let (folder_views, loose_feeds, _) =
        build_sidebar(&state, &did, &subs, q.feed.as_deref(), q.folder.as_deref()).await;
    let nav_view = match q.view.as_deref() {
        Some("all") => "all",
        Some("starred") => "starred",
        _ => "unread",
    };
    let nav = build_nav(
        &user,
        nav_view,
        back_qs.clone(),
        folder_views,
        loose_feeds,
        false,
    );

    let tmpl = EntryTemplate {
        version: VERSION,
        repo_url: REPO_URL,
        kofi_url: KOFI_URL,
        nav,
        id: entry.id,
        title: entry
            .title
            .clone()
            .filter(|t| !t.trim().is_empty())
            .unwrap_or_else(|| "(untitled)".to_string()),
        feed_title,
        author: entry.author.clone().filter(|a| !a.trim().is_empty()),
        published: display_date(entry.published.as_deref()),
        url: entry.url.as_deref().and_then(SafeLink::external_opt),
        content_html: entry.content_html.clone(),
        read,
        starred,
        back_qs,
        prev_id,
        next_id,
        oob: false,
    };
    Ok(render(&tmpl))
}

/// Compute the prev/next entry ids around `current` within the reader's current
/// scope + view, so the reader view can offer keyboard/paging navigation.
async fn neighbors_in_scope(
    state: &AppState,
    did: &str,
    q: &EntryQuery,
    current: i64,
) -> (Option<i64>, Option<i64>) {
    let idx_q = IndexQuery {
        feed: q.feed.clone(),
        folder: q.folder.clone(),
        view: q.view.clone(),
        // Neighbours span the whole list, not the page the reader arrived from.
        page: None,
        flash: None,
    };
    let ids = list_entry_ids(state, did, &idx_q).await;
    let pos = ids.iter().position(|&x| x == current);
    match pos {
        Some(p) => {
            let prev = if p > 0 { Some(ids[p - 1]) } else { None };
            let next = ids.get(p + 1).copied();
            (prev, next)
        }
        None => (None, None),
    }
}

/// The ordered entry ids for a scope + view — the same ordering `index` renders,
/// used for reader prev/next. Best-effort; PDS failures degrade to local cache.
async fn list_entry_ids(state: &AppState, did: &str, q: &IndexQuery) -> Vec<i64> {
    let pool = &state.db;
    let subs = resolve_subscriptions(state, did).await;

    let scope_urls = scope_urls_for(&subs, q.feed.as_deref(), q.folder.as_deref());

    // Ids only, and bounded. This used to fetch whole entries — bodies included
    // — for all three views and then throw everything but `id` away; the "all"
    // branch additionally ran one unbounded query PER FEED and sorted the union
    // in memory. Scope is now a feed-id restriction inside the query, so the
    // database does the filtering and the ordering exactly once.
    store::list_entry_ids(
        pool,
        did,
        list_view_of(q.view.as_deref()),
        scoped_feed_ids(&subs, &scope_urls).as_deref(),
        PREV_NEXT_MAX,
    )
    .await
    .unwrap_or_else(|err| {
        warn!(%err, %did, "prev/next id list failed; the reader loses its neighbour links");
        Vec::new()
    })
}

/// Map the `?view=` query value onto the store's list view. Anything
/// unrecognised is the unread default, matching `index`.
fn list_view_of(view: Option<&str>) -> store::ListView {
    match view {
        Some("all") => store::ListView::All,
        Some("starred") => store::ListView::Starred,
        _ => store::ListView::Unread,
    }
}

/// Translate a feed/folder scope into the feed ids to restrict a list query to.
///
/// `None` means unscoped (every subscribed feed). `Some(&[])` means the scope
/// matched no local feed, which must return nothing rather than everything — so
/// the empty vec is deliberately preserved, not collapsed back into `None`.
fn scoped_feed_ids(subs: &[ResolvedSub], scope_urls: &Option<Vec<String>>) -> Option<Vec<i64>> {
    let urls = scope_urls.as_ref()?;
    Some(
        subs.iter()
            .filter(|s| urls.contains(&s.sub.url))
            .filter_map(|s| s.feed.as_ref().map(|f| f.id))
            .collect(),
    )
}

/// Build a `?…` query string that preserves the reading scope + view for links.
fn scope_query(q: &EntryQuery) -> String {
    let mut parts = Vec::new();
    if let Some(f) = q.feed.as_deref() {
        parts.push(format!("feed={}", qenc(f)));
    }
    if let Some(f) = q.folder.as_deref() {
        parts.push(format!("folder={}", qenc(f)));
    }
    if let Some(v) = q.view.as_deref() {
        if v != "unread" {
            parts.push(format!("view={}", qenc(v)));
        }
    }
    parts.join("&")
}

// ---------------------------------------------------------------------------
// Mark read / unread
// ---------------------------------------------------------------------------

/// Form body for `POST /entries/:id/read`.
#[derive(Debug, Deserialize)]
struct ReadForm {
    #[serde(default)]
    read: Option<String>,
}

/// `POST /entries/:id/read` — toggle an entry's read-state for the current DID.
async fn mark_read(
    State(state): State<AppState>,
    Path(id): Path<i64>,
    headers: HeaderMap,
    Form(form): Form<ReadForm>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let pool = &state.db;

    let read = matches!(
        form.read.as_deref(),
        Some("true") | Some("1") | Some("on") | None
    );

    // Refresh the caller's `sub_ref` projection, then apply the AUTHORIZED
    // mutation: `mark_read` only writes when `did` subscribes to the entry's
    // feed. A non-subscriber gets a 404, never a mutation of someone else's
    // (or the shared cache's) state.
    resolve_subscriptions(&state, &did).await;
    if !store::mark_read(pool, &did, id, read).await? {
        return Ok((StatusCode::NOT_FOUND, "entry not found").into_response());
    }

    if !is_htmx(&headers) {
        return Ok(Redirect::to("/").into_response());
    }

    // The reader view swaps an out-of-band action-bar fragment (its `<li>` isn't
    // in the DOM), so its button's hidden value + aria-pressed update in place
    // and a second keypress can reverse the toggle. The list view swaps the row.
    if is_reader_request(&headers) {
        let starred = entry_is_starred(pool, &did, id).await?;
        return Ok(render(&EntryActionBarTemplate {
            id,
            read,
            starred,
            oob: true,
        }));
    }

    let row = build_entry_row(pool, &did, id, Some(read)).await?;
    match row {
        Some(r) => Ok(render(&EntryRowTemplate { e: r })),
        None => Ok((StatusCode::NOT_FOUND, "entry not found").into_response()),
    }
}

// ---------------------------------------------------------------------------
// Star / save
// ---------------------------------------------------------------------------

/// Form body for `POST /entries/:id/star`.
#[derive(Debug, Deserialize)]
struct StarForm {
    #[serde(default)]
    starred: Option<String>,
}

/// `POST /entries/:id/star` — star/unstar an entry.
///
/// Sets the local `starred` bit (fast working copy) and writes/removes a
/// `community.lexicon.rss.saved` record in the user's PDS (stars are worth
/// owning). The PDS write is best-effort — the local star still lands.
async fn toggle_star(
    State(state): State<AppState>,
    Path(id): Path<i64>,
    headers: HeaderMap,
    Form(form): Form<StarForm>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let pool = &state.db;

    let starred = matches!(
        form.starred.as_deref(),
        Some("true") | Some("1") | Some("on") | None
    );

    // Refresh the caller's `sub_ref` projection, then apply the AUTHORIZED
    // mutation: `mark_starred` only writes when `did` subscribes to the entry's
    // feed. A non-subscriber gets a 404, never a mutation.
    resolve_subscriptions(&state, &did).await;
    if !store::mark_starred(pool, &did, id, starred).await? {
        return Ok((StatusCode::NOT_FOUND, "entry not found").into_response());
    }

    // Reflect into the PDS saved-records collection. `get_entry_by_id` is scoped
    // to the caller's subscriptions, so this only ever acts on the caller's feed.
    if let Ok(Some(entry)) = get_entry_by_id(pool, &did, id).await {
        let entry_url = entry.url.clone().unwrap_or_default();
        if !entry_url.is_empty() {
            if starred {
                let mut saved = Saved::new(entry_url.clone(), now_rfc3339());
                saved.title = entry.title.clone();
                saved.feed_url = feed_url_for_id(pool, entry.feed_id).await;
                saved.entry_id = Some(entry.guid.clone());
                match state.repo().add_saved(&did, &saved).await {
                    Ok(rkey) => info!(%did, url = %entry_url, %rkey, "wrote saved record to PDS"),
                    Err(err) => warn!(%err, %did, "PDS saved write failed (starred locally)"),
                }
            } else {
                // Un-star: find and delete the matching saved record by URL.
                match state.repo().list_saved(&did).await {
                    Ok(records) => {
                        for (rkey, _rec) in records.iter().filter(|(_, r)| r.url == entry_url) {
                            if let Err(err) = state.repo().remove_saved(&did, rkey).await {
                                warn!(%err, %did, %rkey, "PDS saved delete failed");
                            }
                        }
                    }
                    Err(err) => warn!(%err, %did, "could not list saved records to un-star"),
                }
            }
        }
    }

    if !is_htmx(&headers) {
        return Ok(Redirect::to("/").into_response());
    }

    // Reader → out-of-band action-bar fragment; list → the row (see mark_read).
    if is_reader_request(&headers) {
        let read = entry_is_read(pool, &did, id).await?;
        return Ok(render(&EntryActionBarTemplate {
            id,
            read,
            starred,
            oob: true,
        }));
    }

    let row = build_entry_row(pool, &did, id, None).await?;
    match row {
        Some(r) => Ok(render(&EntryRowTemplate { e: r })),
        None => Ok((StatusCode::NOT_FOUND, "entry not found").into_response()),
    }
}

/// The feed URL for a cached feed id, if the row exists.
async fn feed_url_for_id(pool: &store::Pool, feed_id: i64) -> Option<String> {
    sqlx::query_scalar::<_, String>("SELECT url FROM feeds WHERE id = ?1")
        .bind(feed_id)
        .fetch_optional(pool)
        .await
        .ok()
        .flatten()
}

// ---------------------------------------------------------------------------
// Mark-all-read
// ---------------------------------------------------------------------------

/// Query for `POST /read-all` — an optional `?feed=<url>` scopes it to one feed;
/// absent means mark everything read.
#[derive(Debug, Deserialize, Default)]
struct ReadAllQuery {
    #[serde(default)]
    feed: Option<String>,
}

/// `POST /read-all` — mark every entry read for the current DID, optionally
/// scoped to one feed (mark-all-read per feed or globally).
async fn mark_all_read(
    State(state): State<AppState>,
    headers: HeaderMap,
    Query(q): Query<ReadAllQuery>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let pool = &state.db;

    // Refresh the caller's `sub_ref` projection so the scoped mark-read writes
    // only ever touch feeds this DID actually subscribes to.
    resolve_subscriptions(&state, &did).await;

    if let Some(feed_url) = q.feed.as_deref() {
        if let Ok(Some(feed)) = store::get_feed_by_url(pool, feed_url).await {
            store::mark_feed_read(pool, &did, feed.id, true).await?;
        }
        return Ok(Redirect::to(&format!("/?feed={}", qenc(feed_url))).into_response());
    }

    // Global: mark every subscribed feed read. Fan out over the DID's feeds
    // (bounded by the per-DID subscription cap) using the batched per-feed path,
    // rather than one UPDATE round-trip per unread entry (unbounded) — same end
    // state, but O(feeds) statements instead of O(unread entries).
    for feed_id in store::subscribed_feed_ids(pool, &did).await? {
        store::mark_feed_read(pool, &did, feed_id, true).await?;
    }
    Ok(Redirect::to("/").into_response())
}

// ---------------------------------------------------------------------------
// Subscribe by URL
// ---------------------------------------------------------------------------

/// Flash for a URL this instance cannot store as a feed — not private, just
/// not a kind of feed it supports (an `at://` publication with
/// `FEATHERREADER_STANDARD_SITE` off, an unsupported scheme). Distinct from
/// [`PRIVATE_FEED_REFUSAL`], whose "not saved or sent anywhere" would be a
/// false promise for a record that may already exist in the user's PDS.
const UNSUPPORTED_FEED_URL_REFUSAL: &str =
    "That isn't a kind of feed this instance can subscribe to. Nothing was saved.";

/// Refusal message shown when a private/paid feed is submitted. FeatherReader
/// stores subscriptions in the user's PUBLIC PDS, so it supports public feeds
/// only for now — a private feed's secret URL is never saved, fetched, or sent
/// anywhere. Kept as a constant so the add and OPML paths share the exact wording
/// and the boot-smoke can assert on it.
const PRIVATE_FEED_REFUSAL: &str = "Private/paid feeds aren't supported yet. \
    FeatherReader stores your subscriptions in your public PDS, so it supports public \
    feeds for now — private-feed support arrives when atproto's private data \
    (permissioned records) ships. Your feed URL was not saved or sent anywhere.";

/// Form body for `POST /subscriptions`.
#[derive(Debug, Deserialize)]
struct SubscribeForm {
    url: String,
    /// Optional folder `at://` URI to file the new feed under.
    #[serde(default)]
    folder: Option<String>,
}

/// `POST /subscriptions` — subscribe by URL.
async fn add_subscription(
    State(state): State<AppState>,
    headers: HeaderMap,
    Form(form): Form<SubscribeForm>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let pool = &state.db;
    let input = form.url.trim().to_string();
    if input.is_empty() {
        return Ok(Redirect::to("/").into_response());
    }

    // An `at://` paste is refused here, whatever the flag says: this path must
    // FETCH what was pasted to find the feed in it, and nothing fetches
    // `at://` until the standard.site reader is wired. Letting a well-formed
    // one through produced "Couldn't find a feed" and a `warn!` for an
    // expected condition; letting a malformed one reach the privacy arm, which
    // fails closed as `Private`, told the reader a typo was a paid feed. Only
    // `at://` is pre-checked — an http(s) or scheme-less paste keeps its
    // "Couldn't find a feed" path below, which is the accurate answer there.
    // Case-insensitive, unlike the storage guards: `Url::parse` folds the
    // scheme, so `AT://…` would otherwise skip both this and the classifier's
    // at:// arm, parse as `at`, and draw the private/paid flash off the rkey.
    // This decides a MESSAGE; nothing about storage keys off it.
    if input
        .get(..crate::atproto::AT_URI_PREFIX.len())
        .is_some_and(|p| p.eq_ignore_ascii_case(crate::atproto::AT_URI_PREFIX))
    {
        info!(url = %input, %did, "refused an at:// paste: the add path cannot fetch one (not stored)");
        return Ok(
            Redirect::to(&format!("/?flash={}", qenc(UNSUPPORTED_FEED_URL_REFUSAL)))
                .into_response(),
        );
    }

    // Block private/paid feeds BEFORE any fetch/resolve so a secret-bearing URL is
    // never even requested. Public feeds only until atproto permissioned data
    // ships; there is no override and nothing is stored or written.
    if let feed::FeedPrivacy::Private(reason) = feed::classify_feed_privacy(&input) {
        info!(url = %input, %reason, %did, "refused private/paid feed at add (not fetched or stored)");
        return Ok(
            Redirect::to(&format!("/?flash={}", qenc(PRIVATE_FEED_REFUSAL))).into_response(),
        );
    }

    // Per-DID subscription cap: bound one account's storage/poller footprint on
    // the small box. Checked BEFORE any fetch/resolve so an over-cap account
    // can't even trigger an outbound request. `<= 0` disables the cap.
    let cap = state.config.max_subs_per_did;
    if cap > 0 {
        match store::count_subscriptions_for_did(pool, &did).await {
            Ok(n) if n >= cap => {
                info!(%did, current = n, cap, "refused subscribe: per-DID subscription cap reached");
                return Ok(Redirect::to(&format!(
                    "/?flash={}",
                    qenc(&format!(
                        "Subscription limit reached ({cap}). Remove a feed before adding another."
                    ))
                ))
                .into_response());
            }
            Ok(_) => {}
            Err(err) => warn!(%err, %did, "could not count subscriptions for cap check; allowing"),
        }
    }

    let feed_url = match resolve_feed_url(&state.config, &input).await {
        Ok(u) => u,
        Err(err) => {
            warn!(%err, url = %input, "could not resolve a feed from the given URL");
            return Ok(Redirect::to(&format!(
                "/?flash={}",
                qenc("Couldn't find a feed at that URL")
            ))
            .into_response());
        }
    };

    // Defensive: resolution may have discovered a feed URL that itself carries a
    // secret (e.g. a public site page linking a tokened feed). Re-check the
    // resolved URL and refuse before storing/writing anything.
    if let feed::FeedPrivacy::Private(reason) = feed::classify_feed_privacy(&feed_url) {
        info!(url = %feed_url, %reason, %did, "refused private/paid feed after resolution (not stored)");
        return Ok(
            Redirect::to(&format!("/?flash={}", qenc(PRIVATE_FEED_REFUSAL))).into_response(),
        );
    }

    // The URL about to be STORED is what must be storable — not the one the
    // user typed. Autodiscovery already yields only http(s), but this is the
    // path that writes the row and the PDS record, so the check lives here too:
    // the same gate the OPML and rename paths apply, on the same terms.
    if !feed::is_storable_feed_url(&feed_url, state.config.standard_site) {
        info!(url = %feed_url, %did, "refused unsupported feed URL after resolution (not stored)");
        return Ok(
            Redirect::to(&format!("/?flash={}", qenc(UNSUPPORTED_FEED_URL_REFUSAL)))
                .into_response(),
        );
    }

    // Global feeds ceiling: a brand-new distinct feed is refused once the shared
    // cache is full (an existing/duplicate feed URL is always fine — it adds no
    // row). Bounds total cache size across all users on the box. `<= 0` disables.
    let feeds_cap = state.config.max_feeds_global;
    if feeds_cap > 0 && store::get_feed_by_url(pool, &feed_url).await?.is_none() {
        match store::count_feeds(pool).await {
            Ok(n) if n >= feeds_cap => {
                warn!(%did, feeds = n, cap = feeds_cap, feed = %feed_url, "refused subscribe: global feeds ceiling reached");
                return Ok(Redirect::to(&format!(
                    "/?flash={}",
                    qenc(
                        "This instance is at its feed capacity right now. Please try again later."
                    )
                ))
                .into_response());
            }
            Ok(_) => {}
            Err(err) => warn!(%err, "could not count feeds for global-cap check; allowing"),
        }
    }

    store::upsert_feed(
        pool,
        &store::NewFeed {
            url: feed_url.clone(),
            ..Default::default()
        },
    )
    .await?;

    if let Ok(client) = feed::build_client() {
        if let Some(feed_row) = store::get_feed_by_url(pool, &feed_url).await? {
            match feed::poll_feed(pool, &client, &feed_row, state.config.max_entries_per_feed).await
            {
                Ok(outcome) => {
                    info!(feed = %feed_url, ?outcome, "polled new subscription");
                    // **This path is not the scheduler, so it must settle the
                    // error columns itself.** `poll_feed` writes validators and
                    // `last_polled` and nothing else.
                    feed::settle_poll(pool, &feed_url, &outcome, state.config.poll_interval).await;
                }
                Err(err) => warn!(%err, feed = %feed_url, "initial poll failed"),
            }
        }
    }

    let mut sub = Subscription::new(feed_url.clone(), now_rfc3339());
    if let Ok(Some(feed_row)) = store::get_feed_by_url(pool, &feed_url).await {
        sub.title = feed_row.title.clone();
        sub.site_url = feed_row.site_url.clone();
    }
    sub.folder = form
        .folder
        .map(|f| f.trim().to_string())
        .filter(|f| !f.is_empty());

    match state.repo().add_subscription(&did, &sub).await {
        Ok(rkey) => info!(feed = %feed_url, %rkey, %did, "wrote subscription record to PDS"),
        Err(err) => {
            warn!(%err, feed = %feed_url, %did, "PDS subscription write failed (cached locally)")
        }
    }

    Ok(Redirect::to("/").into_response())
}

/// `POST /subscriptions/:rkey/delete` — unsubscribe (delete the PDS record).
async fn delete_subscription(
    State(state): State<AppState>,
    headers: HeaderMap,
    Path(rkey): Path<String>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    match state.repo().remove_subscription(&did, &rkey).await {
        Ok(()) => info!(%did, %rkey, "unsubscribed (deleted PDS subscription record)"),
        Err(err) => warn!(%err, %did, %rkey, "PDS unsubscribe failed"),
    }
    Ok(Redirect::to("/").into_response())
}

/// Form body for `POST /subscriptions/:rkey/rename`.
#[derive(Debug, Deserialize)]
struct RenameSubForm {
    url: String,
    #[serde(default)]
    title: Option<String>,
    #[serde(default)]
    site_url: Option<String>,
    #[serde(default)]
    folder: Option<String>,
}

/// `POST /subscriptions/:rkey/rename` — retitle a feed and/or move it to a
/// folder, rewriting the whole subscription record via `putRecord`.
async fn rename_subscription(
    State(state): State<AppState>,
    headers: HeaderMap,
    Path(rkey): Path<String>,
    Form(form): Form<RenameSubForm>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let feed_url = form.url.trim().to_string();

    // Reject an empty/blank resolved URL — a rename with no usable URL must not
    // write a junk row to the cache or a malformed subscription record to the
    // PDS (add_subscription refuses an empty input the same way).
    if feed_url.is_empty() {
        return Ok(Redirect::to("/").into_response());
    }

    // **Read before write — `update_subscription` is a `putRecord`, and a
    // putRecord replaces the WHOLE record** (see its doc on `atproto.rs`).
    //
    // This used to build a fresh `Subscription::new(feed_url, now_rfc3339())`
    // and hand that over, so every field the form does not carry was written
    // back as its default. `templates/manage_row.html` posts `url`, `title` and
    // `folder` — and nothing else — so a rename silently destroyed four fields:
    // `siteUrl`, `fetchHint`, `private`, and `createdAt`.
    //
    // `createdAt` is the one that matters most: it is the reader's subscribe
    // time, it is the sort key for "when did I subscribe", it lives in THEIR
    // repo rather than our cache, and once overwritten it is gone with nothing
    // in the UI to say so.
    //
    // There is no single-record read on `Repo` (no `getRecord`), so this lists
    // and filters. That is one extra round trip on an action that is already
    // doing a PDS write, and it is bounded; a `get_subscription` would be
    // strictly better if this ever measures badly.
    //
    // **A failed read refuses the rename.** Falling back to the old
    // rebuild-from-scratch here would reinstate the data loss on exactly the
    // flaky path, which is the worst place to have it. The write below already
    // takes this stance — "a failure here means nothing was renamed or moved" —
    // and the read gets the same one.
    let existing = match state.repo().list_subscriptions_sorted(&did).await {
        Ok(subs) => subs.into_iter().find(|(k, _)| *k == rkey).map(|(_, s)| s),
        Err(err) => {
            warn!(%err, %did, %rkey, "could not read the subscription before renaming it");
            return Ok(Redirect::to(&format!(
                "/?flash={}",
                qenc("Could not reach your PDS — nothing was renamed or moved.")
            ))
            .into_response());
        }
    };
    let Some(existing) = existing else {
        // The rkey is not in the reader's repo. Renaming a record that is not
        // there would CREATE one, which is not what "rename" means and would
        // give it a fresh `createdAt` — the bug this read exists to prevent.
        warn!(%did, %rkey, "refused rename: no such subscription in the repo");
        return Ok(Redirect::to(&format!(
            "/?flash={}",
            qenc("That subscription is no longer in your repo — nothing was renamed or moved.")
        ))
        .into_response());
    };

    // The subscription can be repointed at a different feed URL. **Every gate
    // on the URL applies to a repoint and only a repoint** — the three below
    // were each, at one time, run before this line on the URL as posted, and
    // each refused a pure retitle of a record that already existed:
    //
    // - privacy: the narrowed at:// arm fails closed as `Private` for an
    //   at-URI that is not a publication (a feed generator another client
    //   subscribed to), so the record became un-editable with a flash saying
    //   it "was not saved or sent anywhere";
    // - the global feeds ceiling keyed on "URL not in the cache", and an
    //   at:// record is never cached with the flag off, so at capacity a
    //   retitle was refused for a row the handler would not insert;
    // - storability, the same way.
    //
    // An unchanged URL is already in the reader's repo; refusing to retitle
    // it protects nothing and takes their own record away from them.
    // Like for like: the form value is trimmed, and a record another client
    // wrote may carry padding — compared raw, every retitle of it was a repoint.
    let url_changed = existing.url.trim() != feed_url;

    // **Storability, on the same terms as the add and OPML paths — for a
    // REPOINT, and FIRST.** A target this instance cannot store gets that
    // answer, not "private" (the at:// arm fails closed) or "at capacity"
    // (it would never be inserted) — the ordering the add path has. This handler writes `feeds` via `upsert_feed` and had only the
    // privacy check above, so `FEATHERREADER_STANDARD_SITE` was bypassable
    // here; a review found it by enumerating every writer of the table. The
    // first fix ran this check before the repo lookup, on the URL as posted —
    // which refused a pure retitle of a subscription that already IS an
    // at-URI, on every instance with the flag off. The flag gates what the
    // cache may store, not whether a reader may edit their own record: an
    // unchanged non-storable URL keeps its PDS write and simply gets no cache
    // row below.
    let storable = feed::is_storable_feed_url(&feed_url, state.config.standard_site);
    if url_changed && !storable {
        info!(url = %feed_url, %did, %rkey, "refused a repoint to a non-storable feed URL");
        return Ok(
            Redirect::to(&format!("/?flash={}", qenc(UNSUPPORTED_FEED_URL_REFUSAL)))
                .into_response(),
        );
    }

    // Block private/paid feeds on a repoint. `url` is attacker-controllable,
    // and rename both upserts it to the local cache AND rewrites the PDS
    // subscription record (a public `putRecord`), so without this guard a
    // crafted rename could land a secret-bearing URL in the public PDS — the
    // exact leak the add and OPML paths already prevent.
    if url_changed {
        if let feed::FeedPrivacy::Private(reason) = feed::classify_feed_privacy(&feed_url) {
            info!(url = %feed_url, %reason, %did, %rkey, "refused private/paid feed at rename (not stored or written)");
            return Ok(
                Redirect::to(&format!("/?flash={}", qenc(PRIVATE_FEED_REFUSAL))).into_response(),
            );
        }
    }

    // Global feeds ceiling parity with add_subscription: a repoint to a
    // brand-new feed URL would insert a NEW `feeds` row. Refuse that when the
    // shared cache is at capacity (an existing/duplicate URL adds no row and
    // is always fine). `<= 0` disables.
    let feeds_cap = state.config.max_feeds_global;
    if url_changed
        && feeds_cap > 0
        && store::get_feed_by_url(&state.db, &feed_url)
            .await?
            .is_none()
    {
        match store::count_feeds(&state.db).await {
            Ok(n) if n >= feeds_cap => {
                warn!(%did, %rkey, feeds = n, cap = feeds_cap, feed = %feed_url, "refused rename: global feeds ceiling reached");
                return Ok(Redirect::to(&format!(
                    "/?flash={}",
                    qenc(
                        "This instance is at its feed capacity right now. Please try again later."
                    )
                ))
                .into_response());
            }
            Ok(_) => {}
            Err(err) => warn!(%err, "could not count feeds for global-cap check; allowing"),
        }
    }

    let mut sub = existing;
    sub.url = feed_url;
    sub.title = form
        .title
        .map(|t| t.trim().to_string())
        .filter(|t| !t.is_empty());
    sub.folder = form
        .folder
        .map(|f| f.trim().to_string())
        .filter(|f| !f.is_empty());
    // `createdAt` and `private` carry over untouched — neither is a property of
    // which feed URL the subscription points at.
    //
    // `siteUrl` and `fetchHint` ARE properties of the specific feed, so a
    // repoint drops them rather than leaving a site link for the old feed
    // hanging off the new one. An explicit form value still wins if the form
    // ever starts carrying one.
    match form
        .site_url
        .map(|t| t.trim().to_string())
        .filter(|t| !t.is_empty())
    {
        Some(site) => sub.site_url = Some(site),
        None if url_changed => sub.site_url = None,
        None => {}
    }
    if url_changed {
        sub.fetch_hint = None;
    }

    // Keep the local cache title in step for the loose-feed fallback path —
    // for a row this instance would have. Two cases write nothing:
    //
    // - not storable (an existing at-URI with the flag off): the record is the
    //   reader's to edit, the cache row is not this instance's to create;
    // - an unchanged URL with no cache row: a retitle is never the write that
    //   CREATES a row. That covers two findings at once — the ceiling is
    //   checked on a repoint only, so a retitle must not insert past it; and
    //   a secret-bearing URL another client subscribed to has no row (the
    //   privacy gate above runs on a repoint only, and `resolve_subscriptions`
    //   refuses to cache it), so it cannot enter the shared table here, be
    //   polled, fail, and be printed on the admin page. A privacy re-check on
    //   this write was the first draft; mutation showed it dead — the row
    //   rule already refused every case it would have.
    let cache_write =
        storable && (url_changed || store::get_feed_by_url(&state.db, &sub.url).await?.is_some());
    if !cache_write {
        info!(%did, %rkey, url = %sub.url, "renamed a subscription without touching the cache");
    } else if let Err(err) = store::upsert_feed(
        &state.db,
        &store::NewFeed {
            url: sub.url.clone(),
            title: sub.title.clone(),
            site_url: sub.site_url.clone(),
            ..Default::default()
        },
    )
    .await
    {
        // Not fatal to the rename — the PDS record below is the source of truth
        // — but a missing `feeds` row means this subscription is never polled.
        warn!(%err, %did, url = %sub.url, "could not update the cached feed row on rename");
    }

    // **The PDS write decides what the reader is told.**
    //
    // This used to `warn!` on failure and then redirect exactly as it does on
    // success, so a rename that did not happen was indistinguishable from one
    // that did — the reader saw their old title come back and had no reason to
    // think anything had gone wrong. The PDS record IS the subscription; a
    // failure here means nothing was renamed or moved.
    match state.repo().update_subscription(&did, &rkey, &sub).await {
        Ok(res) => {
            info!(%did, %rkey, uri = %res.uri, "renamed/moved subscription");
            Ok(Redirect::to("/").into_response())
        }
        Err(err) => {
            warn!(%err, %did, %rkey, "PDS subscription update failed");
            Ok(Redirect::to(&format!(
                "/?flash={}",
                qenc("Could not save that change to your PDS — nothing was renamed or moved.")
            ))
            .into_response())
        }
    }
}

// ---------------------------------------------------------------------------
// Folders
// ---------------------------------------------------------------------------

/// Form body for `POST /folders`.
#[derive(Debug, Deserialize)]
struct FolderForm {
    name: String,
}

/// `POST /folders` — create a folder record.
async fn create_folder(
    State(state): State<AppState>,
    headers: HeaderMap,
    Form(form): Form<FolderForm>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let name = form.name.trim();
    if name.is_empty() {
        return Ok(Redirect::to("/").into_response());
    }
    let folder = Folder::new(name.to_string(), now_rfc3339());
    match state.repo().add_folder(&did, &folder).await {
        Ok(rkey) => info!(%did, %rkey, name, "created folder record"),
        Err(err) => warn!(%err, %did, "PDS folder create failed"),
    }
    Ok(Redirect::to("/").into_response())
}

/// `POST /folders/:rkey/rename` — rename a folder record.
async fn rename_folder(
    State(state): State<AppState>,
    headers: HeaderMap,
    Path(rkey): Path<String>,
    Form(form): Form<FolderForm>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let name = form.name.trim();
    if name.is_empty() {
        return Ok(Redirect::to("/").into_response());
    }
    let folder = Folder::new(name.to_string(), now_rfc3339());
    match state.repo().rename_folder(&did, &rkey, &folder).await {
        Ok(res) => info!(%did, %rkey, uri = %res.uri, "renamed folder"),
        Err(err) => warn!(%err, %did, %rkey, "PDS folder rename failed"),
    }
    Ok(Redirect::to("/").into_response())
}

/// `POST /folders/:rkey/delete` — delete a folder record (feeds referencing it
/// simply become un-foldered).
async fn delete_folder(
    State(state): State<AppState>,
    headers: HeaderMap,
    Path(rkey): Path<String>,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    match state.repo().remove_folder(&did, &rkey).await {
        Ok(()) => info!(%did, %rkey, "deleted folder record"),
        Err(err) => warn!(%err, %did, %rkey, "PDS folder delete failed"),
    }
    Ok(Redirect::to("/").into_response())
}

/// Resolve a user-pasted URL to a canonical feed URL: if fetching it yields a
/// feed document we take it as-is; if it yields an HTML page we run
/// autodiscovery over its `<link rel="alternate">` tags.
async fn resolve_feed_url(_config: &Config, input: &str) -> anyhow::Result<String> {
    let parsed =
        url::Url::parse(input).map_err(|e| anyhow::anyhow!("not a valid URL {input:?}: {e}"))?;

    let client = feed::build_client()?;
    // Fetch through the SSRF guard: scheme + resolved-IP checks on the URL and
    // every redirect hop, so a user-pasted URL can't reach cloud metadata /
    // loopback / private hosts.
    let resp = crate::net::guarded_get(&client, parsed.as_str(), &[]).await?;
    let final_url = resp.url().clone();
    let content_type = resp
        .headers()
        .get(axum::http::header::CONTENT_TYPE)
        .and_then(|v| v.to_str().ok())
        .unwrap_or("")
        .to_ascii_lowercase();
    // Cap the body (streamed, aborts over 8 MiB) — never trust Content-Length,
    // gzip strips it, and this response is reflected into the UI.
    let raw = crate::net::read_capped(resp).await?;
    let body = String::from_utf8_lossy(&raw).into_owned();

    let looks_like_feed = content_type.contains("xml")
        || content_type.contains("rss")
        || content_type.contains("atom")
        || content_type.contains("application/feed+json")
        || {
            let head = body.trim_start();
            head.starts_with("<?xml")
                || head.starts_with("<rss")
                || head.starts_with("<feed")
                || head.contains("<rss")
                || head.contains("<feed")
        };
    if looks_like_feed {
        return Ok(final_url.to_string());
    }

    match feed::discover_feed(&body, Some(&final_url)) {
        Some(u) => Ok(u.to_string()),
        None => anyhow::bail!("no feed found at {input} (no autodiscovery link)"),
    }
}

// ---------------------------------------------------------------------------
// Login (atproto OAuth via the sidecar)
// ---------------------------------------------------------------------------

/// Query for `GET /login`.
#[derive(Debug, Deserialize, Default)]
struct LoginQuery {
    #[serde(default)]
    handle: Option<String>,
    #[serde(default)]
    error: Option<String>,
    #[serde(default)]
    flash: Option<String>,
}

/// `GET /login` — start the atproto OAuth flow, or render the handle form.
///
/// **Pre-handshake gate:** starting OAuth (a `?handle=` GET) is refused unless
/// the visitor is allowed by [`may_start_oauth`] — an existing beta seat (via
/// session cookie *or* the submitted handle resolving to a seated DID) or a
/// valid reserving invite cookie. Refusal redirects to `/beta/redeem`. The bare
/// form (no handle) always renders.
async fn login_form(
    State(state): State<AppState>,
    headers: HeaderMap,
    Query(q): Query<LoginQuery>,
) -> Response {
    if let Some(handle) = q
        .handle
        .map(|h| h.trim().to_string())
        .filter(|h| !h.is_empty())
    {
        if !may_start_oauth(&state, &headers, &handle).await {
            return Redirect::to("/beta/redeem").into_response();
        }
        return start_oauth(&state, &handle).await;
    }
    render(&LoginTemplate {
        repo_url: REPO_URL,
        error: q.error.unwrap_or_default(),
        flash: q.flash.unwrap_or_default(),
    })
}

/// `POST /login` — the handle-form submit: redirect into the sidecar OAuth flow.
/// Subject to the same pre-handshake invite gate as `GET /login?handle=`.
async fn login_submit(
    State(state): State<AppState>,
    headers: HeaderMap,
    Form(form): Form<LoginForm>,
) -> Response {
    let handle = form.handle.trim();
    if handle.is_empty() {
        return login_error("Enter your atproto handle.");
    }
    if !may_start_oauth(&state, &headers, handle).await {
        return Redirect::to("/beta/redeem").into_response();
    }
    start_oauth(&state, handle).await
}

/// Whether this visitor is allowed to *start* the OAuth handshake. The gate
/// admits, in order of cost:
///
/// 1. an existing beta member's cookie session whose DID already holds a seat;
/// 2. a fresh visitor carrying a valid reserving invite cookie;
/// 3. a cookie-less visitor whose submitted `handle` resolves to a DID that
///    already holds a seat — this honors the **seeded admin's first login** on a
///    fresh deploy (and any returning member who cleared cookies) without a
///    session cookie or an invite code.
///
/// The cookie/invite fast paths run FIRST and short-circuit, so the network
/// handle→DID resolution is only attempted when neither applies. It fails
/// CLOSED: a malformed/unresolvable handle, a resolution error/timeout, or a
/// resolved DID with no seat all leave the visitor bounced to `/beta/redeem`.
/// This keeps the anti-abuse intent — a rando now pays a cheap handle
/// resolution instead of a burned sidecar handshake (and `/login` is already in
/// the rate-limited path set).
async fn may_start_oauth(state: &AppState, headers: &HeaderMap, handle: &str) -> bool {
    // The production resolver is the app's existing atproto handle→DID path,
    // routed through the SSRF guard. Resolution is injected so tests can exercise
    // the gate without a live network call (the guard forbids loopback mocks).
    may_start_oauth_with(state, headers, handle, |h| async move {
        crate::atproto::resolve_handle(&state.http, &state.config.resolver_base, &h)
            .await
            .ok()
    })
    .await
}

/// Core of [`may_start_oauth`] with the handle→DID resolver injected as `resolve`
/// (returning `Some(did)` on success, `None` on any failure/unresolvable handle).
/// The cookie + invite fast paths run FIRST and short-circuit, so `resolve` is
/// only called when neither admits — keeping the network round-trip off the hot
/// path and preserving the fail-closed contract on resolution failure.
async fn may_start_oauth_with<F, Fut>(
    state: &AppState,
    headers: &HeaderMap,
    handle: &str,
    resolve: F,
) -> bool
where
    F: FnOnce(String) -> Fut,
    Fut: std::future::Future<Output = Option<String>>,
{
    // 1. An already-beta'd session may re-auth freely.
    if let Some(did) = current_did(state, headers).await {
        if store::has_beta_access(&state.db, &did)
            .await
            .unwrap_or(false)
        {
            return true;
        }
    }
    // 2. A valid reserving invite cookie.
    if invite_cookie_code(headers, &state.config.cookie_secret).is_some() {
        return true;
    }
    // 3. Cookie-less: honor an existing seat by resolving the submitted handle to
    //    a DID (the seeded-admin first-login / cleared-cookies case). Fail closed
    //    on any resolution error or unresolvable/malformed handle.
    match resolve(handle.to_string()).await {
        Some(did) => store::has_beta_access(&state.db, &did)
            .await
            .unwrap_or(false),
        None => {
            warn!(%handle, "handle resolution failed in pre-handshake beta gate");
            false
        }
    }
}

/// Begin the OAuth handshake for `handle`, on whichever backend is live.
///
/// **On `form-action 'self'` and this redirect.** The Rust arm answers a form
/// POST with a redirect straight to the PDS — cross-origin — while the app's CSP
/// carries `form-action 'self'`. Browsers have historically disagreed about
/// whether that directive applies to redirects following a form submission, and
/// if it did here, login would break in a browser while every test passed.
///
/// It does not, and the evidence is the SIDECAR path, which is live in
/// production today: `POST /login` -> 303 to the same-origin `/oauth/login` ->
/// 302 to the PDS, cross-origin, under this same CSP. A browser checking the
/// whole redirect chain would already be blocking that. One checking only the
/// form's action URL sees `/login` in both cases. The two arms differ only in
/// how many same-origin hops precede the cross-origin one, so any policy that
/// permits the sidecar flow permits this one.
///
/// The two arms differ in SHAPE, not just in implementation. The sidecar owns
/// its own `/login` and its own callback, so starting a login is one redirect
/// and nothing is stored here. The Rust backend pushes the authorization
/// request itself, which means this app now holds the pending login — and must
/// set the browser-binding cookie that the callback will be checked against.
async fn start_oauth(state: &AppState, handle: &str) -> Response {
    match state.config.repo_backend {
        crate::metrics::Backend::Sidecar => {
            let url = state.sidecar.login_url(handle, None);
            info!(%handle, "redirecting to OAuth sidecar login");
            Redirect::to(&url).into_response()
        }
        crate::metrics::Backend::Rust => {
            let Some(runtime) = state.oauth.as_deref() else {
                warn!("the rust backend is live but its OAuth runtime is absent");
                return login_error("Login is not available right now.");
            };
            match crate::oauth::login::start(
                runtime,
                &state.http,
                &state.db,
                handle,
                crate::store::now_unix(),
            )
            .await
            {
                Ok(started) => {
                    info!(%handle, "pushed authorization request; redirecting to the PDS");
                    let mut resp = Redirect::to(&started.authorize_url).into_response();
                    set_cookie(
                        &mut resp,
                        &cookie::sign_value(
                            OAUTH_BINDING_COOKIE,
                            &started.binding_token,
                            &state.config.cookie_secret,
                            OAUTH_BINDING_MAX_AGE_SECS,
                        ),
                    );
                    resp
                }
                Err(err) => {
                    // The handle the user typed is logged; the error is not shown
                    // to them verbatim, since it can name internal hosts.
                    warn!(%err, %handle, "could not start the OAuth login");
                    login_error("Could not start login for that handle.")
                }
            }
        }
    }
}

/// Clear the browser-binding cookie. Called on every terminal outcome of a
/// callback, successful or not: the pending row is consumed either way, so a
/// lingering cookie can only ever match a login that no longer exists.
fn clear_binding_cookie(resp: &mut Response) {
    set_cookie(
        resp,
        &format!("{OAUTH_BINDING_COOKIE}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0"),
    );
}

/// Form body for `POST /login`.
#[derive(Debug, Deserialize)]
struct LoginForm {
    handle: String,
}

/// Query for `GET /oauth/callback`.
///
/// Carries BOTH shapes, because the two backends deliver different things to
/// the same URL: the sidecar hands back a one-shot `session_id` it has already
/// exchanged, while the PDS redirects here directly with `code`/`state`/`iss`
/// for this app to exchange itself. Which fields are populated is decided by
/// which backend started the login, not by which is live now — so a flip with a
/// login already in flight still lands in the right arm.
#[derive(Debug, Deserialize, Default)]
struct CallbackQuery {
    /// Sidecar backend: the handoff id.
    #[serde(default)]
    session_id: Option<String>,
    /// Rust backend: the authorization code and its envelope.
    #[serde(default)]
    code: Option<String>,
    #[serde(default)]
    state: Option<String>,
    #[serde(default)]
    iss: Option<String>,
    /// JARM, which is not supported — carried only so it can be refused
    /// explicitly rather than read as "no code".
    #[serde(default)]
    response: Option<String>,
    #[serde(default)]
    error: Option<String>,
    #[serde(default)]
    error_description: Option<String>,
}

/// `GET /oauth/callback` — establish the cookie session.
///
/// **Invite gate:** the verified DID must hold beta access. If it already does
/// (existing member / seeded admin) it's admitted directly. Otherwise we bind
/// the DID to the reserved invite cookie: `redeem_code` atomically consumes the
/// code and grants the seat. A DID with neither is bounced to `/beta/redeem`.
async fn oauth_callback(
    State(state): State<AppState>,
    headers: HeaderMap,
    Query(q): Query<CallbackQuery>,
) -> Response {
    // An error response is handled by the SAME arm that would have handled a
    // success, not short-circuited here.
    //
    // Returning early looks obviously right and is wrong on the Rust path: it
    // skips `verify_callback`, which validates `iss` BEFORE reporting the error
    // precisely because RFC 9207 §2.4 says a client "MUST NOT assume that the
    // error originates from the intended AS". It also leaves the pending row
    // unconsumed, so a `state` that has already produced a callback stays usable
    // until it expires.
    //
    // The sidecar arm has no such check to reach, so it is short-circuited
    // below, preserving exactly what it did before.
    // **The arm is chosen by what the SERVER knows, not by what the caller
    // sent.** A `session_id` in the query used to select the sidecar arm on its
    // own — so a caller could pick which code path ran, and the sidecar arm has
    // no browser-binding check at all. It also short-circuited the error path
    // below, skipping the `iss` validation.
    //
    // Requiring the Rust runtime to be absent, or a sidecar backend to be the
    // configured one, means the selection follows this deployment's own
    // configuration. A login started before a flip still completes, because the
    // Rust arm is reached whenever the Rust runtime exists and can match the
    // `state` against a pending row it actually wrote.
    // The sidecar hands off in TWO shapes, not one: `?session_id=…` on success
    // and `?error=…&error_description=…` on its own failure. Keying only on
    // `session_id` sent the failure shape down the Rust arm, which then failed
    // with "no `state`" and replaced the specific reason with a generic one —
    // and `error_description` is exactly what the sidecar Caddy routing matches
    // to send that request here in the first place.
    let sidecar_shape =
        q.session_id.as_deref().is_some_and(|s| !s.is_empty()) || q.error_description.is_some();
    let sidecar_handoff = sidecar_shape
        && (state.oauth.is_none() || state.config.repo_backend == crate::metrics::Backend::Sidecar);
    if let Some(err) = q.error.clone() {
        // **Neither the code nor the description is echoed as sent.**
        //
        // Both are server-controlled free text arriving on a public GET, so
        // anyone who can make a browser fetch this URL chooses them. The raw
        // `error` used to go into a `warn!` AND into the rendered login page,
        // and `error_description` — arbitrary text, newlines included — went
        // into the log verbatim: a log-injection surface on one side and
        // attacker-chosen copy in the product's own voice on the other.
        //
        // `oauth::flow` already decided this exact question for the Rust arm:
        // reduce the code to a known slug, drop the description entirely. That
        // reasoning is not specific to which arm handles the callback, and this
        // one simply never got the same treatment. The description's LENGTH is
        // kept, because "the server sent a 4 KB explanation" is occasionally
        // worth knowing and cannot be used to inject anything.
        let slug = crate::oauth::flow::known_error_slug(&err);
        warn!(
            error = slug,
            desc_len = q.error_description.as_deref().map_or(0, str::len),
            "OAuth callback returned an error"
        );
        if sidecar_handoff || state.oauth.is_none() {
            return login_error(&format!("Login failed: {slug}"));
        }
        // Fall through: the Rust arm consumes the pending row and validates
        // `iss` against it, and reports the failure afterwards.
    }

    // Which arm runs is decided by WHAT ARRIVED, not by which backend is
    // currently selected: a login started before a flip must still complete.
    let session = if sidecar_handoff {
        let session_id = q.session_id.clone().unwrap_or_default();
        match state.sidecar.resolve_session(&session_id).await {
            Ok(Some(s)) => s,
            Ok(None) => {
                warn!("OAuth callback session_id did not resolve (expired/unknown)");
                return login_error("Login session expired — please try again.");
            }
            Err(err) => {
                warn!(%err, "failed to resolve OAuth session via the sidecar");
                return login_error("Login failed talking to the auth service.");
            }
        }
    } else {
        let Some(runtime) = state.oauth.as_deref() else {
            warn!("an OAuth callback arrived with no sidecar session and no Rust runtime");
            return login_error("Login failed: this login could not be completed.");
        };
        let params = crate::oauth::flow::CallbackParams {
            code: q.code.clone(),
            state: q.state.clone(),
            iss: q.iss.clone(),
            // Passed through, NOT dropped: `verify_callback` checks `iss`
            // against the pending row's issuer before it reports the error, and
            // it cannot do that for an error it never sees.
            error: q.error.clone(),
            error_description: q.error_description.clone(),
            response: q.response.clone(),
        };
        let binding =
            cookie::verify_value(&headers, OAUTH_BINDING_COOKIE, &state.config.cookie_secret);
        match crate::oauth::login::complete(
            runtime,
            &state.http,
            &state.db,
            &params,
            binding.as_deref(),
            crate::store::now_unix(),
        )
        .await
        {
            Ok(done) => crate::atproto::SidecarSession {
                did: done.did,
                handle: done.handle,
            },
            Err(err) => {
                // Never echoed to the browser: the message can name the issuer,
                // the PDS, and why a binding check failed.
                warn!(%err, "could not complete the OAuth callback");
                let mut resp = login_error("Login failed — please try again.");
                clear_binding_cookie(&mut resp);
                return resp;
            }
        }
    };

    // Bind the verified DID to the invite gate. Returns a response only on the
    // (rare) failure paths; `Ok(())` means the DID now holds beta access.
    let mut clear_invite = false;
    if !store::has_beta_access(&state.db, &session.did)
        .await
        .unwrap_or(false)
    {
        // Not yet a member: consume the reserved invite code, if any.
        let code = match invite_cookie_code(&headers, &state.config.cookie_secret) {
            Some(c) => c,
            None => {
                warn!(did = %session.did, "OAuth callback with no beta access and no invite cookie");
                return Redirect::to("/beta/redeem").into_response();
            }
        };
        match store::redeem_code(
            &state.db,
            &code,
            &session.did,
            session.handle.as_deref(),
            state.config.beta_cap,
        )
        .await
        {
            Ok(Ok(())) => {
                clear_invite = true;
                info!(did = %session.did, "invite code redeemed at OAuth callback; beta access granted");
            }
            Ok(Err(policy)) => {
                warn!(did = %session.did, ?policy, "invite redeem failed at callback");
                let mut resp = redeem_bounce(&policy).into_response();
                // The reservation is spent/invalid — drop the stale invite cookie.
                clear_invite_cookie(&mut resp);
                return resp;
            }
            Err(err) => {
                warn!(%err, did = %session.did, "invite redeem infra error at callback");
                return login_error("Login failed while confirming your invite.");
            }
        }
    }

    // Mint an opaque, random server-side session id and store the identity under
    // it; the cookie carries the (HMAC-signed) sid, never the DID.
    let sid = state.sessions.create(Session {
        did: session.did.clone(),
        handle: session.handle.clone(),
    });
    let cookie = cookie::sign_session(&sid, &state.config.cookie_secret);
    info!(did = %session.did, handle = ?session.handle, "OAuth login OK; session cookie set");

    let mut resp = Redirect::to("/").into_response();
    set_cookie(&mut resp, &cookie);
    clear_binding_cookie(&mut resp);
    if clear_invite {
        clear_invite_cookie(&mut resp);
    }
    resp
}

/// Revoke a DID's OAuth session on BOTH backends, best-effort.
///
/// Not "whichever backend is live": during a cutover a user's tokens can be in
/// either store — they logged in under one backend and are logging out under
/// the other. Revoking only the live one would leave a live refresh token
/// behind in the other, which is the exact failure sign-out exists to prevent,
/// and it would be invisible because the sign-out itself looks successful.
///
/// Both arms are best-effort. The caller has already decided to sign the user
/// out, and a network failure must not trap them in a half-logged-out state.
/// How long sign-out will wait for a final read-state flush before revoking
/// anyway.
///
/// Bounded because the flush talks to the user's PDS, and a user trying to leave
/// must never be held by a server that is not answering. Three seconds is long
/// enough for a healthy `applyWrites` (the production samples run 100–970 ms)
/// and short enough that a dead PDS is an inconvenience rather than a trap.
const SIGN_OUT_FLUSH_BUDGET: std::time::Duration = std::time::Duration::from_secs(3);

/// Flush whatever read-state is still dirty for `did`, then give up quietly.
///
/// **Called before revoking, because revoking first strands it (#117).**
/// `revoke_everywhere` deletes the OAuth session, and a dirty cursor with no
/// session cannot be sent by anyone — it parks until the user signs in again,
/// which may be never. Flushing first is what stops the common case from
/// becoming that.
///
/// Best-effort by construction: every failure path here falls through to the
/// revoke. A flush that times out or errors leaves the cursors dirty, which is
/// the parked state the flusher now handles deliberately rather than retrying
/// forever.
async fn flush_before_revoke(state: &AppState, did: &str) {
    match tokio::time::timeout(
        SIGN_OUT_FLUSH_BUDGET,
        crate::readstate::flush_did(state, did),
    )
    .await
    {
        Ok(Ok(())) => {}
        Ok(Err(err)) => {
            warn!(%did, %err, "sign-out: final read-state flush failed; it will park until next sign-in")
        }
        Err(_) => warn!(
            %did,
            budget = ?SIGN_OUT_FLUSH_BUDGET,
            "sign-out: final read-state flush timed out; it will park until next sign-in"
        ),
    }
}

async fn revoke_everywhere(state: &AppState, did: &str) {
    // **Counted under Backend::Sidecar, not left uncounted.** A review found
    // that recording only the rust arm let `oauth_revoke` report a clean success
    // while every sidecar revocation failed — and for anyone who logged in before
    // the cutover, the sidecar store is the ONLY one that held tokens, so the
    // rust arm correctly returns NoSession and the metric reads all-clear while
    // live refresh tokens sit at the PDS.
    //
    // Same op name, different backend: the backend column is what distinguishes
    // them, so "no revocation failures" means checking both rows, not one.
    let sidecar_started = std::time::Instant::now();
    let sidecar_ok = match state.sidecar.revoke_session(did).await {
        Ok(res) => {
            info!(%did, revoked = res.revoked, "sidecar session revoked");
            true
        }
        Err(err) => {
            warn!(%did, %err, "sidecar revoke failed; continuing");
            false
        }
    };
    state.metrics.record(
        crate::metrics::Backend::Sidecar,
        "oauth_revoke",
        sidecar_started.elapsed().as_micros() as u64,
        sidecar_ok,
    );

    if let Some(runtime) = state.oauth.as_deref() {
        let revoke_started = std::time::Instant::now();
        let outcome = crate::oauth::revoke::sign_out_discovering(
            runtime,
            &state.http,
            &state.db,
            did,
            crate::store::now_unix(),
        )
        .await;
        // **Counted, because a warn! nobody reads is not observability.** Until
        // this existed, a revocation failure left exactly one trace: a log line.
        // "No revocation failures this week" was therefore a statement about
        // nobody having looked, which is not the same claim.
        //
        // NoSession counts as a SUCCESS, deliberately. Logout is idempotent —
        // there being nothing to revoke is the correct outcome, not a failure,
        // and counting it as an error would make the metric noisy in exactly
        // the case that is fine. Only `Failed` means the PDS still holds live
        // tokens we asked it to drop.
        let revoke_ok = !matches!(outcome, crate::oauth::revoke::Revocation::Failed(_));
        state.metrics.record(
            crate::metrics::Backend::Rust,
            "oauth_revoke",
            revoke_started.elapsed().as_micros() as u64,
            revoke_ok,
        );
        match outcome {
            crate::oauth::revoke::Revocation::Revoked => {
                info!(%did, "rust OAuth session revoked at the PDS")
            }
            crate::oauth::revoke::Revocation::NoSession => {}
            crate::oauth::revoke::Revocation::Failed(reason) => {
                warn!(%did, %reason, "rust OAuth revoke failed; the local session is gone regardless")
            }
        }
    }
}

/// `POST /logout` — end the session everywhere, not just in this browser.
///
/// Clearing the cookie only stops *this* device from presenting the session;
/// the sidecar still holds live OAuth tokens for the DID. So logout now also
/// calls the sidecar `POST /internal/revoke {did}`, which revokes the refresh +
/// access tokens at the PDS and drops the sidecar's session rows. The local
/// registry entry is dropped and the cookie cleared regardless of whether the
/// revoke round-trip succeeds (best-effort — a network blip must not trap the
/// user in a half-logged-out state).
async fn logout(State(state): State<AppState>, headers: HeaderMap) -> Response {
    if let Some(user) = current_session(&state, &headers).await {
        // Only a real cookie session (`sid` present) has sidecar-held tokens to
        // revoke; the dev-DID fallback never handshook the sidecar.
        if let Some(sid) = user.sid {
            state.sessions.remove(&sid);
            // BEFORE the revoke: afterwards there is no session to send it with.
            flush_before_revoke(&state, &user.did).await;
            revoke_everywhere(&state, &user.did).await;
        }
    }
    let mut resp = Redirect::to("/login").into_response();
    set_cookie(
        &mut resp,
        &format!("{SESSION_COOKIE}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0"),
    );
    resp
}

/// Form body for `POST /account/delete` — the confirm-gate. The user must type
/// `DELETE` into this field for the purge to run.
#[derive(Debug, Deserialize)]
struct DeleteAccountForm {
    #[serde(default)]
    confirm: String,
}

/// The literal a user must type to confirm the destructive delete.
const DELETE_CONFIRM_PHRASE: &str = "DELETE";

/// `POST /account/delete` (authed) — the "delete my data" endpoint.
///
/// Confirm-gated: the form must carry `confirm=DELETE` or we bounce back to
/// `/manage` with an explanatory flash and touch nothing. On confirmation it:
///   1. purges **every** local row owned by the caller DID (`entry_state`,
///      `read_cursor`, `sub_ref`, `beta_access` seat, and any invite codes the
///      DID created) via [`store::purge_did_data`], then
///   2. calls the sidecar `POST /internal/revoke {did}` so the OAuth tokens are
///      revoked at the PDS and the sidecar's session rows are dropped, then
///   3. drops the in-memory session and clears the cookie, signing the user out.
///
/// The subscription/folder/saved *records* in the user's own PDS are
/// intentionally left alone — they are the user's data on their own server; the
/// `/about` copy and this page's UI both say so, and export stays available.
async fn account_delete(
    State(state): State<AppState>,
    headers: HeaderMap,
    Form(form): Form<DeleteAccountForm>,
) -> Result<Response, WebError> {
    let user = match current_session(&state, &headers).await {
        Some(u) => u,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let did = user.did.clone();

    // Confirm-gate: require the exact typed phrase before doing anything.
    if form.confirm.trim() != DELETE_CONFIRM_PHRASE {
        return Ok(Redirect::to(&format!(
            "/manage?flash={}",
            qenc("Type DELETE to confirm — nothing was deleted.")
        ))
        .into_response());
    }

    // 1. Purge every local row this DID owns (single transaction).
    let counts = store::purge_did_data(&state.db, &did).await?;
    info!(
        %did,
        total = counts.total(),
        entry_state = counts.entry_state,
        read_cursor = counts.read_cursor,
        sub_ref = counts.sub_ref,
        beta_access = counts.beta_access,
        invite_codes = counts.invite_codes,
        "account/delete: local rows purged"
    );

    // 2. Revoke the OAuth session at the sidecar/PDS (best-effort — the local
    //    rows are already gone; a network blip must not block the sign-out).
    revoke_everywhere(&state, &did).await;

    // 3. Drop the in-memory session and clear the cookie: sign the user out.
    if let Some(sid) = user.sid {
        state.sessions.remove(&sid);
    }
    let mut resp = Redirect::to(&format!(
        "/login?flash={}",
        qenc("Your data was deleted and you've been signed out. Thanks for trying FeatherReader.")
    ))
    .into_response();
    set_cookie(
        &mut resp,
        &format!("{SESSION_COOKIE}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0"),
    );
    Ok(resp)
}

/// Re-render the login form with an error banner.
fn login_error(msg: &str) -> Response {
    render(&LoginTemplate {
        repo_url: REPO_URL,
        error: msg.to_string(),
        flash: String::new(),
    })
}

// ---------------------------------------------------------------------------
// Closed-beta invite gate (self-serve redeem + admin mint)
// ---------------------------------------------------------------------------

/// Form body for `POST /beta/redeem`.
#[derive(Debug, Deserialize)]
struct RedeemForm {
    code: String,
}

/// `GET /beta/redeem` — render the invite-redeem page. If the seat cap is
/// already full we render the "capacity full" variant (no form).
async fn beta_redeem_form(State(state): State<AppState>) -> Response {
    let full = store::count_beta_access(&state.db)
        .await
        .map(|n| n >= state.config.beta_cap)
        .unwrap_or(false);
    render(&BetaRedeemTemplate {
        repo_url: REPO_URL,
        error: String::new(),
        capacity_full: full,
    })
}

/// `POST /beta/redeem` — the **pre-handshake** reservation.
///
/// Validates the pasted code is *redeemable right now* (exists, active,
/// unexpired, and a seat is free) WITHOUT consuming it or binding a DID — the
/// visitor has no DID yet. On success it sets a short-lived signed invite cookie
/// reserving intent to redeem this code, then sends the visitor to `/login`. The
/// OAuth callback later binds the verified DID and atomically consumes the code
/// (`store::redeem_code`). This ordering means a non-invited visitor can never
/// start OAuth (and burn a sidecar handshake).
async fn beta_redeem_submit(
    State(state): State<AppState>,
    Form(form): Form<RedeemForm>,
) -> Response {
    let code = form.code.trim().to_uppercase();
    if code.is_empty() {
        return render(&BetaRedeemTemplate {
            repo_url: REPO_URL,
            error: "Enter your invite code.".to_string(),
            capacity_full: false,
        });
    }

    match preflight_code(&state, &code).await {
        Ok(()) => {
            let cookie = sign_invite(&code, &state.config.cookie_secret);
            let mut resp = Redirect::to("/login").into_response();
            set_cookie(&mut resp, &cookie);
            info!("invite code preflight OK; reserving intent + redirecting to /login");
            resp
        }
        Err(policy) => {
            warn!(?policy, "invite code preflight rejected");
            redeem_bounce(&policy)
        }
    }
}

/// Read-only preflight of an invite code for the pre-handshake reservation:
/// verify it exists, is active, is not past `expires_at`, and that a seat is
/// free — mirroring the checks `store::redeem_code` will re-run atomically at
/// callback time. Does NOT consume the code or grant a seat. Returns the same
/// typed [`store::RedeemError`] variants so the two paths share one message map.
async fn preflight_code(state: &AppState, code: &str) -> Result<(), store::RedeemError> {
    // Cap check first: a clear "capacity full" beats "code invalid" when both.
    // FAIL CLOSED on a count error — an `unwrap_or(0)` would let a DB blip read as
    // "0 seats used" and wave the redeem through the preflight. (`redeem_code`
    // still backstops the real cap inside its tx, so this is a consistency /
    // defence-in-depth fix, not the only guard.) Treat an unverifiable count as
    // capacity-full: the redeemer sees "at capacity, try later" rather than a mint
    // that might overrun the cap.
    let count = match store::count_beta_access(&state.db).await {
        Ok(n) => n,
        Err(err) => {
            warn!(%err, "preflight_code: count_beta_access failed; failing closed");
            return Err(store::RedeemError::CapacityFull);
        }
    };
    if count >= state.config.beta_cap {
        return Err(store::RedeemError::CapacityFull);
    }
    // Look up the code's current status + expiry (read-only).
    let row = sqlx::query_as::<_, (String, i64)>(
        "SELECT status, expires_at FROM invite_codes WHERE code = ?1",
    )
    .bind(code)
    .fetch_optional(&state.db)
    .await
    .ok()
    .flatten();
    let (status, expires_at) = match row {
        Some(r) => r,
        None => return Err(store::RedeemError::NotFound),
    };
    let now = chrono::Utc::now().timestamp();
    match status.as_str() {
        "active" if expires_at >= now => Ok(()),
        "active" => Err(store::RedeemError::Expired),
        "expired" => Err(store::RedeemError::Expired),
        // "redeemed" or anything else non-active.
        _ => Err(store::RedeemError::AlreadyRedeemed),
    }
}

/// Map a [`store::RedeemError`] to the invite page with the right message. Used
/// by both the preflight (`POST /beta/redeem`) and the callback bind path.
fn redeem_bounce(policy: &store::RedeemError) -> Response {
    use store::RedeemError::*;
    let (msg, capacity_full) = match policy {
        NotFound => ("That invite code isn't valid.", false),
        Expired => ("That invite code has expired.", false),
        AlreadyRedeemed => ("That invite code has already been used.", false),
        CapacityFull => ("", true),
    };
    render(&BetaRedeemTemplate {
        repo_url: REPO_URL,
        error: msg.to_string(),
        capacity_full,
    })
}

/// Query for `POST /admin/invites` — how many codes to mint (`?n=`, default 1).
#[derive(Debug, Deserialize, Default)]
struct MintQuery {
    #[serde(default)]
    n: Option<u32>,
}

/// `POST /admin/invites?n=N` — mint N invite codes.
///
/// `GET /oauth/client-metadata.json` — the client's published identity.
///
/// **This URL IS the `client_id`.** The PDS fetches it during every login and
/// caches it against every existing grant, so it must keep answering at exactly
/// this path across the cutover — the sidecar serves the same document at the
/// same URL today, proxied by the edge.
///
/// Served whatever backend is live: a request that arrives here is from a PDS
/// resolving our identity, and it has no idea which of our two implementations
/// is currently answering repo calls.
async fn oauth_client_metadata(State(state): State<AppState>) -> Response {
    let Some(runtime) = state.oauth.as_deref() else {
        // The sidecar is serving this path in front of us, or nothing is.
        return (StatusCode::NOT_FOUND, "no client metadata\n").into_response();
    };
    axum::Json(crate::oauth::metadata::client_metadata(&runtime.client)).into_response()
}

/// `GET /oauth/jwks.json` — the client's public signing key.
///
/// Production only. The localhost dev client is a PUBLIC client: it registers no
/// key and signs no assertions, so publishing a JWKS there would advertise a
/// credential that is never used — and would make a dev deployment look like a
/// confidential client to anyone reading it.
async fn oauth_jwks(State(state): State<AppState>) -> Response {
    let Some(runtime) = state.oauth.as_deref() else {
        return (StatusCode::NOT_FOUND, "no jwks\n").into_response();
    };
    match runtime.client_key.as_ref() {
        Some(key) => match key.jwks_document() {
            Ok(doc) => axum::Json(doc).into_response(),
            Err(err) => {
                warn!(%err, "could not render the client JWKS");
                (StatusCode::INTERNAL_SERVER_ERROR, "jwks unavailable\n").into_response()
            }
        },
        None => (StatusCode::NOT_FOUND, "this client publishes no jwks\n").into_response(),
    }
}

/// How many failing feeds `/admin/metrics` will name. One response, so bounded.
const ADMIN_FAILING_FEED_LIMIT: i64 = 200;

/// `GET /admin/metrics` — repo-op latency for both backends, as plain text.
///
/// Admin-gated on the same rule as the invite minter: the table names every
/// operation the reader performs and how often each fails, which is an
/// operational picture rather than public information.
///
/// Text, not JSON or HTML: it is read by a person deciding whether the cutover
/// is safe, and the comparison is two rows side by side.
async fn admin_metrics(State(state): State<AppState>, headers: HeaderMap) -> Response {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return (StatusCode::UNAUTHORIZED, "sign in first\n").into_response(),
    };
    if !state.config.admin_seed_dids().iter().any(|d| d == &did) {
        warn!(%did, "admin metrics denied: not an admin-seed DID");
        return (StatusCode::FORBIDDEN, "not an admin\n").into_response();
    }

    // Flush first, so the table includes this process's traffic up to now.
    // Then read the PERSISTED rows, which is the only place both backends can
    // appear at once -- a flip is a restart, and in-process memory only ever
    // holds the backend currently running.
    if let Err(err) =
        crate::metrics::flush(&state.metrics, &state.db, crate::store::now_unix()).await
    {
        warn!(%err, "could not flush repo timings before rendering");
    }
    let rows = match crate::metrics::persisted_rows(&state.db).await {
        Ok(rows) => rows,
        Err(err) => {
            warn!(%err, "could not read persisted repo timings");
            return (StatusCode::INTERNAL_SERVER_ERROR, "metrics unavailable\n").into_response();
        }
    };

    // The live backend is named at the top: a table of two populated rows is
    // ambiguous about which one is currently serving users.
    // Parked read-state, alongside the timings. The flusher no longer logs
    // these every round (#117), so without a number here the state would be
    // silent — which is the failure the noisy loop at least did not have.
    let parked = match crate::store::parked_readstate_dids(&state.db).await {
        Ok(n) => n.to_string(),
        Err(err) => {
            warn!(%err, "could not count parked read-state DIDs");
            "unknown".to_string()
        }
    };
    // **The half the public histogram cannot carry.** `/stats` reports counts by
    // cause and nothing else, deliberately — but `fetch` covers DNS failure,
    // timeout, SSRF refusal AND this reader's own bugs, so the count alone
    // cannot separate "the publishers are gone" from "we are broken". #159 was
    // the latter and took a production investigation to establish. Named feeds
    // and their error text belong here, behind ALLOWED_DIDS.
    let failing = match crate::store::failing_feeds(&state.db, ADMIN_FAILING_FEED_LIMIT).await {
        Ok(f) => f,
        Err(err) => {
            warn!(%err, "could not list failing feeds");
            Vec::new()
        }
    };
    let mut failing_block = String::new();
    if !failing.is_empty() {
        failing_block.push_str("\nfailing feeds (worst first)\n");
        for f in &failing {
            failing_block.push_str(&format!(
                "  {:>4}x  {:<8}  {}\n          {}\n",
                f.consecutive_errors,
                f.kind.as_deref().unwrap_or("unknown"),
                f.url,
                f.detail.as_deref().unwrap_or("(no detail recorded)"),
            ));
        }
    }

    let body = format!(
        "live backend: {}\nparked read-state DIDs: {}\n\n{}{}",
        state.config.repo_backend.as_str(),
        parked,
        crate::metrics::render(&rows),
        failing_block,
    );
    (StatusCode::OK, body).into_response()
}

/// Authorized ONLY for a live session whose DID is in the `ALLOWED_DIDS` admin
/// seed (`config.admin_seed_dids`). Returns the freshly-minted codes as
/// newline-separated `text/plain`. Deliberately minimal (no HTML UI).
async fn admin_mint_invites(
    State(state): State<AppState>,
    headers: HeaderMap,
    Query(q): Query<MintQuery>,
) -> Response {
    // Require a real, current session (not just a DID string) whose DID is an
    // admin-seed DID. `current_did` already re-checks the beta gate.
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return (StatusCode::UNAUTHORIZED, "sign in first\n").into_response(),
    };
    if !state.config.admin_seed_dids().iter().any(|d| d == &did) {
        warn!(%did, "admin mint denied: not an admin-seed DID");
        return (StatusCode::FORBIDDEN, "not an admin\n").into_response();
    }

    let n = q.n.unwrap_or(1).clamp(1, 100);
    let mut codes = Vec::with_capacity(n as usize);
    for _ in 0..n {
        match store::mint_code(&state.db, &did, INVITE_TTL_SECS).await {
            Ok(code) => codes.push(code),
            Err(err) => {
                warn!(%err, %did, "admin mint_code failed");
                return (StatusCode::INTERNAL_SERVER_ERROR, "mint failed\n").into_response();
            }
        }
    }
    info!(%did, count = codes.len(), "admin minted invite codes");
    let mut body = codes.join("\n");
    body.push('\n');
    (StatusCode::OK, body).into_response()
}

// ---------------------------------------------------------------------------
// Bot claim link: /claim?t=<token>  +  POST /bot/claims (shared-secret mint)
// ---------------------------------------------------------------------------

/// Query for `GET /claim`.
#[derive(Debug, Deserialize)]
struct ClaimQuery {
    /// The opaque claim token from the bot's public follow-back skeet.
    t: Option<String>,
}

/// `GET /claim?t=<token>` — redeem a bot-issued claim link.
///
/// The follow→invite bot posts a public skeet mentioning a new follower with a
/// link here. The token wraps a pre-minted invite code (never the raw code — see
/// [`sign_claim_token`]). On a valid, still-redeemable token this behaves exactly
/// like a successful `POST /beta/redeem`: it sets the reserving `fr_invite`
/// cookie and sends the visitor to `/login`, so they flow through OAuth and the
/// callback atomically consumes the code (`store::redeem_code`) — the same
/// machinery as a pasted code. On any failure it bounces to the invite page with
/// the matching message.
///
/// Single-use / grabbability: a token in a public URL is grabbable. The code it
/// wraps is single-use (redeem flips `active→redeemed`), and `preflight_code`
/// here rejects an already-used / expired / capacity-full code before reserving,
/// so a replayed link past the first successful claim is refused. The residual
/// window is the same as any pasted invite code: whoever completes OAuth *first*
/// with a live reservation wins the seat. The per-IP rate limit on `/claim`
/// blunts brute-force enumeration.
async fn claim(State(state): State<AppState>, Query(q): Query<ClaimQuery>) -> Response {
    let token = match q.t {
        Some(t) if !t.is_empty() => t,
        _ => {
            warn!("claim link with no token");
            return redeem_bounce(&store::RedeemError::NotFound);
        }
    };

    // Unwrap the token → the invite code it reserves. A tampered/forged token
    // yields nothing → treat as an invalid code (don't leak whether it parsed).
    let code = match claim_token_code(&token, &state.config.cookie_secret) {
        Some(c) => c,
        None => {
            warn!("claim token invalid (bad signature / malformed)");
            return redeem_bounce(&store::RedeemError::NotFound);
        }
    };

    // Re-run the same preflight as the pasted-code path: exists, active,
    // unexpired, seat free. This is what makes a replayed link past first-claim
    // (or past cap) fail cleanly.
    match preflight_code(&state, &code).await {
        Ok(()) => {
            let cookie = sign_invite(&code, &state.config.cookie_secret);
            let mut resp = Redirect::to("/login").into_response();
            set_cookie(&mut resp, &cookie);
            info!("claim token preflight OK; reserving intent + redirecting to /login");
            resp
        }
        Err(policy) => {
            warn!(?policy, "claim token preflight rejected");
            redeem_bounce(&policy)
        }
    }
}

/// The JSON body `POST /bot/claims` accepts — the follower the claim is FOR.
///
/// Passing the follower DID makes the APP the authoritative deduper: the app can
/// short-circuit a DID that already holds a seat, and return the SAME code for a
/// DID that already has an outstanding claim — so a bot-host state loss cannot
/// re-mint or re-post per follower. Handle is advisory (logs only).
#[derive(Debug, Default, Deserialize)]
struct BotClaimRequest {
    /// The follower's DID (the idempotency key). Optional for backward-compat: an
    /// omitted DID falls back to the old un-keyed mint (no server-side dedupe).
    #[serde(default)]
    did: Option<String>,
    /// The follower's handle (advisory; recorded for operator logs only).
    #[serde(default)]
    #[allow(dead_code)]
    handle: Option<String>,
}

/// The JSON body `POST /bot/claims` returns on success.
#[derive(Debug, serde::Serialize)]
struct BotClaimResponse {
    /// Server-side dedupe outcome, so the bot knows whether to post:
    /// `"minted"` (a fresh code — post the claim link), `"existing"` (this DID
    /// already had an outstanding claim; the SAME code/token/url is returned, so an
    /// idempotent re-post is safe), or `"already_seated"` (this DID already holds
    /// beta access; code/token/url are empty and the bot should post NOTHING).
    status: &'static str,
    /// The bare invite code (`FEATHER-…`) — for the bot's own logs/idempotency
    /// store. NEVER post this publicly; post the `url` instead. Empty when
    /// `already_seated`.
    code: String,
    /// The opaque claim token (the code wrapped + signed). Empty when
    /// `already_seated`.
    token: String,
    /// The full claim URL to put in the public skeet: `${public_url}/claim?t=…`.
    /// Empty when `already_seated`.
    url: String,
}

/// `POST /bot/claims` — headless, shared-secret mint of a claim link.
///
/// Auth is a bearer shared secret in the `X-Bot-Secret` header (== the Fly secret
/// `FEATHERREADER_BOT_SECRET`), NOT an OAuth cookie — so the homelab-hosted bot
/// can call it. When `FEATHERREADER_BOT_SECRET` is unset the endpoint is DISABLED
/// (503), so a bare/dev instance never exposes an unauthenticated mint.
///
/// Server-side DID idempotency (the authoritative dedupe backstop): the request
/// body carries the follower `did`. The app — not the bot's local SQLite — is the
/// source of truth, so a bot-host state loss cannot re-mint or re-post per
/// follower:
///   * DID already holds beta access → `200 {status:"already_seated"}` (empty
///     code/url; the bot marks it handled and posts NOTHING);
///   * DID already has an outstanding active claim → `200 {status:"existing"}`
///     returning the SAME code/token/url (idempotent — never a second mint);
///   * otherwise mint a fresh code recorded FOR that DID → `200 {status:"minted"}`.
///
/// Cap accounting: the bot must not promise more claims than seats remain, so
/// this refuses with `409 Conflict {"error":"full"}` when
/// `beta_access + outstanding active codes >= FEATHERREADER_BETA_CAP`. (The
/// redeem-time cap in `store::redeem_code` is still the hard backstop.) The count
/// queries FAIL CLOSED: a DB error propagates as `500` rather than reading 0 and
/// minting past the cap.
///
/// On a fresh mint it uses the generous claim TTL (`FEATHERREADER_CLAIM_TTL_SECS`,
/// default 14d — the admin browser flow's 30-min TTL would expire before the
/// follower taps an async-delivered link).
async fn bot_mint_claim(
    State(state): State<AppState>,
    headers: HeaderMap,
    body: axum::body::Bytes,
) -> Response {
    // 1. The endpoint is OFF unless a bot secret is configured.
    let bot_secret = match state.config.bot_secret.as_deref() {
        Some(s) => s,
        None => {
            warn!(
                "POST /bot/claims called but FEATHERREADER_BOT_SECRET is unset (endpoint disabled)"
            );
            return (
                StatusCode::SERVICE_UNAVAILABLE,
                "bot mint endpoint disabled (FEATHERREADER_BOT_SECRET unset)\n",
            )
                .into_response();
        }
    };

    // 2. Constant-time bearer check on the X-Bot-Secret header.
    let presented = headers
        .get("x-bot-secret")
        .and_then(|v| v.to_str().ok())
        .unwrap_or("");
    if !bot_secret_matches(presented, bot_secret) {
        warn!("POST /bot/claims rejected: bad or missing X-Bot-Secret");
        return (StatusCode::UNAUTHORIZED, "bad bot secret\n").into_response();
    }

    // 2b. Parse the (optional) JSON body → the follower DID/handle. An empty body
    // (legacy caller) parses to an all-None request; a malformed body is a 400.
    let req: BotClaimRequest = if body.is_empty() {
        BotClaimRequest::default()
    } else {
        match serde_json::from_slice(&body) {
            Ok(r) => r,
            Err(err) => {
                warn!(%err, "POST /bot/claims: bad JSON body");
                return (StatusCode::BAD_REQUEST, "bad json body\n").into_response();
            }
        }
    };
    let follower_did = req.did.as_deref().filter(|d| !d.is_empty());

    // 3. Server-side DID idempotency (only when a DID was supplied):
    if let Some(did) = follower_did {
        // 3a. Already seated → tell the bot to post nothing.
        match store::has_beta_access(&state.db, did).await {
            Ok(true) => {
                info!("bot mint: DID already holds beta access; already_seated");
                return bot_claim_json(BotClaimResponse {
                    status: "already_seated",
                    code: String::new(),
                    token: String::new(),
                    url: String::new(),
                });
            }
            Ok(false) => {}
            Err(err) => {
                // Fail closed: a DB error must not fall through to a fresh mint.
                warn!(%err, "bot mint: has_beta_access failed");
                return (StatusCode::INTERNAL_SERVER_ERROR, "lookup failed\n").into_response();
            }
        }
        // 3b. Outstanding active claim for this DID → return the SAME code (no
        // second mint). This is what survives a bot-host state loss.
        match store::find_active_code_for_did(&state.db, did).await {
            Ok(Some(code)) => {
                info!("bot mint: existing outstanding claim for DID; returning same code");
                let token = sign_claim_token(&code, &state.config.cookie_secret);
                let url = format!("{}/claim?t={}", state.config.public_url, qenc(&token));
                return bot_claim_json(BotClaimResponse {
                    status: "existing",
                    code,
                    token,
                    url,
                });
            }
            Ok(None) => {}
            Err(err) => {
                warn!(%err, "bot mint: find_active_code_for_did failed");
                return (StatusCode::INTERNAL_SERVER_ERROR, "lookup failed\n").into_response();
            }
        }
    }

    // 4. Cap accounting: seats already granted + outstanding unredeemed codes.
    //    FAIL CLOSED — a count error is a 500, not a silent mint past the cap.
    let granted = match store::count_beta_access(&state.db).await {
        Ok(n) => n,
        Err(err) => {
            warn!(%err, "bot mint: count_beta_access failed; failing closed");
            return (StatusCode::INTERNAL_SERVER_ERROR, "count failed\n").into_response();
        }
    };
    let outstanding = match store::count_active_codes(&state.db).await {
        Ok(n) => n,
        Err(err) => {
            warn!(%err, "bot mint: count_active_codes failed; failing closed");
            return (StatusCode::INTERNAL_SERVER_ERROR, "count failed\n").into_response();
        }
    };
    if granted + outstanding >= state.config.beta_cap {
        info!(
            granted,
            outstanding,
            cap = state.config.beta_cap,
            "bot mint refused: at capacity"
        );
        return (
            StatusCode::CONFLICT,
            [(header::CONTENT_TYPE, "application/json")],
            "{\"error\":\"full\"}\n",
        )
            .into_response();
    }

    // 5. Mint with the generous claim TTL, recording the follower DID (when given)
    //    so a re-request for the same DID returns THIS code idempotently.
    let bot_did = state
        .config
        .admin_seed_dids()
        .first()
        .cloned()
        .unwrap_or_else(|| "did:bot:featherreader".to_string());
    let minted = match follower_did {
        Some(did) => {
            store::mint_code_for_did(&state.db, &bot_did, state.config.claim_ttl_secs, did).await
        }
        None => store::mint_code(&state.db, &bot_did, state.config.claim_ttl_secs).await,
    };
    let code = match minted {
        Ok(c) => c,
        // S4: the dedupe check (3b) and this mint are separate statements, so two
        // concurrent requests for one DID can both fall through 3b's `Ok(None)`.
        // The partial unique index `idx_invite_codes_intended_active` makes the
        // loser's INSERT fail (only one active row per intended DID), which
        // surfaces here as a conflict. Recover by returning the winner's existing
        // code (same shape as the 3b idempotent path) instead of a 500.
        Err(err) if follower_did.is_some() && store::is_intended_active_conflict(&err) => {
            match store::find_active_code_for_did(&state.db, follower_did.unwrap()).await {
                Ok(Some(code)) => {
                    info!("bot mint: lost the mint race; returning the concurrently-minted code");
                    let token = sign_claim_token(&code, &state.config.cookie_secret);
                    let url = format!("{}/claim?t={}", state.config.public_url, qenc(&token));
                    return bot_claim_json(BotClaimResponse {
                        status: "existing",
                        code,
                        token,
                        url,
                    });
                }
                // The winner's row vanished between the conflict and this lookup
                // (redeemed/expired/purged in the gap) — nothing to hand back.
                // Fail closed rather than silently mint past the just-hit guard.
                Ok(None) => {
                    warn!("bot mint: conflict but no active code found on recovery");
                    return (StatusCode::INTERNAL_SERVER_ERROR, "mint failed\n").into_response();
                }
                Err(err) => {
                    warn!(%err, "bot mint: recovery lookup after conflict failed");
                    return (StatusCode::INTERNAL_SERVER_ERROR, "mint failed\n").into_response();
                }
            }
        }
        Err(err) => {
            warn!(%err, "bot mint_code failed");
            return (StatusCode::INTERNAL_SERVER_ERROR, "mint failed\n").into_response();
        }
    };
    let token = sign_claim_token(&code, &state.config.cookie_secret);
    let url = format!("{}/claim?t={}", state.config.public_url, qenc(&token));
    info!("bot minted a claim code + token");

    bot_claim_json(BotClaimResponse {
        status: "minted",
        code,
        token,
        url,
    })
}

/// Serialize a [`BotClaimResponse`] to a `200 application/json` response (or a
/// `500` if serialization somehow fails).
fn bot_claim_json(resp: BotClaimResponse) -> Response {
    match serde_json::to_string(&resp) {
        Ok(body) => (
            StatusCode::OK,
            [(header::CONTENT_TYPE, "application/json")],
            body,
        )
            .into_response(),
        Err(err) => {
            warn!(%err, "serializing bot claim response failed");
            (StatusCode::INTERNAL_SERVER_ERROR, "serialize failed\n").into_response()
        }
    }
}

/// Constant-time equality for the bot bearer secret (avoid a timing side-channel
/// on the shared secret). Delegates to the same `cookie::constant_time_eq` used
/// by the HMAC checks so there is one comparator to audit; a length mismatch
/// short-circuits to `false`, which is fine — the secret length isn't sensitive.
fn bot_secret_matches(presented: &str, expected: &str) -> bool {
    cookie::constant_time_eq(presented.as_bytes(), expected.as_bytes())
}

// ---------------------------------------------------------------------------
// Signed, short-lived invite cookie (reuses the session-cookie HMAC helper)
// ---------------------------------------------------------------------------

/// Sign the reserved invite `code` into a short-lived `Set-Cookie` value. Reuses
/// the same HMAC-SHA256 helper as the session cookie; the payload is the code
/// itself (base64url) rather than an opaque sid, since the code IS the reserved
/// intent the callback consumes.
fn sign_invite(code: &str, secret: &str) -> String {
    cookie::sign_value(INVITE_COOKIE, code, secret, INVITE_TTL_SECS)
}

/// Verify + read the reserved invite code out of the request's invite cookie
/// (`None` if absent, tampered, or forged). No expiry is enforced here beyond
/// the cookie's own `Max-Age`; the atomic `redeem_code` at the callback is the
/// authority on the code's live status.
fn invite_cookie_code(headers: &HeaderMap, secret: &str) -> Option<String> {
    cookie::verify_value(headers, INVITE_COOKIE, secret)
}

/// Domain-separation label for the claim TOKEN's HMAC (distinct from the
/// `fr_invite`/`fr_session` cookie names), so a token can never be replayed as a
/// cookie value and vice-versa.
const CLAIM_TOKEN_LABEL: &str = "claim-token";

/// Sign an invite `code` into a URL-safe claim TOKEN: `b64url(code).<sig>`
/// (HMAC-SHA256 over `"claim-token" || 0x00 || code`).
///
/// NOTE — the token is NOT confidential: the `b64url(code)` half is trivially
/// decodable by anyone, so the raw `FEATHER-…` code is effectively public in the
/// claim URL. The token's security is INTEGRITY + SINGLE-USE, not secrecy: the
/// `<sig>` HMAC means only this instance can MINT a valid token (a forged/guessed
/// code won't verify), the wrapped code is single-use (redeem flips
/// `active→redeemed`), and `/claim` is per-IP rate-limited. Wrapping keeps the
/// token one self-contained string needing no server-side token table; it does
/// NOT hide the code.
fn sign_claim_token(code: &str, secret: &str) -> String {
    cookie::sign_token(CLAIM_TOKEN_LABEL, code, secret)
}

/// Verify a claim token and return the invite code it wraps (`None` on a tampered
/// / forged / malformed token). The code's live status (active/unexpired/seat
/// free) is re-checked by `preflight_code`; this only proves the token was minted
/// by this instance.
fn claim_token_code(token: &str, secret: &str) -> Option<String> {
    cookie::verify_token(CLAIM_TOKEN_LABEL, token, secret)
}

/// Clear the invite cookie on a response (after a successful bind, or when the
/// reservation turned out to be stale).
fn clear_invite_cookie(resp: &mut Response) {
    set_cookie(
        resp,
        &format!("{INVITE_COOKIE}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0"),
    );
}

// ---------------------------------------------------------------------------
// OPML import + export
// ---------------------------------------------------------------------------

/// `POST /opml` — import subscriptions from an OPML document.
///
/// Accepts either a multipart file upload (field `file`) or a pasted textarea
/// (field `opml`). The parsed feeds each become a `community.lexicon.rss.folder`
/// (for any named folders) + a `community.lexicon.rss.subscription` record in the
/// user's PDS via the records layer's bulk-add (`add_subscriptions_bulk`, one
/// `applyWrites` round-trip). Feeds are also upserted into the local cache so
/// they show immediately; polling is left to the background poller.
async fn import_opml(
    State(state): State<AppState>,
    headers: HeaderMap,
    mut multipart: Multipart,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };
    let pool = &state.db;

    // Collect the OPML text from whichever field carried it. Multipart errors
    // are mapped to their axum-native response so that an over-cap upload (the
    // `DefaultBodyLimit` on this route, see `OPML_BODY_LIMIT`) surfaces as
    // `413 Payload Too Large` rather than being swallowed by the blanket
    // `WebError` → `500` conversion.
    let mut opml_text = String::new();
    while let Some(field) = multipart.next_field().await.map_err(multipart_response)? {
        let name = field.name().unwrap_or("").to_string();
        if name == "opml" || name == "file" {
            let bytes = field.bytes().await.map_err(multipart_response)?;
            if !bytes.is_empty() {
                opml_text = String::from_utf8_lossy(&bytes).into_owned();
                if name == "file" {
                    break;
                }
            }
        }
    }

    // A parse FAILURE and an empty-but-valid file are different things, and
    // `unwrap_or_default` collapsed them: a malformed export was reported to the
    // reader as "No feeds found in that OPML", which sends them looking at their
    // old reader for feeds that are right there in the file.
    let feeds =
        match opml::parse_opml(&opml_text) {
            Ok(feeds) => feeds,
            Err(err) => {
                warn!(%err, %did, "OPML import could not parse the uploaded file");
                return Ok(Redirect::to(&format!(
                "/?flash={}",
                qenc("That file could not be read as OPML. Export it again from your other reader?")
            ))
                .into_response());
            }
        };
    if feeds.is_empty() {
        info!(%did, "OPML import found no feeds");
        return Ok(
            Redirect::to(&format!("/?flash={}", qenc("No feeds found in that OPML")))
                .into_response(),
        );
    }

    // Create any named folders first, mapping folder name → at:// URI so
    // subscriptions can reference them.
    let now = now_rfc3339();
    let mut folder_uris: std::collections::HashMap<String, String> =
        std::collections::HashMap::new();
    // Reuse existing folders where the name already exists.
    if let Ok(existing) = state.repo().list_folders_sorted(&did).await {
        for (rkey, folder) in existing {
            folder_uris
                .entry(folder.name.clone())
                .or_insert_with(|| folder_uri(&did, &rkey));
        }
    }
    let mut wanted_folders: Vec<String> = feeds
        .iter()
        .filter_map(|f| f.folder.clone())
        .filter(|n| !n.is_empty())
        .collect();
    wanted_folders.sort();
    wanted_folders.dedup();
    for name in wanted_folders {
        if folder_uris.contains_key(&name) {
            continue;
        }
        let folder = Folder::new(name.clone(), now.clone());
        match state.repo().add_folder(&did, &folder).await {
            Ok(rkey) => {
                folder_uris.insert(name, folder_uri(&did, &rkey));
            }
            Err(err) => warn!(%err, %did, "OPML folder create failed"),
        }
    }

    // Build one subscription record per PUBLIC feed + upsert the local cache row.
    // Private/paid feeds are SKIPPED entirely (never stored, fetched, or written)
    // and reported back to the user — the same public-feeds-only stance as the
    // single-add path, so an OPML import can't leak a Substack/Patreon/podcast
    // token onto the public network either.
    // Per-DID subscription cap: an OPML import must not blow past the cap. Compute
    // the remaining headroom (cap − existing) once; public feeds beyond it are
    // TRIMMED (not imported) and reported. `<= 0` disables the cap.
    let sub_cap = state.config.max_subs_per_did;
    let mut headroom: Option<i64> = if sub_cap > 0 {
        let existing = store::count_subscriptions_for_did(pool, &did)
            .await
            .unwrap_or(0);
        Some((sub_cap - existing).max(0))
    } else {
        None
    };
    let mut trimmed_over_cap: usize = 0;

    // Global feeds ceiling: an OPML import must not blow past the shared cache
    // ceiling any more than the single-add path may. Seed the remaining global
    // headroom (cap − current feeds) once, and only a BRAND-NEW feed URL (one
    // not already cached) consumes it. Existing/duplicate URLs add no row and
    // are always allowed. Feeds past the ceiling are TRIMMED and reported.
    // `<= 0` disables the ceiling.
    let feeds_cap = state.config.max_feeds_global;
    let mut global_headroom: Option<i64> = if feeds_cap > 0 {
        let existing = store::count_feeds(pool).await.unwrap_or(0);
        Some((feeds_cap - existing).max(0))
    } else {
        None
    };
    let mut trimmed_over_global: usize = 0;

    let mut subs = Vec::with_capacity(feeds.len());
    let mut skipped_private: Vec<String> = Vec::new();
    // Imported into the PDS but not cached locally, so not pollable until the
    // next import touches them. Counted rather than only logged — see below.
    let mut uncached: usize = 0;
    // Entries this instance cannot store at all (an `at://` publication with
    // the flag off, an unsupported scheme). Counted, because the `continue`
    // below used to increment nothing while the privacy branch beside it
    // produced a label — so an OPML from a standard.site-enabled instance
    // imported "successfully" with entries missing and no reason given.
    let mut skipped_unsupported: usize = 0;
    for f in &feeds {
        // `xmlUrl` is whatever the uploaded file says, and nothing on this path
        // ever parsed it — the single-add path can't reach here because
        // `resolve_feed_url` must parse AND successfully fetch first. So
        // `javascript:alert(1)` and `file:///etc/passwd` were both accepted,
        // cached, and published as records to the user's PUBLIC repo. Note that
        // `classify_feed_privacy` does not catch these: both parse cleanly, and
        // it returns `Public` for anything unparseable by design.
        if !feed::is_storable_feed_url(&f.feed_url, state.config.standard_site) {
            info!(
                %did,
                "skipped an OPML entry whose xmlUrl is not a storable feed URL"
            );
            skipped_unsupported += 1;
            continue;
        }
        if let feed::FeedPrivacy::Private(reason) = feed::classify_feed_privacy(&f.feed_url) {
            info!(feed = %f.feed_url, %reason, %did, "skipped private/paid feed on OPML import (not stored)");
            // Report by title where we have one, else the (public-safe) host.
            let label = f
                .title
                .clone()
                .filter(|t| !t.trim().is_empty())
                .unwrap_or_else(|| private_feed_label(&f.feed_url));
            skipped_private.push(label);
            continue;
        }

        // Over-cap: stop importing once headroom is exhausted (count the rest so
        // we can tell the user how many were dropped).
        if let Some(h) = headroom.as_mut() {
            if *h <= 0 {
                trimmed_over_cap += 1;
                continue;
            }
        }

        // Global ceiling: a brand-new feed URL consumes global headroom. Once
        // it's exhausted, refuse to cache further NEW feeds (existing URLs are
        // free — they add no row). Checked before decrementing the per-DID
        // headroom so a dropped feed doesn't burn the caller's own quota.
        let is_new = match store::get_feed_by_url(pool, &f.feed_url).await {
            Ok(existing) => existing.is_none(),
            // On a lookup error, treat as existing (don't consume global
            // headroom) but still allow the upsert to proceed.
            Err(err) => {
                warn!(%err, feed = %f.feed_url, "get_feed_by_url failed during OPML global-cap check");
                false
            }
        };
        if is_new {
            if let Some(g) = global_headroom.as_mut() {
                if *g <= 0 {
                    trimmed_over_global += 1;
                    continue;
                }
                *g -= 1;
            }
        }

        // Passed both caps: consume the per-DID headroom now that the feed is
        // actually being imported.
        if let Some(h) = headroom.as_mut() {
            *h -= 1;
        }

        let mut sub = Subscription::new(f.feed_url.clone(), now.clone());
        sub.title = f.title.clone();
        sub.site_url = f.site_url.clone();
        sub.folder = f
            .folder
            .as_ref()
            .and_then(|name| folder_uris.get(name).cloned());
        subs.push(sub);
        // Same support ticket as the single-add path: no `feeds` row means the
        // poller never selects this subscription, so the import looks like it
        // worked and the feed silently never updates. Counted as well as logged,
        // because one line per feed in a 200-feed import is not something anyone
        // reads — the count goes to the reader.
        if let Err(err) = store::upsert_feed(
            pool,
            &store::NewFeed {
                url: f.feed_url.clone(),
                title: f.title.clone(),
                site_url: f.site_url.clone(),
                ..Default::default()
            },
        )
        .await
        {
            warn!(%err, %did, url = %f.feed_url, "OPML import could not cache a feed; \
                                                  it will not be polled");
            uncached += 1;
        }
    }

    // **A failed PDS write is not an import.**
    //
    // The subscriptions live in the reader's repo; a local `feeds` row is just a
    // poller hint. This used to `warn!` and then report "Imported N feeds"
    // regardless, so a total failure read as a total success — and the reader
    // would only discover otherwise on their next visit, with an empty sidebar.
    let pds_written = match state.repo().add_subscriptions_bulk(&did, &subs).await {
        Ok(rkeys) => {
            info!(%did, count = rkeys.len(), skipped = skipped_private.len(), "imported OPML subscriptions to PDS (batched)");
            true
        }
        Err(err) => {
            warn!(%err, %did, "OPML PDS batch write failed (feeds cached locally)");
            false
        }
    };
    if !pds_written {
        return Ok(Redirect::to(&format!(
            "/?flash={}",
            qenc(
                "Could not save those subscriptions to your PDS, so nothing was imported. \
                 Try again in a moment."
            )
        ))
        .into_response());
    }

    // Report the import count, plus any private/paid feeds skipped as unsupported.
    let mut flash = format!("Imported {} feeds", subs.len());
    if uncached > 0 {
        flash.push_str(&format!(
            ". {uncached} of them could not be cached locally and may not update until the next import."
        ));
    }
    if trimmed_over_cap > 0 {
        flash.push_str(&format!(
            ". {trimmed_over_cap} feed(s) not imported: your subscription limit ({sub_cap}) was reached."
        ));
    }
    if trimmed_over_global > 0 {
        flash.push_str(&format!(
            ". {trimmed_over_global} feed(s) not imported: this instance is at its feed capacity right now."
        ));
    }
    if !skipped_private.is_empty() {
        flash.push_str(&format!(
            ". {} feed(s) skipped as private/paid: {} — not supported yet (public feeds only for now).",
            skipped_private.len(),
            skipped_private.join(", ")
        ));
    }
    if skipped_unsupported > 0 {
        // By count only — the URL is whatever the file said, and unlike the
        // private branch there is no public-safe label to give.
        flash.push_str(&format!(
            ". {skipped_unsupported} feed(s) skipped: not a kind of feed this instance can subscribe to."
        ));
    }
    Ok(Redirect::to(&format!("/?flash={}", qenc(&flash))).into_response())
}

/// A public-safe label for a skipped private feed when it has no title: just the
/// host, so we never echo the secret-bearing path/query back to the user.
fn private_feed_label(url: &str) -> String {
    url::Url::parse(url)
        .ok()
        .and_then(|u| u.host_str().map(str::to_string))
        .unwrap_or_else(|| "a private feed".to_string())
}

/// `GET /opml/export` — export the user's subscriptions + folders as OPML.
async fn export_opml(
    State(state): State<AppState>,
    headers: HeaderMap,
) -> Result<Response, WebError> {
    let did = match current_did(&state, &headers).await {
        Some(d) => d,
        None => return Ok(Redirect::to("/login").into_response()),
    };

    let subs = state
        .repo()
        .list_subscriptions_sorted(&did)
        .await
        .unwrap_or_default();
    let folders = state
        .repo()
        .list_folders_sorted(&did)
        .await
        .unwrap_or_default();
    // The exporter matches a subscription's `folder` at-uri against the folder's
    // pair key; our folder pairs are keyed by rkey, so rebuild them as at-uris.
    let folder_pairs: Vec<(String, Folder)> = folders
        .into_iter()
        .map(|(rkey, f)| (folder_uri(&did, &rkey), f))
        .collect();

    let body = opml::to_opml(&subs, &folder_pairs);
    let mut resp = (StatusCode::OK, body).into_response();
    resp.headers_mut().insert(
        header::CONTENT_TYPE,
        "text/x-opml; charset=utf-8".parse().unwrap(),
    );
    resp.headers_mut().insert(
        header::CONTENT_DISPOSITION,
        "attachment; filename=\"featherreader-subscriptions.opml\""
            .parse()
            .unwrap(),
    );
    Ok(resp)
}

// ---------------------------------------------------------------------------
// Signed session cookie (HMAC-SHA256, dependency-free)
// ---------------------------------------------------------------------------

/// Set a `Set-Cookie` header on a response (append, so logout+redirect compose).
fn set_cookie(resp: &mut Response, cookie: &str) {
    if let Ok(value) = axum::http::HeaderValue::from_str(cookie) {
        resp.headers_mut()
            .append(axum::http::header::SET_COOKIE, value);
    }
}

/// Whether the request came from htmx (the `HX-Request` header).
fn is_htmx(headers: &HeaderMap) -> bool {
    headers
        .get("HX-Request")
        .is_some_and(|v| v.as_bytes().eq_ignore_ascii_case(b"true"))
}

/// Whether a mark-read / star request originated from the single-entry READER
/// (as opposed to the list view). The reader's forms tag themselves with
/// `X-FR-Reader: 1` via `hx-headers`; the list view's do not. This selects the
/// swap fragment: the reader gets an out-of-band action-bar update (its `<li>`
/// isn't in the DOM), the list gets the row (`entry_row.html`).
fn is_reader_request(headers: &HeaderMap) -> bool {
    headers
        .get("X-FR-Reader")
        .is_some_and(|v| v.as_bytes() == b"1")
}

/// A tiny, self-contained signed-cookie layer: HMAC-SHA256 over an opaque,
/// server-minted **session id** (never the DID — so the cookie can't be forged
/// from a resolved victim DID; forging it needs the HMAC secret *and* a live
/// server-side session id).
mod cookie {
    use super::{HeaderMap, SESSION_COOKIE};

    /// Sign a session id into a `Set-Cookie` header value: `fr_session=<sid>.<sig>`.
    pub fn sign_session(sid: &str, secret: &str) -> String {
        sign_value(SESSION_COOKIE, sid, secret, 2_592_000)
    }

    /// Verify the request's session cookie and return the session id it carries.
    pub fn verify_session(headers: &HeaderMap, secret: &str) -> Option<String> {
        verify_value(headers, SESSION_COOKIE, secret)
    }

    /// The HMAC message binding the cookie NAME to its value (`name || 0x00 ||
    /// value`), so a signature minted for one cookie can't verify under another —
    /// e.g. a value validly signed as `fr_invite` is not accepted as `fr_session`.
    /// The NUL separator can't appear in a cookie name, so the encoding is
    /// unambiguous.
    fn cookie_hmac_msg(name: &str, value: &str) -> Vec<u8> {
        let mut msg = Vec::with_capacity(name.len() + 1 + value.len());
        msg.extend_from_slice(name.as_bytes());
        msg.push(0);
        msg.extend_from_slice(value.as_bytes());
        msg
    }

    /// Sign an arbitrary string `value` into a `Set-Cookie` header for `name`,
    /// HMAC-SHA256 over `name || 0x00 || value`: `name=<b64url(value)>.<sig>`. The
    /// generic form behind both the session cookie and the short-lived invite
    /// cookie; domain-separating by name keeps a signature valid only for the
    /// cookie it was minted for.
    pub fn sign_value(name: &str, value: &str, secret: &str, max_age_secs: i64) -> String {
        let sig = hmac_sha256_hex(secret.as_bytes(), &cookie_hmac_msg(name, value));
        let b64 = b64url_encode(value.as_bytes());
        format!(
            "{name}={b64}.{sig}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age={max_age_secs}"
        )
    }

    /// Verify + read a value out of the named signed cookie (`None` on absent /
    /// tampered / forged / cross-cookie). The generic form behind both readers.
    pub fn verify_value(headers: &HeaderMap, name: &str, secret: &str) -> Option<String> {
        let raw = cookie_value(headers, name)?;
        let (b64, sig) = raw.split_once('.')?;
        let bytes = b64url_decode(b64)?;
        let value = String::from_utf8(bytes).ok()?;
        let expected = hmac_sha256_hex(secret.as_bytes(), &cookie_hmac_msg(name, &value));
        if constant_time_eq(expected.as_bytes(), sig.as_bytes()) {
            Some(value)
        } else {
            None
        }
    }

    /// Sign an arbitrary `value` into an opaque, URL-safe token string
    /// `b64url(value).<sig>` (HMAC-SHA256 over `label || 0x00 || value`). Unlike
    /// [`sign_value`] this is NOT a `Set-Cookie` header — it's a bare token for a
    /// URL query param (the bot's claim link). `label` domain-separates it from
    /// the cookies so a token can't be replayed as a cookie value.
    pub fn sign_token(label: &str, value: &str, secret: &str) -> String {
        let sig = hmac_sha256_hex(secret.as_bytes(), &cookie_hmac_msg(label, value));
        let b64 = b64url_encode(value.as_bytes());
        format!("{b64}.{sig}")
    }

    /// Verify a token minted by [`sign_token`] and return the wrapped value
    /// (`None` on tamper / forge / malformed). Constant-time signature compare.
    pub fn verify_token(label: &str, token: &str, secret: &str) -> Option<String> {
        let (b64, sig) = token.split_once('.')?;
        let bytes = b64url_decode(b64)?;
        let value = String::from_utf8(bytes).ok()?;
        let expected = hmac_sha256_hex(secret.as_bytes(), &cookie_hmac_msg(label, &value));
        if constant_time_eq(expected.as_bytes(), sig.as_bytes()) {
            Some(value)
        } else {
            None
        }
    }

    /// Pull one cookie value out of the `Cookie` request header.
    fn cookie_value(headers: &HeaderMap, name: &str) -> Option<String> {
        let header = headers.get(axum::http::header::COOKIE)?.to_str().ok()?;
        for part in header.split(';') {
            let part = part.trim();
            if let Some((k, v)) = part.split_once('=') {
                if k == name {
                    return Some(v.to_string());
                }
            }
        }
        None
    }

    /// Constant-time byte comparison (avoid signature-timing leaks). Public
    /// within the module so the bot-secret bearer check reuses the exact same
    /// comparator as the cookie/token HMAC checks (one implementation to audit).
    pub fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
        if a.len() != b.len() {
            return false;
        }
        let mut diff = 0u8;
        for (x, y) in a.iter().zip(b.iter()) {
            diff |= x ^ y;
        }
        diff == 0
    }

    // -- URL-safe base64 (no padding), std-only --------------------------------

    const B64: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";

    fn b64url_encode(input: &[u8]) -> String {
        let mut out = String::with_capacity(input.len().div_ceil(3) * 4);
        for chunk in input.chunks(3) {
            let b = [
                chunk[0],
                *chunk.get(1).unwrap_or(&0),
                *chunk.get(2).unwrap_or(&0),
            ];
            let n = ((b[0] as u32) << 16) | ((b[1] as u32) << 8) | (b[2] as u32);
            out.push(B64[((n >> 18) & 63) as usize] as char);
            out.push(B64[((n >> 12) & 63) as usize] as char);
            if chunk.len() > 1 {
                out.push(B64[((n >> 6) & 63) as usize] as char);
            }
            if chunk.len() > 2 {
                out.push(B64[(n & 63) as usize] as char);
            }
        }
        out
    }

    fn b64url_decode(input: &str) -> Option<Vec<u8>> {
        fn val(c: u8) -> Option<u32> {
            match c {
                b'A'..=b'Z' => Some((c - b'A') as u32),
                b'a'..=b'z' => Some((c - b'a' + 26) as u32),
                b'0'..=b'9' => Some((c - b'0' + 52) as u32),
                b'-' => Some(62),
                b'_' => Some(63),
                _ => None,
            }
        }
        let bytes = input.as_bytes();
        let mut out = Vec::with_capacity(input.len() / 4 * 3 + 2);
        for chunk in bytes.chunks(4) {
            let mut n = 0u32;
            let mut valid = 0;
            for (i, &c) in chunk.iter().enumerate() {
                n |= val(c)? << (18 - 6 * i);
                valid += 1;
            }
            out.push((n >> 16) as u8);
            if valid > 2 {
                out.push((n >> 8) as u8);
            }
            if valid > 3 {
                out.push(n as u8);
            }
        }
        Some(out)
    }

    // -- HMAC-SHA256, std-only -------------------------------------------------

    /// HMAC-SHA256(key, msg) as lowercase hex.
    fn hmac_sha256_hex(key: &[u8], msg: &[u8]) -> String {
        const BLOCK: usize = 64;
        let mut k = [0u8; BLOCK];
        if key.len() > BLOCK {
            let d = sha256(key);
            k[..32].copy_from_slice(&d);
        } else {
            k[..key.len()].copy_from_slice(key);
        }
        let mut ipad = [0x36u8; BLOCK];
        let mut opad = [0x5cu8; BLOCK];
        for i in 0..BLOCK {
            ipad[i] ^= k[i];
            opad[i] ^= k[i];
        }
        let mut inner = Vec::with_capacity(BLOCK + msg.len());
        inner.extend_from_slice(&ipad);
        inner.extend_from_slice(msg);
        let inner_hash = sha256(&inner);
        let mut outer = Vec::with_capacity(BLOCK + 32);
        outer.extend_from_slice(&opad);
        outer.extend_from_slice(&inner_hash);
        let mac = sha256(&outer);
        let mut hex = String::with_capacity(64);
        for b in mac {
            hex.push_str(&format!("{b:02x}"));
        }
        hex
    }

    /// SHA-256 (FIPS 180-4), std-only.
    fn sha256(data: &[u8]) -> [u8; 32] {
        const K: [u32; 64] = [
            0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4,
            0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe,
            0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f,
            0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
            0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc,
            0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
            0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116,
            0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
            0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
            0xc67178f2,
        ];
        let mut h: [u32; 8] = [
            0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab,
            0x5be0cd19,
        ];

        let bit_len = (data.len() as u64) * 8;
        let mut msg = data.to_vec();
        msg.push(0x80);
        while msg.len() % 64 != 56 {
            msg.push(0);
        }
        msg.extend_from_slice(&bit_len.to_be_bytes());

        for block in msg.chunks(64) {
            let mut w = [0u32; 64];
            for i in 0..16 {
                w[i] = u32::from_be_bytes([
                    block[i * 4],
                    block[i * 4 + 1],
                    block[i * 4 + 2],
                    block[i * 4 + 3],
                ]);
            }
            for i in 16..64 {
                let s0 = w[i - 15].rotate_right(7) ^ w[i - 15].rotate_right(18) ^ (w[i - 15] >> 3);
                let s1 = w[i - 2].rotate_right(17) ^ w[i - 2].rotate_right(19) ^ (w[i - 2] >> 10);
                w[i] = w[i - 16]
                    .wrapping_add(s0)
                    .wrapping_add(w[i - 7])
                    .wrapping_add(s1);
            }
            let mut a = h;
            for i in 0..64 {
                let s1 = a[4].rotate_right(6) ^ a[4].rotate_right(11) ^ a[4].rotate_right(25);
                let ch = (a[4] & a[5]) ^ ((!a[4]) & a[6]);
                let t1 = a[7]
                    .wrapping_add(s1)
                    .wrapping_add(ch)
                    .wrapping_add(K[i])
                    .wrapping_add(w[i]);
                let s0 = a[0].rotate_right(2) ^ a[0].rotate_right(13) ^ a[0].rotate_right(22);
                let maj = (a[0] & a[1]) ^ (a[0] & a[2]) ^ (a[1] & a[2]);
                let t2 = s0.wrapping_add(maj);
                a[7] = a[6];
                a[6] = a[5];
                a[5] = a[4];
                a[4] = a[3].wrapping_add(t1);
                a[3] = a[2];
                a[2] = a[1];
                a[1] = a[0];
                a[0] = t1.wrapping_add(t2);
            }
            for i in 0..8 {
                h[i] = h[i].wrapping_add(a[i]);
            }
        }

        let mut out = [0u8; 32];
        for (i, word) in h.iter().enumerate() {
            out[i * 4..i * 4 + 4].copy_from_slice(&word.to_be_bytes());
        }
        out
    }

    #[cfg(test)]
    mod tests {
        use super::*;

        #[test]
        fn sha256_known_vector() {
            let d = sha256(b"abc");
            let hex: String = d.iter().map(|b| format!("{b:02x}")).collect();
            assert_eq!(
                hex,
                "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
            );
        }

        #[test]
        fn hmac_known_vector() {
            let mac = hmac_sha256_hex(b"Jefe", b"what do ya want for nothing?");
            assert_eq!(
                mac,
                "5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843"
            );
        }

        #[test]
        fn sign_verify_round_trips() {
            let secret = "test-secret";
            let sid = "9f2c-opaque-session-id";
            let cookie = sign_session(sid, secret);
            let pair = cookie.split(';').next().unwrap().to_string();
            let mut headers = HeaderMap::new();
            headers.insert(axum::http::header::COOKIE, pair.parse().unwrap());
            assert_eq!(verify_session(&headers, secret).as_deref(), Some(sid));
            // Wrong secret → rejected (an attacker without the HMAC key can't forge).
            assert!(verify_session(&headers, "other-secret").is_none());
        }

        #[test]
        fn forged_and_tampered_cookies_are_rejected() {
            let secret = "test-secret";

            // 1. A fully forged cookie: attacker knows a victim's DID/sid but not
            //    the secret, so an arbitrary signature must not verify.
            let forged = format!(
                "{SESSION_COOKIE}={}.{}",
                b64url_encode(b"attacker-chosen-sid"),
                "deadbeef".repeat(8) // 64 hex chars, wrong sig
            );
            let mut headers = HeaderMap::new();
            headers.insert(axum::http::header::COOKIE, forged.parse().unwrap());
            assert!(verify_session(&headers, secret).is_none());

            // 2. A tampered cookie: take a VALID cookie and mutate the sid while
            //    keeping the original signature — must not verify.
            let cookie = sign_session("real-sid", secret);
            let pair = cookie.split(';').next().unwrap();
            let (_b64, sig) = pair.split_once('=').unwrap().1.split_once('.').unwrap();
            let tampered = format!(
                "{SESSION_COOKIE}={}.{}",
                b64url_encode(b"different-sid"),
                sig
            );
            let mut headers2 = HeaderMap::new();
            headers2.insert(axum::http::header::COOKIE, tampered.parse().unwrap());
            assert!(verify_session(&headers2, secret).is_none());
        }

        #[test]
        fn b64url_round_trips() {
            for s in ["did:plc:abc", "", "a", "ab", "abc", "abcd"] {
                let enc = b64url_encode(s.as_bytes());
                assert_eq!(b64url_decode(&enc).unwrap(), s.as_bytes());
            }
        }
    }
}

// ---------------------------------------------------------------------------
// Small store helpers local to the web layer
// ---------------------------------------------------------------------------

/// Fetch a single cached entry by id — SCOPED to `did`'s subscriptions.
///
/// Returns `None` (→ 404 at the handler) if the entry does not exist OR if
/// `did` does not subscribe to its feed. This is the per-DID read gate for the
/// `GET /entries/:id` reader and the htmx row rebuild: the shared cache is
/// deduped by URL, but no DID can read another DID's cached article.
///
/// **The only `SELECT e.*` left, and deliberately so.** This is the one surface
/// that renders `content_html`, and it fetches exactly one row. The list views
/// go through [`store::list_entries`], which is both paged and body-free — see
/// [`store::EntryListRow`] for why they had to stop sharing this projection.
async fn get_entry_by_id(
    pool: &store::Pool,
    did: &str,
    id: i64,
) -> anyhow::Result<Option<store::Entry>> {
    let entry = sqlx::query_as::<_, store::Entry>(
        r#"
        SELECT e.* FROM entries e
        WHERE e.id = ?2
          AND EXISTS (
              SELECT 1 FROM sub_ref sr
              WHERE sr.did = ?1 AND sr.feed_id = e.feed_id
          )
        "#,
    )
    .bind(did)
    .bind(id)
    .fetch_optional(pool)
    .await?;
    Ok(entry)
}

/// Whether `entry_id` is marked read for `did` (absent state row = unread).
async fn entry_is_read(pool: &store::Pool, did: &str, entry_id: i64) -> anyhow::Result<bool> {
    let read: Option<bool> =
        sqlx::query_scalar("SELECT read FROM entry_state WHERE did = ?1 AND entry_id = ?2")
            .bind(did)
            .bind(entry_id)
            .fetch_optional(pool)
            .await?
            .flatten();
    Ok(read.unwrap_or(false))
}

/// Whether `entry_id` is starred for `did` (absent state row = not starred).
async fn entry_is_starred(pool: &store::Pool, did: &str, entry_id: i64) -> anyhow::Result<bool> {
    let starred: Option<bool> =
        sqlx::query_scalar("SELECT starred FROM entry_state WHERE did = ?1 AND entry_id = ?2")
            .bind(did)
            .bind(entry_id)
            .fetch_optional(pool)
            .await?
            .flatten();
    Ok(starred.unwrap_or(false))
}

/// Feed display title for one entry's feed id (via a single lookup).
async fn feed_title_by_entry(pool: &store::Pool, feed_id: i64) -> String {
    match sqlx::query_as::<_, store::Feed>("SELECT * FROM feeds WHERE id = ?1")
        .bind(feed_id)
        .fetch_optional(pool)
        .await
    {
        Ok(Some(f)) => display_title(f.title.as_deref(), &f.url),
        _ => String::new(),
    }
}

/// Rebuild an [`EntryRow`] for an htmx swap after a read/star toggle. `read` may
/// be forced (mark-read path) or looked up (`None` — star path).
async fn build_entry_row(
    pool: &store::Pool,
    did: &str,
    id: i64,
    read: Option<bool>,
) -> anyhow::Result<Option<EntryRow>> {
    let entry = match get_entry_by_id(pool, did, id).await? {
        Some(e) => e,
        None => return Ok(None),
    };
    let read = match read {
        Some(r) => r,
        None => entry_is_read(pool, did, id).await?,
    };
    let starred = entry_is_starred(pool, did, id).await?;
    Ok(Some(EntryRow {
        id: entry.id,
        title: entry
            .title
            .clone()
            .filter(|t| !t.trim().is_empty())
            .unwrap_or_else(|| "(untitled)".to_string()),
        feed_title: feed_title_by_entry(pool, entry.feed_id).await,
        published: display_date(entry.published.as_deref()),
        read,
        starred,
        link: SafeLink::entry(id, ""),
        cached: true,
        rkey: String::new(),
    }))
}

/// RFC3339 "now" (UTC) — shared by handlers that stamp/compare timestamps.
fn now_rfc3339() -> String {
    chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn qenc_encodes_reserved() {
        assert_eq!(qenc("a b"), "a%20b");
        assert_eq!(
            qenc("https://example.com/feed.xml"),
            "https%3A%2F%2Fexample.com%2Ffeed.xml"
        );
        assert_eq!(
            qenc("at://did:plc:x/c/r"),
            "at%3A%2F%2Fdid%3Aplc%3Ax%2Fc%2Fr"
        );
        // Unreserved chars pass through untouched.
        assert_eq!(qenc("A-Za-z0-9-_.~"), "A-Za-z0-9-_.~");
    }

    #[test]
    fn folder_uri_shape() {
        assert_eq!(
            folder_uri("did:plc:abc", "3kfolder"),
            "at://did:plc:abc/community.lexicon.rss.folder/3kfolder"
        );
    }

    // -- public-feeds-only: private/paid feeds are refused --------------------

    #[test]
    fn private_feeds_are_classified_private_across_providers() {
        // The add + OPML paths both gate on this classifier; assert it flags a
        // spread of paid providers (newsletters + private podcasts) and the
        // generic credential-in-URL shapes.
        for url in [
            "https://author.substack.com/feed/private/deadbeefcafe1234",
            "https://www.patreon.com/rss/author?auth=Zm9vYmFyc2VjcmV0dG9rZW4",
            "https://blog.ghost.io/rss/?uuid=1f2e3d4c-5b6a-7089-90ab-cdef01234567",
            "https://feeds.supportingcast.fm/show/abcdef0123456789abcdef01",
            "https://example.com/feed?token=Zm9vYmFyc2VjcmV0",
            "https://user:pass@example.com/feed",
        ] {
            assert!(
                feed::classify_feed_privacy(url).is_private(),
                "expected private: {url}"
            );
        }
    }

    #[test]
    fn public_feeds_stay_public() {
        for url in [
            "https://author.substack.com/feed",
            "https://wordpress.example.com/feed/",
            "https://example.com/rss.xml",
            "https://example.org/atom.xml",
            // YouTube channel/playlist RSS is fully public — must not false-block.
            "https://www.youtube.com/feeds/videos.xml?channel_id=UC-lHJZR3Gqxm24_Vd_AJ5Yw",
            "https://www.youtube.com/feeds/videos.xml?playlist_id=PLFgquLnL59alCl_2TQvOiD5Vgm1",
        ] {
            assert!(
                !feed::classify_feed_privacy(url).is_private(),
                "expected public: {url}"
            );
        }
    }

    #[test]
    fn private_feed_label_is_public_safe_host_only() {
        // The OPML skip report must never echo the secret path/query, only the host.
        let label =
            private_feed_label("https://author.substack.com/feed/private/deadbeefcafe1234token");
        assert_eq!(label, "author.substack.com");
        assert!(!label.contains("deadbeefcafe1234token"));
        assert!(!label.contains("/private/"));
        // An unparseable URL degrades to a generic label.
        assert_eq!(private_feed_label("not a url"), "a private feed");
    }

    #[test]
    fn refusal_message_promises_nothing_stored() {
        assert!(PRIVATE_FEED_REFUSAL.contains("not saved or sent anywhere"));
        assert!(PRIVATE_FEED_REFUSAL.contains("public feeds"));
    }

    #[test]
    fn scope_query_preserves_context() {
        let q = EntryQuery {
            feed: Some("https://example.com/feed.xml".to_string()),
            folder: None,
            view: Some("all".to_string()),
        };
        let s = scope_query(&q);
        assert!(s.contains("feed=https%3A%2F%2Fexample.com%2Ffeed.xml"));
        assert!(s.contains("view=all"));

        // Default view is omitted.
        let q2 = EntryQuery {
            feed: None,
            folder: None,
            view: Some("unread".to_string()),
        };
        assert_eq!(scope_query(&q2), "");
    }

    // -- closed-beta invite gate + rate-limit + cache-control ------------------

    use axum::body::Body;
    use axum::http::Request;
    use tower::ServiceExt; // for `oneshot`

    /// Build an [`AppState`] over a fresh in-memory DB, seeding the given admin
    /// DIDs (via ALLOWED_DIDS → ensure_seed) and a fixed cookie secret so tests
    /// can forge matching cookies.
    async fn test_state(allowed: &[&str]) -> AppState {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        let dids: Vec<String> = allowed.iter().map(|s| s.to_string()).collect();
        store::ensure_seed(&db, &dids).await.unwrap();
        let config = Config {
            allowed_dids: dids,
            cookie_secret: "test-cookie-secret-000".to_string(),
            beta_cap: 3,
            ..Config::default()
        };
        AppState::new(config, db).unwrap()
    }

    /// A `Cookie` header carrying a valid signed session for `sid` (the sid is
    /// looked up in the registry, so create the session first).
    fn session_cookie(state: &AppState, did: &str, handle: Option<&str>) -> String {
        let sid = state.sessions.create(Session {
            did: did.to_string(),
            handle: handle.map(str::to_string),
        });
        let sc = cookie::sign_session(&sid, &state.config.cookie_secret);
        sc.split(';').next().unwrap().to_string()
    }

    /// The bucket map is bounded by COUNT, not only by idle time. An hour is a
    /// long time to accept distinct source IPs on two unauthenticated guarded
    /// routes.
    #[test]
    fn the_rate_limit_map_is_bounded() {
        let rl = RateLimiter::shared();
        let now = Instant::now();
        for i in 0..(MAX_RATE_BUCKETS + 2_000) {
            // Distinct IPv6 addresses, all "seen" at increasing times so the LRU
            // ordering below is well-defined.
            let ip: IpAddr = format!("2001:db8::{i:x}").parse().unwrap();
            rl.check_at(ip, now + Duration::from_millis(i as u64));
        }
        let len = rl.inner.lock().unwrap().buckets.len();
        assert!(
            len <= MAX_RATE_BUCKETS,
            "the rate-limit map grew to {len}, past its {MAX_RATE_BUCKETS} cap"
        );
    }

    /// Eviction must not hand a throttled attacker a fresh burst.
    ///
    /// The bound is LRU, so the one bucket an attacker can never evict is their
    /// own — it is the most recently touched thing in the map. If this inverted,
    /// the size cap would become a rate-limit bypass: spray addresses until the
    /// map overflows, then resume.
    #[test]
    fn flooding_the_map_does_not_reset_the_flooders_own_bucket() {
        let rl = RateLimiter::shared();
        let base = Instant::now();
        let attacker: IpAddr = "203.0.113.7".parse().unwrap();
        // Nanosecond steps: enough to keep the LRU ordering strictly increasing,
        // far too little for `RATE_REFILL_PER_SEC` to hand back a token. A
        // millisecond step made the whole flood take a second, and the refill —
        // working correctly — then looked exactly like an eviction bypass.
        let at = |n: u64| base + Duration::from_nanos(n);

        // Spend the burst. `RATE_BURST` allowed, then refused.
        for i in 0..(RATE_BURST as u64) {
            assert!(rl.check_at(attacker, at(i)));
        }
        assert!(
            !rl.check_at(attacker, at(RATE_BURST as u64)),
            "burst was not exhausted; the rest of this test proves nothing"
        );

        // Now overflow the map from other addresses, interleaving the attacker
        // so their bucket stays hot — the realistic shape of the attack.
        for i in 0..(MAX_RATE_BUCKETS + 2_000) {
            let t = at(100 + i as u64 * 2);
            let ip: IpAddr = format!("2001:db8:1::{i:x}").parse().unwrap();
            rl.check_at(ip, t);
            assert!(
                !rl.check_at(attacker, t),
                "the attacker got a token back after evictions at i={i}"
            );
        }
    }

    /// The idle sweep is amortised, not per-request. It used to be an O(n) scan
    /// of the whole map on every guarded request, on one shared core.
    #[test]
    fn the_idle_sweep_does_not_run_on_every_request() {
        let rl = RateLimiter::shared();
        let start = Instant::now();
        let a: IpAddr = "198.51.100.1".parse().unwrap();
        let b: IpAddr = "198.51.100.2".parse().unwrap();

        rl.check_at(a, start);
        // `b` arrives an hour later: `a` is now idle past `RATE_IDLE_EVICT`, but
        // the sweep interval has elapsed too, so this request does sweep it.
        rl.check_at(b, start + RATE_IDLE_EVICT + Duration::from_secs(1));
        assert!(
            !rl.inner.lock().unwrap().buckets.contains_key(&a),
            "an idle bucket survived a sweep that was due"
        );

        // A second request moments later must NOT re-sweep — `b` is still there,
        // and the recorded sweep time must not have moved.
        let before = rl.inner.lock().unwrap().last_sweep;
        rl.check_at(b, start + RATE_IDLE_EVICT + Duration::from_secs(2));
        assert_eq!(
            rl.inner.lock().unwrap().last_sweep,
            before,
            "the sweep ran again within the interval"
        );
    }

    #[test]
    fn rate_limited_paths_match_expected() {
        use axum::http::Method;
        assert!(is_rate_limited_path("/login", &Method::GET));
        assert!(is_rate_limited_path("/login", &Method::POST));
        assert!(is_rate_limited_path("/beta/redeem", &Method::POST));
        assert!(is_rate_limited_path("/subscriptions", &Method::POST));
        assert!(is_rate_limited_path("/opml", &Method::POST));
        assert!(is_rate_limited_path("/read-all", &Method::POST));
        assert!(is_rate_limited_path("/admin/invites", &Method::POST));
        assert!(is_rate_limited_path("/entries/42/read", &Method::POST));
        assert!(is_rate_limited_path("/entries/42/star", &Method::POST));
        // Read-only navigation is NOT limited.
        assert!(!is_rate_limited_path("/", &Method::GET));
        assert!(!is_rate_limited_path("/about", &Method::GET));
        assert!(!is_rate_limited_path("/entries/42", &Method::GET));
        assert!(!is_rate_limited_path("/login", &Method::HEAD));
    }

    #[test]
    fn rate_limiter_allows_burst_then_429s() {
        let rl = RateLimiter::shared();
        let ip: IpAddr = "203.0.113.7".parse().unwrap();
        // The full burst passes.
        for _ in 0..(RATE_BURST as usize) {
            assert!(rl.check(ip));
        }
        // The next one (no time elapsed → no refill) is rejected.
        assert!(!rl.check(ip));
        // A different IP has its own bucket.
        let ip2: IpAddr = "203.0.113.8".parse().unwrap();
        assert!(rl.check(ip2));
    }

    #[test]
    fn client_ip_ignores_spoofed_xff_without_trusted_header() {
        // With NO trusted header configured, a client-supplied X-Forwarded-For
        // must be ignored entirely — the limiter keys on the real socket peer,
        // so an attacker can't mint a fresh bucket per forged XFF value.
        let mut h = HeaderMap::new();
        h.insert("x-forwarded-for", "198.51.100.9, 10.0.0.1".parse().unwrap());
        let sock: SocketAddr = "203.0.113.55:1234".parse().unwrap();
        assert_eq!(
            client_ip(&h, Some(&sock), None),
            Some("203.0.113.55".parse().unwrap()),
            "spoofed XFF must not override the socket peer"
        );
    }

    #[test]
    fn client_ip_uses_trusted_header_last_hop() {
        // With a trusted proxy header configured, the client IP comes from THAT
        // header (the proxy overwrites any client copy). On a comma list we take
        // the RIGHT-most hop — the one the trusted proxy appended — so a
        // client-forged left-most value is ignored.
        let sock: SocketAddr = "10.0.0.1:1234".parse().unwrap();

        let mut h = HeaderMap::new();
        h.insert("fly-client-ip", "198.51.100.9".parse().unwrap());
        assert_eq!(
            client_ip(&h, Some(&sock), Some("fly-client-ip")),
            Some("198.51.100.9".parse().unwrap())
        );

        // Attacker prepends a forged hop; the trusted proxy appends the real one.
        let mut h2 = HeaderMap::new();
        h2.insert("x-forwarded-for", "1.2.3.4, 198.51.100.9".parse().unwrap());
        assert_eq!(
            client_ip(&h2, Some(&sock), Some("x-forwarded-for")),
            Some("198.51.100.9".parse().unwrap()),
            "must take the right-most (trusted) hop, not the forged left-most"
        );

        // Trusted header absent → fall back to the socket peer.
        let h3 = HeaderMap::new();
        assert_eq!(
            client_ip(&h3, Some(&sock), Some("fly-client-ip")),
            Some("10.0.0.1".parse().unwrap())
        );
    }

    #[test]
    fn invite_cookie_round_trips_and_rejects_tamper() {
        let secret = "test-cookie-secret-000";
        let sc = sign_invite("FEATHER-ABCDWXYZ", secret);
        let pair = sc.split(';').next().unwrap();
        let mut h = HeaderMap::new();
        h.insert(header::COOKIE, pair.parse().unwrap());
        assert_eq!(
            invite_cookie_code(&h, secret).as_deref(),
            Some("FEATHER-ABCDWXYZ")
        );
        // Wrong secret → rejected.
        assert!(invite_cookie_code(&h, "other").is_none());
    }

    #[tokio::test]
    async fn preflight_valid_expired_and_full() {
        let state = test_state(&["did:plc:admin"]).await;
        // A minted, active code preflights OK.
        let code = store::mint_code(&state.db, "did:plc:admin", 3600)
            .await
            .unwrap();
        assert!(preflight_code(&state, &code).await.is_ok());

        // A code whose expiry is in the past preflights as Expired. (mint_code
        // clamps negative ttl to 0, so back-date the row directly for a
        // deterministic past expiry.)
        let expired = store::mint_code(&state.db, "did:plc:admin", 3600)
            .await
            .unwrap();
        sqlx::query("UPDATE invite_codes SET expires_at = ?1 WHERE code = ?2")
            .bind(chrono::Utc::now().timestamp() - 3600)
            .bind(&expired)
            .execute(&state.db)
            .await
            .unwrap();
        assert_eq!(
            preflight_code(&state, &expired).await,
            Err(store::RedeemError::Expired)
        );

        // Unknown code → NotFound.
        assert_eq!(
            preflight_code(&state, "FEATHER-NOPENOPE").await,
            Err(store::RedeemError::NotFound)
        );

        // Fill to cap (cap=3; the admin seed already took 1 seat) then preflight
        // must report CapacityFull.
        store::grant_access(&state.db, "did:plc:b", None, "admin", None)
            .await
            .unwrap();
        store::grant_access(&state.db, "did:plc:c", None, "admin", None)
            .await
            .unwrap();
        assert_eq!(store::count_beta_access(&state.db).await.unwrap(), 3);
        assert_eq!(
            preflight_code(&state, &code).await,
            Err(store::RedeemError::CapacityFull)
        );
    }

    // -- Bot claim link + shared-secret mint ---------------------------------

    /// A test state with a configured bot secret (so `/bot/claims` is live).
    async fn bot_state(bot_secret: &str) -> AppState {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        store::ensure_seed(&db, &["did:plc:admin".to_string()])
            .await
            .unwrap();
        let config = Config {
            allowed_dids: vec!["did:plc:admin".to_string()],
            cookie_secret: "test-cookie-secret-000".to_string(),
            beta_cap: 3,
            bot_secret: Some(bot_secret.to_string()),
            public_url: "https://feather-reader.com".to_string(),
            ..Config::default()
        };
        AppState::new(config, db).unwrap()
    }

    #[test]
    fn claim_token_round_trips_and_rejects_tamper() {
        let secret = "test-cookie-secret-000";
        let token = sign_claim_token("FEATHER-ABCDWXYZ", secret);
        // No cookie framing — a bare URL-safe token.
        assert!(!token.contains(';'));
        assert_eq!(
            claim_token_code(&token, secret).as_deref(),
            Some("FEATHER-ABCDWXYZ")
        );
        // Wrong secret → rejected.
        assert!(claim_token_code(&token, "other").is_none());
        // Tampered token → rejected.
        let mut bad = token.clone();
        bad.push('x');
        assert!(claim_token_code(&bad, secret).is_none());
        // The token is NOT confidential: it is `b64url(code).<sig>`, so the code is
        // only base64-obscured (not verbatim, but TRIVIALLY decodable — anyone can
        // recover it WITHOUT the secret). The security is single-use + HMAC
        // integrity + rate-limit, not secrecy of the code. Assert the code half is
        // publicly decodable (a plain base64url decode, no secret involved).
        let (b64, _sig) = token.split_once('.').expect("token is b64.sig");
        assert_eq!(
            test_b64url_decode(b64).as_deref(),
            Some("FEATHER-ABCDWXYZ".as_bytes()),
            "the code half of the token is plain base64url, decodable by anyone"
        );
    }

    /// Minimal URL-safe base64 (no padding) decoder for the test above, proving the
    /// claim token's code half needs NO secret to recover (it is not confidential).
    fn test_b64url_decode(input: &str) -> Option<Vec<u8>> {
        fn val(c: u8) -> Option<u32> {
            match c {
                b'A'..=b'Z' => Some((c - b'A') as u32),
                b'a'..=b'z' => Some((c - b'a' + 26) as u32),
                b'0'..=b'9' => Some((c - b'0' + 52) as u32),
                b'-' => Some(62),
                b'_' => Some(63),
                _ => None,
            }
        }
        let mut out = Vec::with_capacity(input.len() / 4 * 3);
        for chunk in input.as_bytes().chunks(4) {
            let mut n = 0u32;
            let mut bits = 0;
            for &c in chunk {
                n = (n << 6) | val(c)?;
                bits += 6;
            }
            let bytes = bits / 8;
            n <<= 24 - bits;
            for i in 0..bytes {
                out.push((n >> (16 - i * 8)) as u8);
            }
        }
        Some(out)
    }

    #[tokio::test]
    async fn bot_mint_then_claim_grants_a_seat() {
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state.clone());

        // 1. Mint a claim via the shared-secret endpoint.
        let resp = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", "bot-secret-abcdef")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let json: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
        let token = json["token"].as_str().unwrap().to_string();
        let url = json["url"].as_str().unwrap();
        assert!(url.starts_with("https://feather-reader.com/claim?t="));
        // The raw code is returned for the bot's records but not embedded in url.
        assert!(json["code"].as_str().unwrap().starts_with("FEATHER-"));
        assert!(!url.contains("FEATHER-"));

        // 2. Follow the claim link → reserves the invite cookie + redirects to /login.
        let resp = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("GET")
                    .uri(format!("/claim?t={}", qenc(&token)))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert_eq!(resp.headers().get(header::LOCATION).unwrap(), "/login");
        let set_cookie = resp
            .headers()
            .get(header::SET_COOKIE)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(set_cookie.starts_with(INVITE_COOKIE), "{set_cookie}");

        // 3. The reserved cookie carries the same code the token wrapped, and
        //    redeeming it (the callback's machinery) grants a seat.
        let code = claim_token_code(&token, &state.config.cookie_secret).unwrap();
        let out = store::redeem_code(
            &state.db,
            &code,
            "did:plc:follower",
            None,
            state.config.beta_cap,
        )
        .await
        .unwrap();
        assert_eq!(out, Ok(()));
        assert!(store::has_beta_access(&state.db, "did:plc:follower")
            .await
            .unwrap());
    }

    #[tokio::test]
    async fn claim_with_invalid_token_bounces() {
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("GET")
                    .uri("/claim?t=not-a-real-token")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        // Renders the invite page (200), NOT a redirect to /login.
        assert_eq!(resp.status(), StatusCode::OK);
    }

    #[tokio::test]
    async fn claim_with_used_token_is_refused() {
        let state = bot_state("bot-secret-abcdef").await;
        // Mint a code + wrap it, then redeem it out from under the token.
        let code = store::mint_code(&state.db, "did:plc:admin", 3600)
            .await
            .unwrap();
        let token = sign_claim_token(&code, &state.config.cookie_secret);
        store::redeem_code(
            &state.db,
            &code,
            "did:plc:someone",
            None,
            state.config.beta_cap,
        )
        .await
        .unwrap()
        .unwrap();
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("GET")
                    .uri(format!("/claim?t={}", qenc(&token)))
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        // A used code → the invite page (AlreadyRedeemed), not a fresh reservation.
        assert_eq!(resp.status(), StatusCode::OK);
        assert!(resp.headers().get(header::SET_COOKIE).is_none());
    }

    #[tokio::test]
    async fn bot_claims_rejects_bad_and_missing_secret() {
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state);
        // Wrong secret.
        let resp = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", "wrong")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
        // Missing secret.
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
    }

    #[tokio::test]
    async fn bot_claims_disabled_when_secret_unset() {
        // test_state configures NO bot secret → the endpoint is off (503).
        let state = test_state(&["did:plc:admin"]).await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", "anything")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SERVICE_UNAVAILABLE);
    }

    #[tokio::test]
    async fn bot_claims_refuses_at_capacity() {
        let state = bot_state("bot-secret-abcdef").await;
        // cap=3, admin seed took 1 seat. Grant 2 more to fill it.
        store::grant_access(&state.db, "did:plc:b", None, "admin", None)
            .await
            .unwrap();
        store::grant_access(&state.db, "did:plc:c", None, "admin", None)
            .await
            .unwrap();
        assert_eq!(store::count_beta_access(&state.db).await.unwrap(), 3);
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", "bot-secret-abcdef")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::CONFLICT);
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        assert!(String::from_utf8_lossy(&bytes).contains("full"));
    }

    #[tokio::test]
    async fn bot_claims_counts_outstanding_codes_against_cap() {
        let state = bot_state("bot-secret-abcdef").await;
        // cap=3, admin seed = 1 seat. Two outstanding active codes = 3 committed.
        store::mint_code(&state.db, "did:plc:admin", 3600)
            .await
            .unwrap();
        store::mint_code(&state.db, "did:plc:admin", 3600)
            .await
            .unwrap();
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", "bot-secret-abcdef")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        // 1 seat + 2 outstanding >= cap 3 → refused even though only 1 real seat used.
        assert_eq!(resp.status(), StatusCode::CONFLICT);
    }

    /// POST /bot/claims with a JSON body carrying the follower DID.
    async fn post_bot_claim_for(
        app: &axum::Router,
        secret: &str,
        did: &str,
    ) -> (StatusCode, serde_json::Value) {
        let resp = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", secret)
                    .header("content-type", "application/json")
                    .body(Body::from(format!(
                        "{{\"did\":\"{did}\",\"handle\":\"who.test\"}}"
                    )))
                    .unwrap(),
            )
            .await
            .unwrap();
        let status = resp.status();
        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let json = if bytes.is_empty() {
            serde_json::Value::Null
        } else {
            serde_json::from_slice(&bytes).unwrap_or(serde_json::Value::Null)
        };
        (status, json)
    }

    #[tokio::test]
    async fn bot_claims_returns_already_seated_for_a_member() {
        // A DID that already holds beta access must get `already_seated` with NO
        // code/url — the bot posts nothing. This is the server-side backstop that
        // survives a bot-host state loss (it would otherwise re-mint + re-post).
        let state = bot_state("bot-secret-abcdef").await;
        store::grant_access(&state.db, "did:plc:member", None, "admin", None)
            .await
            .unwrap();
        let app = router(state.clone());
        let (status, json) = post_bot_claim_for(&app, "bot-secret-abcdef", "did:plc:member").await;
        assert_eq!(status, StatusCode::OK);
        assert_eq!(json["status"], "already_seated");
        assert_eq!(json["code"], "");
        assert_eq!(json["url"], "");
        // No new invite code was minted for the seated DID.
        assert!(store::find_active_code_for_did(&state.db, "did:plc:member")
            .await
            .unwrap()
            .is_none());
    }

    #[tokio::test]
    async fn bot_claims_is_idempotent_per_did_returns_same_code() {
        // Two mint requests for the SAME follower DID must return the SAME code
        // (the app is authoritative), never a second one — so a bot-host state loss
        // re-requesting cannot double-mint or double-post.
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state.clone());

        let (s1, j1) = post_bot_claim_for(&app, "bot-secret-abcdef", "did:plc:follower1").await;
        assert_eq!(s1, StatusCode::OK);
        assert_eq!(j1["status"], "minted");
        let code1 = j1["code"].as_str().unwrap().to_string();

        let (s2, j2) = post_bot_claim_for(&app, "bot-secret-abcdef", "did:plc:follower1").await;
        assert_eq!(s2, StatusCode::OK);
        assert_eq!(j2["status"], "existing");
        assert_eq!(j2["code"].as_str().unwrap(), code1, "same code returned");
        assert_eq!(j2["url"], j1["url"], "same url returned");

        // Exactly ONE active code exists for that DID.
        assert_eq!(store::count_active_codes(&state.db).await.unwrap(), 1);
    }

    #[tokio::test]
    async fn bot_claims_records_intended_did_at_mint() {
        // A fresh mint records the follower DID so the lookup finds it.
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state.clone());
        let (status, json) =
            post_bot_claim_for(&app, "bot-secret-abcdef", "did:plc:follower2").await;
        assert_eq!(status, StatusCode::OK);
        let code = json["code"].as_str().unwrap();
        assert_eq!(
            store::find_active_code_for_did(&state.db, "did:plc:follower2")
                .await
                .unwrap()
                .as_deref(),
            Some(code)
        );
    }

    #[tokio::test]
    async fn bot_claims_concurrent_same_did_never_double_mints() {
        // S4: two concurrent /bot/claims for ONE follower DID must not both mint an
        // active code. The dedupe check (3b) and the mint are separate statements,
        // so a race can slip both past 3b's `Ok(None)`; the partial unique index
        // then makes the loser's INSERT conflict, and the handler recovers by
        // returning the winner's code (status `existing`) rather than 500-ing.
        // Result: exactly ONE active code, and BOTH callers get a usable code.
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state.clone());

        let a = post_bot_claim_for(&app, "bot-secret-abcdef", "did:plc:racer");
        let b = post_bot_claim_for(&app, "bot-secret-abcdef", "did:plc:racer");
        let ((sa, ja), (sb, jb)) = tokio::join!(a, b);

        assert_eq!(sa, StatusCode::OK, "first response: {ja:?}");
        assert_eq!(sb, StatusCode::OK, "second response: {jb:?}");

        // Exactly one active code for the DID — the whole point of the fix.
        assert_eq!(
            store::count_active_codes(&state.db).await.unwrap(),
            1,
            "concurrent mints must not create two active codes"
        );

        // Both callers received the SAME (single) code, and neither got a 500.
        let ca = ja["code"].as_str().unwrap_or("");
        let cb = jb["code"].as_str().unwrap_or("");
        assert!(!ca.is_empty() && !cb.is_empty(), "both must return a code");
        assert_eq!(ca, cb, "both callers must get the one minted code");
        // One is `minted` (the winner), the other `minted` or `existing` depending
        // on interleaving — but never an error status.
        for st in [&ja["status"], &jb["status"]] {
            let s = st.as_str().unwrap_or("");
            assert!(s == "minted" || s == "existing", "unexpected status {s:?}");
        }
    }

    #[tokio::test]
    async fn bot_claims_rejects_malformed_json_body() {
        let state = bot_state("bot-secret-abcdef").await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/bot/claims")
                    .header("x-bot-secret", "bot-secret-abcdef")
                    .header("content-type", "application/json")
                    .body(Body::from("{not json"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
    }

    #[tokio::test]
    async fn favicon_ico_served_at_root() {
        // Browsers request bare /favicon.ico regardless of the <link rel="icon">
        // tags in <head>; the root route must serve the icon, not 404.
        let state = test_state(&[]).await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .uri("/favicon.ico")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let ct = resp
            .headers()
            .get(header::CONTENT_TYPE)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            ct.contains("icon") || ct.starts_with("image/"),
            "content-type = {ct}"
        );
    }

    #[tokio::test]
    async fn login_without_invite_redirects_to_beta_redeem() {
        // No allow-list seed, no invite cookie: starting OAuth must be refused.
        let state = test_state(&[]).await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/login")
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("handle=alice.bsky.social"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert_eq!(
            resp.headers().get(header::LOCATION).unwrap(),
            "/beta/redeem"
        );
    }

    #[tokio::test]
    async fn login_with_valid_invite_cookie_starts_oauth() {
        let state = test_state(&[]).await;
        let cookie = sign_invite("FEATHER-ABCDWXYZ", &state.config.cookie_secret);
        let cookie = cookie.split(';').next().unwrap().to_string();
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/login")
                    .header("content-type", "application/x-www-form-urlencoded")
                    .header(header::COOKIE, cookie)
                    .body(Body::from("handle=alice.bsky.social"))
                    .unwrap(),
            )
            .await
            .unwrap();
        // Redirects into the sidecar login (not to /beta/redeem).
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(loc.contains("/login"), "loc = {loc}");
        assert_ne!(loc, "/beta/redeem");
    }

    /// A resolver that always fails — proves the fast paths short-circuit BEFORE
    /// any network resolution and that a resolution failure fails closed.
    async fn resolver_never(_handle: String) -> Option<String> {
        None
    }

    /// A resolver that maps every handle to `did`.
    fn resolver_to(did: &'static str) -> impl FnOnce(String) -> std::future::Ready<Option<String>> {
        move |_handle| std::future::ready(Some(did.to_string()))
    }

    /// Path 3: a cookie-less visitor whose submitted handle resolves to a DID
    /// that already holds a seat (the seeded-admin first-login case) passes the
    /// gate — no session cookie, no invite code.
    #[tokio::test]
    async fn may_start_oauth_honors_seat_via_resolved_handle() {
        // The seeded admin holds a seat (via ALLOWED_DIDS → ensure_seed) but has
        // no cookie on a fresh deploy.
        let state = test_state(&["did:plc:admin"]).await;
        let headers = HeaderMap::new();
        assert!(
            may_start_oauth_with(
                &state,
                &headers,
                "admin.example",
                resolver_to("did:plc:admin")
            )
            .await,
            "a handle resolving to a seated DID must pass the gate"
        );
    }

    /// Path 3, negative: a handle that resolves to a DID with NO seat is bounced
    /// — the anti-abuse intent is preserved (resolution succeeds, seat check
    /// fails).
    #[tokio::test]
    async fn may_start_oauth_bounces_non_member_handle() {
        let state = test_state(&["did:plc:admin"]).await;
        let headers = HeaderMap::new();
        assert!(
            !may_start_oauth_with(
                &state,
                &headers,
                "rando.example",
                resolver_to("did:plc:rando")
            )
            .await,
            "a resolved DID with no seat must be bounced"
        );
    }

    /// Fail-closed: an unresolvable/malformed handle (resolver returns `None`)
    /// bounces gracefully — no panic, no handshake.
    #[tokio::test]
    async fn may_start_oauth_fails_closed_on_unresolvable_handle() {
        let state = test_state(&["did:plc:admin"]).await;
        let headers = HeaderMap::new();
        assert!(
            !may_start_oauth_with(&state, &headers, "not a handle", resolver_never).await,
            "an unresolvable handle must fail closed"
        );
    }

    /// The session-cookie fast path admits a seated member WITHOUT calling the
    /// resolver (proven by injecting `resolver_never`, which would otherwise
    /// bounce).
    #[tokio::test]
    async fn may_start_oauth_session_cookie_shortcircuits_resolution() {
        let state = test_state(&[]).await;
        let did = "did:plc:member";
        store::grant_access(&state.db, did, Some("member.example"), "test", None)
            .await
            .unwrap();
        let cookie = session_cookie(&state, did, Some("member.example"));
        let mut headers = HeaderMap::new();
        headers.insert(header::COOKIE, cookie.parse().unwrap());
        assert!(
            may_start_oauth_with(&state, &headers, "member.example", resolver_never).await,
            "a seated session cookie must pass without resolution"
        );
    }

    /// The invite-cookie fast path admits WITHOUT calling the resolver.
    #[tokio::test]
    async fn may_start_oauth_invite_cookie_shortcircuits_resolution() {
        let state = test_state(&[]).await;
        let cookie = sign_invite("FEATHER-ABCDWXYZ", &state.config.cookie_secret);
        let cookie = cookie.split(';').next().unwrap().to_string();
        let mut headers = HeaderMap::new();
        headers.insert(header::COOKIE, cookie.parse().unwrap());
        assert!(
            may_start_oauth_with(&state, &headers, "someone.example", resolver_never).await,
            "a valid invite cookie must pass without resolution"
        );
    }

    #[tokio::test]
    async fn admin_mint_requires_admin_seed_did() {
        let state = test_state(&["did:plc:admin"]).await;
        // A non-admin (but beta'd) session is forbidden.
        store::grant_access(&state.db, "did:plc:rando", None, "test", None)
            .await
            .unwrap();
        let rando_cookie = session_cookie(&state, "did:plc:rando", None);
        // An admin session is allowed.
        let admin_cookie = session_cookie(&state, "did:plc:admin", None);
        let app = router(state);

        let forbidden = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/invites?n=2")
                    .header(header::COOKIE, rando_cookie)
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(forbidden.status(), StatusCode::FORBIDDEN);

        let ok = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/invites?n=2")
                    .header(header::COOKIE, admin_cookie)
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(ok.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(ok.into_body(), 64 * 1024)
            .await
            .unwrap();
        let body = String::from_utf8(bytes.to_vec()).unwrap();
        let minted: Vec<&str> = body.lines().filter(|l| !l.is_empty()).collect();
        assert_eq!(minted.len(), 2);
        assert!(minted.iter().all(|c| c.starts_with("FEATHER-")));
    }

    #[tokio::test]
    async fn admin_mint_unauthenticated_is_401() {
        let state = test_state(&["did:plc:admin"]).await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/admin/invites")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
    }

    /// A state whose `/about` renders the adoption line, seeded with one
    /// observation.
    async fn adoption_state(repos: i64, truncated: bool) -> AppState {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        store::record_network_stat(
            &db,
            &store::NetworkStat {
                key: store::ADOPTION_STAT_KEY.to_string(),
                source: "https://relay1.us-west.bsky.network".to_string(),
                value: repos,
                truncated,
                observed_at: "2026-08-13T04:05:06Z".to_string(),
            },
        )
        .await
        .unwrap();
        let config = Config {
            cookie_secret: "test-cookie-secret-000".to_string(),
            show_adoption: true,
            ..Config::default()
        };
        AppState::new(config, db).unwrap()
    }

    async fn about_body(state: AppState) -> String {
        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri("/about")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), 256 * 1024)
            .await
            .unwrap();
        String::from_utf8(bytes.to_vec()).unwrap()
    }

    /// Default config ⇒ the flag is off ⇒ no line, and no query is issued.
    #[tokio::test]
    async fn about_omits_adoption_line_by_default() {
        let state = test_state(&[]).await;
        assert!(!state.config.show_adoption);
        let body = about_body(state).await;
        assert!(
            !body.contains("atproto network"),
            "the adoption line must not render by default"
        );
    }

    #[tokio::test]
    async fn about_renders_adoption_line_when_enabled() {
        // **A distinctive count, and asserted IN ITS SENTENCE.**
        //
        // This used to seed 4 and assert `body.contains("4")`, which the
        // colophon's `width="44"` satisfies whatever the count is — so
        // hardcoding the rendered number passed. Both halves are needed: a
        // digit that does not occur incidentally, and the assertion tied to the
        // phrase it belongs to.
        let body = about_body(adoption_state(7_318, false).await).await;
        // The count and its phrase are on separate template lines, so compare
        // against a whitespace-collapsed copy rather than the raw HTML.
        let flat = body.split_whitespace().collect::<Vec<_>>().join(" ");
        assert!(
            flat.contains("7318 accounts on the atproto network hold"),
            "the count did not render in its own sentence: {flat}",
        );
        assert!(
            body.contains("accounts on the atproto network hold"),
            "{body}"
        );
        assert!(
            body.contains("2026-08-13"),
            "the observation date must render"
        );
        assert!(
            body.contains("lower bound"),
            "the non-archival caveat must ride along with the number"
        );
        assert!(
            !body.contains("At least"),
            "an untruncated count is exact-ish"
        );
    }

    /// A count of one must read as "1 account … holds", not "1 accounts … hold".
    #[tokio::test]
    async fn about_adoption_line_is_singular_at_one() {
        let body = about_body(adoption_state(1, false).await).await;
        assert!(
            body.contains("account on the atproto network holds"),
            "{body}"
        );
    }

    /// A truncated observation is a floor, and must say so.
    #[tokio::test]
    async fn about_adoption_line_says_at_least_when_truncated() {
        let body = about_body(adoption_state(25_000, true).await).await;
        assert!(body.contains("At least"), "{body}");
    }

    /// Flag on but no observation (or a zero) ⇒ 200, no line, no error.
    #[tokio::test]
    async fn about_omits_line_when_enabled_with_no_observation() {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        let config = Config {
            cookie_secret: "test-cookie-secret-000".to_string(),
            show_adoption: true,
            ..Config::default()
        };
        let body = about_body(AppState::new(config, db).unwrap()).await;
        assert!(!body.contains("atproto network"));
    }

    #[tokio::test]
    async fn cache_control_public_on_about_no_store_on_authed() {
        let state = test_state(&["did:plc:admin"]).await;
        let admin_cookie = session_cookie(&state, "did:plc:admin", None);
        let app = router(state);

        // /about → public, cacheable.
        let about = app
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/about")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            about.headers().get(header::CACHE_CONTROL).unwrap(),
            "public, max-age=300"
        );
        // The security headers are still intact.
        // The VALUE, spelled out here rather than compared to the constant —
        // `== CONTENT_SECURITY_POLICY` passes with the constant gutted. This
        // used to assert only that the header existed, which a policy of
        // `default-src *` satisfies.
        assert_eq!(
            about.headers()["content-security-policy"],
            EXPECTED_CSP,
            "the CSP is not the policy the router promises"
        );
        assert_eq!(about.headers().get("x-frame-options").unwrap(), "DENY");

        // /privacy and /terms are static public pages → public, cacheable.
        for path in ["/privacy", "/terms"] {
            let resp = app
                .clone()
                .oneshot(Request::builder().uri(path).body(Body::empty()).unwrap())
                .await
                .unwrap();
            assert_eq!(resp.status(), StatusCode::OK);
            assert_eq!(
                resp.headers().get(header::CACHE_CONTROL).unwrap(),
                "public, max-age=300",
                "{path} should be publicly cacheable"
            );
            // Security headers apply to these pages too.
            assert_eq!(resp.headers()["content-security-policy"], EXPECTED_CSP);
            assert_eq!(resp.headers().get("x-frame-options").unwrap(), "DENY");
        }

        // The bare /login landing → public, cacheable.
        let login = app
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/login")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            login.headers().get(header::CACHE_CONTROL).unwrap(),
            "public, max-age=300"
        );

        // An authenticated page → no-store.
        let home = app
            .oneshot(
                Request::builder()
                    .uri("/")
                    .header(header::COOKIE, admin_cookie)
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            home.headers().get(header::CACHE_CONTROL).unwrap(),
            "no-store"
        );
    }

    #[tokio::test]
    async fn beta_redeem_page_renders() {
        let state = test_state(&[]).await;
        let app = router(state);
        let resp = app
            .oneshot(
                Request::builder()
                    .uri("/beta/redeem")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), 256 * 1024)
            .await
            .unwrap();
        let html = String::from_utf8(bytes.to_vec()).unwrap();
        assert!(html.contains("Invite code"));
        assert!(html.contains("/beta/redeem"));
    }

    #[tokio::test]
    async fn rate_limit_returns_429_after_burst() {
        // Configure a trusted proxy header so the limiter keys on the forwarded
        // IP (the oneshot harness sets no ConnectInfo socket peer).
        let db = store::init_url("sqlite::memory:").await.unwrap();
        store::ensure_seed(&db, &[]).await.unwrap();
        let config = Config {
            cookie_secret: "test-cookie-secret-000".to_string(),
            beta_cap: 3,
            trusted_ip_header: Some("cf-connecting-ip".to_string()),
            ..Config::default()
        };
        let state = AppState::new(config, db).unwrap();
        let app = router(state);
        // Hammer POST /beta/redeem past the burst from a single (trusted) IP. The
        // handler itself returns 200 (re-render) on a bad code; the limiter is
        // what eventually yields 429.
        let mut saw_429 = false;
        for _ in 0..(RATE_BURST as usize + 5) {
            let resp = app
                .clone()
                .oneshot(
                    Request::builder()
                        .method("POST")
                        .uri("/beta/redeem")
                        .header("content-type", "application/x-www-form-urlencoded")
                        .header("cf-connecting-ip", "203.0.113.200")
                        .body(Body::from("code=FEATHER-NOPENOPE"))
                        .unwrap(),
                )
                .await
                .unwrap();
            if resp.status() == StatusCode::TOO_MANY_REQUESTS {
                saw_429 = true;
                break;
            }
        }
        assert!(saw_429, "expected a 429 after exhausting the burst");
    }

    /// **A forged `X-Forwarded-For` does not key the limiter** — the property
    /// the middleware's comment cites this test as proof of.
    ///
    /// The previous version rotated the forged header and asserted that no
    /// request was EVER 429'd. Rotating addresses can never exhaust a per-IP
    /// burst, so that assertion held whether the header was trusted or
    /// ignored — it passed in the vulnerable configuration too. And with no
    /// socket peer the limiter fails open, so nothing could have been keyed on
    /// anything. Now one real peer sends `RATE_BURST + 5` requests, each with
    /// a DIFFERENT forged header, and the last must be 429: they all landed in
    /// the peer's bucket. A limiter keying on the header mints a fresh bucket
    /// per request and never trips — which is exactly what the mutation does.
    #[tokio::test]
    async fn a_forged_forwarded_for_header_does_not_key_the_limiter() {
        let state = test_state(&[]).await;
        assert!(
            state.config.trusted_ip_header.is_none(),
            "no proxy header is trusted here"
        );
        let app = router(state);
        let peer = std::net::SocketAddr::from(([203, 0, 113, 7], 40000));
        let mut saw_429 = false;
        for i in 0..(RATE_BURST as usize + 5) {
            let forged = format!("10.9.8.{}", i % 250);
            let resp = app
                .clone()
                .oneshot(
                    Request::builder()
                        .method("POST")
                        .uri("/beta/redeem")
                        .header("content-type", "application/x-www-form-urlencoded")
                        .header("x-forwarded-for", forged)
                        .extension(axum::extract::ConnectInfo(peer))
                        .body(Body::from("code=FEATHER-NOPENOPE"))
                        .unwrap(),
                )
                .await
                .unwrap();
            if resp.status() == StatusCode::TOO_MANY_REQUESTS {
                saw_429 = true;
                break;
            }
        }
        assert!(
            saw_429,
            "rotating a forged X-Forwarded-For minted fresh buckets: the limiter is keyed on an attacker-chosen header"
        );
    }

    // -- OPML import body cap (DefaultBodyLimit → 413) -------------------------

    /// **A private feed is refused BEFORE it is fetched.** The add path's
    /// privacy gate had no test at all — `private_feeds_are_classified_private_
    /// across_providers` says "the add + OPML paths both gate on this
    /// classifier" and nothing checked either. The gate exists so a
    /// token-bearing URL never reaches the network; the assertion that
    /// matters is the server's hit count: zero.
    #[tokio::test]
    async fn subscribing_to_a_private_feed_never_reaches_the_network() {
        let did = "did:plc:privateadder";
        let state = test_state_with_caps(did, 0, 0).await;
        let (base, hits) = crate::net::tests::serve_body_counted(b"<rss/>".to_vec()).await;
        let port: u16 = base
            .trim_end_matches('/')
            .rsplit(':')
            .next()
            .unwrap()
            .parse()
            .unwrap();
        crate::net::test_host_override(
            "private-add.test",
            std::net::SocketAddr::from(([127, 0, 0, 1], port)),
        );
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!(
                        "url=http%3A%2F%2Fprivate-add.test%3A{port}%2Ffeed%2Fprivate%2Fdeadbeefcafe1234"
                    )))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(loc.contains("Private"), "not refused as private: {loc}");
        assert_eq!(
            hits.load(std::sync::atomic::Ordering::SeqCst),
            0,
            "the private feed was FETCHED before being refused"
        );
        assert_eq!(store::count_feeds(&state.db).await.unwrap(), 0);
    }

    /// **OPML import skips a private feed without storing or publishing it.**
    /// The import path does not fetch, so "never fetched" is not the signal
    /// here; "never stored, never written to the PDS" is. The batch write's
    /// bytes are captured and must not carry the URL.
    #[tokio::test]
    async fn opml_import_skips_a_private_feed_without_storing_or_publishing_it() {
        let did = "did:plc:renamer4";
        let (sidecar, bodies) = spawn_logging_sidecar().await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let tokened = "https://www.patreon.com/rss/author?auth=Zm9vYmFyc2VjcmV0dG9rZW4";
        let opml = format!(
            "<?xml version=\"1.0\"?>\n<opml version=\"2.0\"><head><title>t</title></head><body>\n\
             <outline type=\"rss\" text=\"Public\" xmlUrl=\"https://public.example/feed.xml\"/>\n\
             <outline type=\"rss\" text=\"Paid\" xmlUrl=\"{tokened}\"/>\n\
             </body></opml>"
        );
        let (ct, body) = opml_multipart(opml.as_bytes());
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header(header::COOKIE, cookie)
                    .header("content-type", ct)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("skipped%20as%20private"),
            "not reported as skipped: {loc}"
        );
        assert!(store::get_feed_by_url(&state.db, tokened)
            .await
            .unwrap()
            .is_none());
        let sent = bodies.lock().unwrap().join("\n");
        assert!(
            sent.contains("public.example"),
            "the public feed was not written: {sent}"
        );
        assert!(
            !sent.contains("Zm9vYmFyc2VjcmV0dG9rZW4"),
            "the secret was PUBLISHED to the PDS: {sent}"
        );
    }

    /// **`GET /login?handle=` is gated like `POST /login`.** Only the POST was
    /// tested; the GET form starts the same handshake and had no test, so
    /// deleting its gate left the suite green.
    #[tokio::test]
    async fn get_login_without_a_seat_is_refused() {
        let state = test_state(&[]).await;
        let resp = router(state)
            .oneshot(
                Request::builder()
                    .method("GET")
                    .uri("/login?handle=alice.bsky.social")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert_eq!(
            resp.headers().get(header::LOCATION).unwrap(),
            "/beta/redeem"
        );
    }

    /// A sidecar fake that answers every request `ok` and records the PATH of
    /// each in arrival order, plus every body — for asserting what was sent,
    /// and in what order.
    async fn spawn_logging_sidecar() -> (String, std::sync::Arc<std::sync::Mutex<Vec<String>>>) {
        use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let log = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
        let sink = log.clone();
        tokio::spawn(async move {
            loop {
                let Ok((mut sock, _)) = listener.accept().await else {
                    break;
                };
                let mut raw: Vec<u8> = Vec::new();
                let mut chunk = [0u8; 4096];
                let text = loop {
                    let Ok(n) = sock.read(&mut chunk).await else {
                        break String::new();
                    };
                    if n == 0 {
                        break String::from_utf8_lossy(&raw).to_string();
                    }
                    raw.extend_from_slice(&chunk[..n]);
                    let Some(split) = raw.windows(4).position(|w| w == b"\r\n\r\n") else {
                        continue;
                    };
                    let (head, body) = raw.split_at(split + 4);
                    let want = String::from_utf8_lossy(head).lines().find_map(|l| {
                        let (k, v) = l.split_once(':')?;
                        k.eq_ignore_ascii_case("content-length")
                            .then(|| v.trim().parse::<usize>().ok())?
                    });
                    if want.is_none_or(|w| body.len() >= w) {
                        break String::from_utf8_lossy(&raw).to_string();
                    }
                };
                let path = text
                    .lines()
                    .next()
                    .and_then(|l| l.split_whitespace().nth(1))
                    .unwrap_or("")
                    .to_string();
                let body_text = text
                    .split_once("\r\n\r\n")
                    .map(|(_, b)| b)
                    .unwrap_or("")
                    .to_string();
                sink.lock().unwrap().push(format!("{path} {body_text}"));
                let body = serde_json::json!({ "ok": true, "did": "did:plc:x", "revoked": true, "hadSession": true, "data": {"uri": "at://did:plc:x/c/r", "cid": "bafy"} }).to_string();
                let resp = format!(
                    "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
                    body.len(),
                    body
                );
                let _ = sock.write_all(resp.as_bytes()).await;
                let _ = sock.flush().await;
            }
        });
        (format!("http://{addr}"), log)
    }

    /// **Sign-out flushes dirty read-state BEFORE it revokes — through the
    /// route.** The previous version of this test called
    /// `flush_before_revoke` and `revoke_everywhere` itself and asserted one
    /// flush attempt; its doc claimed deleting the call from the handler
    /// "drops that to zero", which was false — the handler was never run.
    /// Deleting the call left the suite green: #117 regressing in full, with
    /// the test named after it still passing. Now `POST /logout` is driven and
    /// the sidecar's log must show a repo write BEFORE the revoke.
    #[tokio::test]
    async fn signing_out_flushes_before_it_revokes_through_the_route() {
        let did = "did:plc:ewvi7nxzyoun6zhxrhs64oiz";
        let (sidecar, log) = spawn_logging_sidecar().await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        crate::store::upsert_cursor(
            &state.db,
            &crate::store::ReadCursor {
                did: did.to_string(),
                feed_url: "https://example.com/feed.xml".into(),
                read_through: None,
                read_ids: "[\"1\"]".into(),
                unread_ids: "[]".into(),
                dirty: true,
                pds_created: false,
                updated_at: "2026-09-13T21:22:40Z".into(),
            },
        )
        .await
        .unwrap();
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/logout")
                    .header(header::COOKIE, cookie)
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);

        let entries = log.lock().unwrap().clone();
        let flush = entries
            .iter()
            .position(|e| e.starts_with("/internal/repo "));
        let revoke = entries
            .iter()
            .position(|e| e.starts_with("/internal/revoke "));
        assert!(revoke.is_some(), "sign-out did not revoke: {entries:?}");
        assert!(
            flush.is_some(),
            "sign-out did not attempt a flush before revoking: {entries:?}"
        );
        assert!(
            flush < revoke,
            "the flush arrived AFTER the revoke — no session left to send it with: {entries:?}"
        );
    }

    /// The policy, as a literal: the backstop the router calls "neutralises any
    /// XSS that slips past sanitization". `script-src 'self'` and no
    /// `'unsafe-inline'` on it are the two clauses that make it one.
    const EXPECTED_CSP: &str = "default-src 'self'; \
     script-src 'self'; \
     style-src 'self' 'unsafe-inline'; \
     img-src 'self' https: data:; \
     font-src 'self'; \
     connect-src 'self'; \
     form-action 'self'; \
     base-uri 'self'; \
     frame-ancestors 'none'; \
     object-src 'none'";

    /// Build a `multipart/form-data` body carrying a single `file` field whose
    /// contents are `payload`, returning `(content_type, body_bytes)`.
    fn opml_multipart(payload: &[u8]) -> (String, Vec<u8>) {
        let boundary = "----featherreadertestboundary";
        let mut body = Vec::new();
        body.extend_from_slice(format!("--{boundary}\r\n").as_bytes());
        body.extend_from_slice(
            b"Content-Disposition: form-data; name=\"file\"; filename=\"feeds.opml\"\r\n",
        );
        body.extend_from_slice(b"Content-Type: text/x-opml\r\n\r\n");
        body.extend_from_slice(payload);
        body.extend_from_slice(format!("\r\n--{boundary}--\r\n").as_bytes());
        (format!("multipart/form-data; boundary={boundary}"), body)
    }

    #[tokio::test]
    async fn opml_import_oversize_upload_returns_413() {
        let state = test_state(&["did:plc:admin"]).await;
        let cookie = session_cookie(&state, "did:plc:admin", None);
        let app = router(state);

        // A payload comfortably above the route cap.
        let payload = vec![b'a'; OPML_BODY_LIMIT + 1024];
        let (content_type, body) = opml_multipart(&payload);

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header("content-type", content_type)
                    .header(header::COOKIE, cookie)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            resp.status(),
            StatusCode::PAYLOAD_TOO_LARGE,
            "an over-cap OPML upload must be rejected with 413, not collapsed to 500"
        );
    }

    /// **The route's own cap is what refuses this, not the framework's.**
    ///
    /// `OPML_BODY_LIMIT` used to equal axum's `DefaultBodyLimit` (2 MiB), so
    /// the route's layer was a no-op — deleting it left every test green, and
    /// `opml_import_oversize_upload_returns_413` was really testing axum. The
    /// limit is 1 MiB now, strictly tighter, and this uploads a payload that
    /// sits BETWEEN the two: over ours, under the framework's. Only the
    /// route's layer can refuse it — remove the layer and this payload is
    /// accepted, which is also what demonstrates the framework's default is
    /// the larger of the two.
    #[tokio::test]
    async fn opml_import_over_the_route_cap_is_refused_below_the_framework_default() {
        let state = test_state(&["did:plc:admin"]).await;
        let cookie = session_cookie(&state, "did:plc:admin", None);
        let app = router(state);

        // Between the two ceilings: the framework would accept this.
        let payload = vec![b'a'; (OPML_BODY_LIMIT + AXUM_DEFAULT_BODY_LIMIT) / 2];
        let (content_type, body) = opml_multipart(&payload);

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header("content-type", content_type)
                    .header(header::COOKIE, cookie)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            resp.status(),
            StatusCode::PAYLOAD_TOO_LARGE,
            "a payload over the route's cap but under the framework's was accepted — \
             the route's own DefaultBodyLimit layer is not doing anything"
        );
    }

    #[tokio::test]
    async fn opml_import_under_limit_upload_is_accepted() {
        let state = test_state(&["did:plc:admin"]).await;
        let cookie = session_cookie(&state, "did:plc:admin", None);
        let db = state.db.clone();
        let app = router(state);

        // A small, valid OPML well under the cap: must be accepted (the handler
        // redirects to `/` or a flash), i.e. never 413.
        let opml = br#"<?xml version="1.0"?>
<opml version="2.0"><body>
  <outline text="Example" type="rss" xmlUrl="https://example.com/feed.xml"/>
</body></opml>"#;
        let (content_type, body) = opml_multipart(opml);

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header("content-type", content_type)
                    .header(header::COOKIE, cookie)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        // **Assert it was ACCEPTED, not merely that it was not a 413.**
        //
        // The old assertion was `assert_ne!(status, PAYLOAD_TOO_LARGE)`, which a
        // 500 satisfies — so making `import_opml` fail unconditionally left this
        // green. Three other OPML tests caught that mutation; the one whose name
        // promises to cover the under-cap case did not.
        assert_eq!(
            resp.status(),
            StatusCode::SEE_OTHER,
            "an under-cap OPML upload was not accepted (status {})",
            resp.status(),
        );
        // **303 alone is not acceptance.** `import_opml` redirects on several
        // FAILURES too — unparseable OPML, zero feeds found, every feed trimmed
        // by a cap — so an import that stored nothing satisfied the status check.
        let stored: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM feeds WHERE url = ?1")
            .bind("https://example.com/feed.xml")
            .fetch_one(&db)
            .await
            .unwrap();
        assert_eq!(stored, 1, "the upload was redirected but imported nothing");
        let location = resp
            .headers()
            .get(header::LOCATION)
            .and_then(|v| v.to_str().ok())
            .unwrap_or_default()
            .to_string();
        assert!(
            !location.starts_with("/login"),
            "the import bounced to login instead of being accepted: {location}",
        );
    }

    #[tokio::test]
    async fn opml_import_logged_out_redirects_to_login() {
        // Logged-out callers are redirected before the body is consumed; assert
        // the auth short-circuit rather than a body-cap rejection.
        let state = test_state(&["did:plc:admin"]).await;
        let app = router(state);

        let opml = b"<opml version=\"2.0\"><body></body></opml>";
        let (content_type, body) = opml_multipart(opml);

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header("content-type", content_type)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert_eq!(resp.headers().get(header::LOCATION).unwrap(), "/login");
    }

    // -- delete-my-data (POST /account/delete) --------------------------------

    /// A one-shot mock sidecar: binds a loopback port, answers exactly one
    /// `POST /internal/revoke` with `{ok:true,…}`, and reports (via the returned
    /// channel) the DID it was asked to revoke. Enough to prove the delete
    /// handler triggers the sidecar revoke without pulling in an HTTP-mock crate.
    async fn spawn_revoke_sidecar() -> (String, tokio::sync::oneshot::Receiver<String>) {
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let (tx, rx) = tokio::sync::oneshot::channel::<String>();
        tokio::spawn(async move {
            let (mut sock, _) = listener.accept().await.unwrap();
            let mut buf = vec![0u8; 4096];
            let n = sock.read(&mut buf).await.unwrap();
            let req = String::from_utf8_lossy(&buf[..n]).to_string();
            // Pull the DID out of the JSON body (last line of the request).
            let did = req
                .split("\r\n\r\n")
                .nth(1)
                .and_then(|body| {
                    let v: serde_json::Value = serde_json::from_str(body.trim()).ok()?;
                    v.get("did")?.as_str().map(str::to_string)
                })
                .unwrap_or_default();
            let is_revoke = req.starts_with("POST /internal/revoke");
            let body = serde_json::json!({
                "ok": true, "did": did, "revoked": true, "hadSession": true
            })
            .to_string();
            let resp = format!(
                "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
                body.len(),
                body
            );
            sock.write_all(resp.as_bytes()).await.unwrap();
            sock.flush().await.unwrap();
            let _ = tx.send(if is_revoke { did } else { String::new() });
        });
        (format!("http://{addr}"), rx)
    }

    /// Build an [`AppState`] whose sidecar points at `sidecar_url`.
    async fn test_state_with_sidecar(allowed: &[&str], sidecar_url: &str) -> AppState {
        let defaults = Config::default();
        test_state_with_sidecar_and(
            allowed,
            sidecar_url,
            defaults.standard_site,
            defaults.max_feeds_global,
        )
        .await
    }

    /// [`test_state_with_sidecar`] with the standard.site flag and the global
    /// feeds ceiling chosen — the two settings the at:// paths branch on.
    async fn test_state_with_sidecar_and(
        allowed: &[&str],
        sidecar_url: &str,
        standard_site: bool,
        max_feeds_global: i64,
    ) -> AppState {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        let dids: Vec<String> = allowed.iter().map(|s| s.to_string()).collect();
        store::ensure_seed(&db, &dids).await.unwrap();
        let mut config = Config {
            allowed_dids: dids,
            cookie_secret: "test-cookie-secret-000".to_string(),
            beta_cap: 3,
            standard_site,
            max_feeds_global,
            ..Config::default()
        };
        config.sidecar.public_url = sidecar_url.to_string();
        config.sidecar.internal_url = sidecar_url.to_string();
        AppState::new(config, db).unwrap()
    }

    /// A confirmed `POST /account/delete` purges the caller's local rows, calls
    /// the sidecar revoke for that DID, and clears the session cookie.
    #[tokio::test]
    async fn account_delete_purges_rows_and_triggers_revoke() {
        let (sidecar_url, revoke_rx) = spawn_revoke_sidecar().await;
        let did = "did:plc:leaver";
        let state = test_state_with_sidecar(&[], &sidecar_url).await;

        // Seed the DID with local rows across the per-DID tables.
        store::grant_access(&state.db, did, Some("leaver.example"), "test", None)
            .await
            .unwrap();
        store::replace_sub_refs(&state.db, did, &[]).await.unwrap();
        store::mint_code(&state.db, did, 3600).await.unwrap();
        assert!(store::has_beta_access(&state.db, did).await.unwrap());

        let cookie = session_cookie(&state, did, Some("leaver.example"));
        let app = router(state.clone());

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/account/delete")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("confirm=DELETE"))
                    .unwrap(),
            )
            .await
            .unwrap();

        // Signed out: redirect to /login with the cookie cleared.
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert!(resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap()
            .starts_with("/login"));
        let set_cookie = resp
            .headers()
            .get(header::SET_COOKIE)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(set_cookie.contains("Max-Age=0"), "cookie must be cleared");

        // The sidecar revoke was called for exactly this DID.
        //
        // BOUNDED. A bare `await` here meant a broken `revoke_everywhere` — one
        // that simply never called the sidecar — hung this test forever instead
        // of failing it: a wedged CI job rather than a red one, which is the
        // worse of the two signals because nobody reads it as a defect.
        let revoked_did = tokio::time::timeout(std::time::Duration::from_secs(10), revoke_rx)
            .await
            .expect("the sidecar revoke never fired; revoke_everywhere did not call it")
            .unwrap();
        assert_eq!(
            revoked_did, did,
            "sidecar revoke must fire for the caller DID"
        );

        // Local rows are gone.
        assert!(!store::has_beta_access(&state.db, did).await.unwrap());
        let codes: i64 =
            sqlx::query_scalar("SELECT COUNT(*) FROM invite_codes WHERE creator_did = ?1")
                .bind(did)
                .fetch_one(&state.db)
                .await
                .unwrap();
        assert_eq!(codes, 0);
    }

    /// An UN-confirmed `POST /account/delete` (wrong/blank `confirm`) deletes
    /// nothing and bounces back to /manage.
    #[tokio::test]
    async fn account_delete_without_confirm_is_a_noop() {
        let did = "did:plc:staying";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did, None, "test", None)
            .await
            .unwrap();
        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/account/delete")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("confirm=nope"))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert!(resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap()
            .starts_with("/manage"));
        // Nothing deleted.
        assert!(store::has_beta_access(&state.db, did).await.unwrap());
    }

    /// PDS-outage authorization: when the sidecar is unreachable (as it is in
    /// this harness — the default sidecar URL is not served), a DID must STILL
    /// be unable to read or mutate an entry in a feed it does not subscribe to.
    /// This guards the `resolve_subscriptions` fallback: it must fail CLOSED
    /// (serve only the DID's own `sub_ref`), never widen the caller's surface to
    /// every cached feed.
    #[tokio::test]
    async fn pds_outage_does_not_widen_cross_did_access() {
        let did_a = "did:plc:aaaa";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did_a, None, "test", None)
            .await
            .unwrap();

        // Shared cache: feed_a (A subscribes) + feed_b (A does NOT). An entry
        // lives in feed_b — the one A must never touch during the outage.
        let feed_a = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://a.example/feed.xml".to_string(),
                title: Some("A".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let feed_b = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://b.example/feed.xml".to_string(),
                title: Some("B".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::insert_entries(
            &state.db,
            feed_b,
            &[store::NewEntry {
                guid: "b-1".to_string(),
                url: Some("https://b.example/1".to_string()),
                title: Some("B one".to_string()),
                published: Some("2026-07-11T00:00:00Z".to_string()),
                content_html: Some("<p>secret B body</p>".to_string()),
                ..Default::default()
            }],
            0,
        )
        .await
        .unwrap();
        // A subscribes ONLY to feed_a.
        store::replace_sub_refs(&state.db, did_a, &[feed_a])
            .await
            .unwrap();
        // Read B's entry id via a transient sub_ref, then drop it so only the
        // shared cache holds B's entry (no DID subscribes to feed_b anymore).
        store::replace_sub_refs(&state.db, "did:plc:bbbb", &[feed_b])
            .await
            .unwrap();
        let b_entry_id = store::entries_for_feed(&state.db, "did:plc:bbbb", feed_b)
            .await
            .unwrap()[0]
            .id;
        store::replace_sub_refs(&state.db, "did:plc:bbbb", &[])
            .await
            .unwrap();

        let cookie = session_cookie(&state, did_a, None);
        let app = router(state.clone());

        // GET /entries/{b} as A → 404 even during the outage.
        let get_b = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("GET")
                    .uri(format!("/entries/{b_entry_id}"))
                    .header(header::COOKIE, cookie.clone())
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            get_b.status(),
            StatusCode::NOT_FOUND,
            "A must not read B's entry during a PDS outage"
        );

        // POST /entries/{b}/read as A → 404, and no entry_state row is written.
        let read_b = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!("/entries/{b_entry_id}/read"))
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("read=true"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            read_b.status(),
            StatusCode::NOT_FOUND,
            "A must not mark B's entry read during a PDS outage"
        );

        // The fallback must NOT have widened A's sub_ref to feed_b.
        let a_feed_ids: Vec<i64> = sqlx::query_scalar("SELECT feed_id FROM sub_ref WHERE did = ?1")
            .bind(did_a)
            .fetch_all(&state.db)
            .await
            .unwrap();
        assert_eq!(
            a_feed_ids,
            vec![feed_a],
            "outage fallback must not add feeds A never subscribed to"
        );
        // And B's entry has zero read-state (A's attempt did not mutate).
        let es_count: i64 =
            sqlx::query_scalar("SELECT COUNT(*) FROM entry_state WHERE did = ?1 AND entry_id = ?2")
                .bind(did_a)
                .bind(b_entry_id)
                .fetch_one(&state.db)
                .await
                .unwrap();
        assert_eq!(es_count, 0, "no cross-DID mutation during the outage");
    }

    /// **A logout with nothing to revoke is a SUCCESS — on the arm that had
    /// nothing. The other arm is counted separately.**
    ///
    /// Logout is idempotent, so `NoSession` must record as ok; counting it as an
    /// error would make the metric noisy in exactly the case that is fine.
    ///
    /// But `revoke_everywhere` has TWO arms, and a review found that counting
    /// only the rust one let `oauth_revoke` report all-clear while every sidecar
    /// revocation failed. For anyone who logged in before the cutover the sidecar
    /// store is the only one holding tokens, so the rust arm correctly says
    /// NoSession and the metric said nothing was wrong. Both arms are now
    /// recorded, distinguished by the backend column — so this test pins the
    /// BACKEND as well as the outcome.
    #[tokio::test]
    async fn a_logout_with_no_session_counts_as_success() {
        let did = "did:plc:aaaa";
        let state = test_state(&[]).await;
        assert!(
            state.oauth.is_some(),
            "meaningless without an oauth runtime; the revoke arm would be skipped",
        );

        revoke_everywhere(&state, did).await;
        let rows = state.metrics.snapshot();
        let find = |b: crate::metrics::Backend| {
            rows.iter()
                .find(|r| r.op == "oauth_revoke" && r.backend == b)
                .unwrap_or_else(|| panic!("no oauth_revoke row for {b:?}"))
        };

        // Rust arm: nothing stored for this DID, so NoSession -> ok.
        let rust = find(crate::metrics::Backend::Rust);
        assert_eq!(
            rust.stats.err_count, 0,
            "NoSession was counted as a failure; logout is idempotent",
        );
        assert_eq!(rust.stats.ok_count, 1);

        // Sidecar arm: unreachable in a test, so it must be recorded as an
        // ERROR under its own backend — not silently dropped, and not folded
        // into the rust row.
        let sidecar = find(crate::metrics::Backend::Sidecar);
        assert_eq!(
            sidecar.stats.err_count, 1,
            "a failed sidecar revoke was not counted",
        );
    }

    /// **`Failed` must count as an error — the half the metric exists for.**
    ///
    /// A review found this unpinned: replacing the mapping with
    /// `let revoke_ok = true;` passed all 682 tests. The only revoke test
    /// asserted the `NoSession -> ok` half, so the branch that actually means
    /// "the PDS still holds tokens we asked it to drop" was untested.
    ///
    /// Driven through the same handler, with a session present but the PDS
    /// unreachable, so `sign_out_discovering` returns `Failed`.
    #[tokio::test]
    async fn a_failed_rust_revoke_counts_as_an_error() {
        let did = "did:plc:ewvi7nxzyoun6zhxrhs64oiz";
        let state = test_state(&[]).await;
        let runtime = state.oauth.as_deref().expect("oauth runtime");
        crate::oauth::store::put_session(
            &state.db,
            &runtime.codec,
            &crate::oauth::store::OAuthSession {
                sub: did.into(),
                issuer: "https://auth.invalid".into(),
                aud: "https://pds.invalid".into(),
                dpop_key_jwk: crate::oauth::keys::SigningKey::generate("session-dpop")
                    .to_jwk_json()
                    .unwrap(),
                access_token: "at".into(),
                refresh_token: "rt".into(),
                token_type: "DPoP".into(),
                granted_scope: "atproto".into(),
                expires_at: Some(crate::store::now_unix() + 3600),
            },
        )
        .await
        .unwrap();

        revoke_everywhere(&state, did).await;

        let rows = state.metrics.snapshot();
        let rust = rows
            .iter()
            .find(|r| r.op == "oauth_revoke" && r.backend == crate::metrics::Backend::Rust)
            .expect("no rust oauth_revoke row");
        assert_eq!(
            rust.stats.err_count, 1,
            "an unreachable PDS must count as a revocation failure",
        );
        assert_eq!(rust.stats.ok_count, 0);
    }

    /// **The `href` defence is now carried by the TYPE, not by remembering.**
    ///
    /// `EntryRow.link` used to be a `String`, and the guard was "call
    /// `net::safe_link` before assigning it". Deleting that call left all 679
    /// tests passing — a live XSS defence with nothing protecting it.
    ///
    /// `SafeLink` has no `From<String>` and no public member, so the only way to
    /// get foreign input into an `href` is `external`, which does the check
    /// itself. This test pins that constructor; the *wiring* is now pinned by
    /// the compiler, which is the part a test could never hold down.
    ///
    /// Note the empty-not-absent behaviour: a rejected URL yields an EMPTY link
    /// so the template renders the row WITHOUT an anchor. Dropping the row
    /// instead would make the record unremovable, because the un-save button
    /// lives on it.
    #[test]
    fn a_hostile_scheme_cannot_reach_an_href_through_safelink() {
        for hostile in [
            "javascript:alert(1)",
            "JavaScript:alert(1)",
            "  javascript:alert(1)",
            "data:text/html;base64,PHNjcmlwdD4=",
            "vbscript:msgbox(1)",
            "file:///etc/passwd",
            // Protocol-relative: inherits the page's scheme, so it is an
            // off-site link wearing a same-site costume. Carried over from the
            // test this one replaces, which was its only unique input.
            "//evil.example/path",
        ] {
            let link = SafeLink::external(hostile);
            assert!(
                link.is_empty(),
                "{hostile:?} produced a non-empty href: {link}",
            );
            assert!(
                !link.to_string().to_ascii_lowercase().contains("script"),
                "{hostile:?} leaked into the rendered link",
            );
        }

        // And the other direction: a check that rejects everything would satisfy
        // the loop above while breaking every real saved record.
        for good in ["https://example.com/a?b=c#d", "http://example.com/"] {
            let link = SafeLink::external(good);
            assert!(!link.is_empty(), "{good:?} was wrongly rejected");
            assert_eq!(link.to_string(), good);
        }
    }

    /// **The WIRING, not the helper — this is the one that catches the real
    /// mistake.**
    ///
    /// `a_hostile_scheme_cannot_reach_an_href_through_safelink` pins what
    /// `SafeLink::external` *does*. It cannot pin that the saved-record path
    /// *calls* it, and a review proved that gap was live twice over: swapping
    /// `external` for the app-path constructor, and constructing the tuple
    /// directly, both restored the whole `javascript:` hole with every test
    /// green. The type now blocks both — `entry` takes an `i64`, and the field
    /// lives in another module — but the wiring deserves a test of its own
    /// rather than resting on the shape of a signature.
    ///
    /// Renders the actual row through the actual handler, from a record whose
    /// URL is hostile.
    #[tokio::test]
    async fn a_saved_record_with_a_hostile_url_renders_no_anchor() {
        let did = "did:plc:ewvi7nxzyoun6zhxrhs64oiz";
        let sidecar = spawn_saved_sidecar("javascript:alert(1)", "Hostile record").await;
        let mut state = test_state_with_sidecar(&[did], &sidecar).await;
        std::sync::Arc::get_mut(&mut state.config).unwrap().dev_did = Some(did.to_string());

        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri("/?view=starred")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();

        // Not in an href, and not as the title either — the title falls back to
        // the URL for links we DO render, so both paths must withhold it.
        assert!(
            !body.to_ascii_lowercase().contains("javascript:"),
            "the hostile scheme reached the rendered page",
        );
        // But the row must survive: the un-save button lives on it, so dropping
        // the row would make the record unremovable from here.
        assert!(
            body.contains("unusable link"),
            "the row was dropped instead of rendering without an anchor",
        );
    }

    /// **The reader view's two `href`s, through the actual handler.**
    ///
    /// The sibling above covers the LIST row. `entry.html` has its own pair of
    /// `href`s fed by `EntryTemplate.url`, and they were a raw `Option<String>`
    /// taken straight off the `entries.url` column — a remote feed's `<link>`.
    ///
    /// Ingest already scheme-checks that column (`feed.rs`'s `entry_link`), so
    /// this was never a live hole. But that guard is procedural and sits a long
    /// way from the `href`: it holds only as long as every future writer to
    /// `entries.url` remembers to go through `feed.rs`. This test does not
    /// depend on it — it writes the hostile URL into the column DIRECTLY, which
    /// is precisely the state the ingest check cannot speak for.
    ///
    /// **Both directions, deliberately.** A fix that renders no link at all
    /// satisfies every negative assertion here, and would break every real
    /// entry. The second half is what makes the first half mean something.
    #[tokio::test]
    async fn a_hostile_entry_url_renders_the_reader_without_an_original_link() {
        let did = "did:plc:readerhref";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did, None, "test", None)
            .await
            .unwrap();
        let feed = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://href.example/feed.xml".to_string(),
                title: Some("Href".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        // Straight into the column, bypassing `feed.rs` — the whole point.
        store::insert_entries(
            &state.db,
            feed,
            &[
                store::NewEntry {
                    guid: "hostile-1".to_string(),
                    url: Some("javascript:alert(1)".to_string()),
                    title: Some("Hostile entry".to_string()),
                    published: Some("2026-07-11T00:00:00Z".to_string()),
                    ..Default::default()
                },
                store::NewEntry {
                    guid: "benign-1".to_string(),
                    url: Some("https://href.example/post".to_string()),
                    title: Some("Benign entry".to_string()),
                    published: Some("2026-07-10T00:00:00Z".to_string()),
                    ..Default::default()
                },
            ],
            0,
        )
        .await
        .unwrap();
        store::replace_sub_refs(&state.db, did, &[feed])
            .await
            .unwrap();
        let rows = store::entries_for_feed(&state.db, did, feed).await.unwrap();
        let id_of = |guid: &str| {
            rows.iter()
                .find(|r| r.guid == guid)
                .unwrap_or_else(|| panic!("{guid} was not inserted"))
                .id
        };

        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());

        let render = |id: i64| {
            let app = app.clone();
            let cookie = cookie.clone();
            async move {
                let resp = app
                    .oneshot(
                        Request::builder()
                            .method("GET")
                            .uri(format!("/entries/{id}"))
                            .header(header::COOKIE, cookie)
                            .body(Body::empty())
                            .unwrap(),
                    )
                    .await
                    .unwrap();
                assert_eq!(resp.status(), StatusCode::OK);
                String::from_utf8(
                    axum::body::to_bytes(resp.into_body(), usize::MAX)
                        .await
                        .unwrap()
                        .to_vec(),
                )
                .unwrap()
            }
        };

        let hostile = render(id_of("hostile-1")).await;
        // The reader page for THIS entry actually rendered. Without this the
        // three negatives below are satisfied by an empty body.
        assert!(
            hostile.contains("Hostile entry"),
            "the reader did not render the entry: {hostile}",
        );
        assert!(
            !hostile.to_ascii_lowercase().contains("javascript:"),
            "the hostile scheme reached the reader page: {hostile}",
        );
        // Not merely escaped — the template took its no-link branch. Both
        // `href`s are gated on the same `Option`, so this covers the byline
        // link and the action-bar button together.
        assert!(
            !hostile.contains("actionbar-open"),
            "the action bar rendered an open-original link for a refused URL: {hostile}",
        );
        assert!(
            !hostile.contains("Original \u{2197}"),
            "the byline rendered an original link for a refused URL: {hostile}",
        );

        // The other direction: a legitimate entry still links out, so "render
        // nothing" cannot pass as a fix.
        let benign = render(id_of("benign-1")).await;
        assert!(
            benign.contains("Benign entry"),
            "the reader did not render the benign entry: {benign}",
        );
        // BOTH `href`s, counted. The negatives above fire on the action bar
        // first, so without this the byline needle `Original \u{2197}` is never
        // once observed failing — a misspelled needle would pass forever.
        assert_eq!(
            benign
                .matches(r#"href="https://href.example/post""#)
                .count(),
            2,
            "entry.html has two `href`s for the entry URL — the byline link and \
             the action-bar button — and this render produced a different \
             number: {benign}",
        );
        assert!(
            benign.contains("actionbar-open"),
            "a legitimate entry lost its open-original button: {benign}",
        );
        assert!(
            benign.contains("Original \u{2197}"),
            "a legitimate entry lost its byline link: {benign}",
        );
    }

    /// **The outage fallback must not widen what the caller can READ — and the
    /// sibling test above can only see what it WRITES.**
    ///
    /// `pds_outage_does_not_widen_cross_did_access` asserts on `sub_ref` rows and
    /// on `entry_state`: the fallback's side effects. But the fail-open it names
    /// returns **early**, before `sync_sub_refs` runs, so it touches neither. It
    /// leaks through the list it *hands back* — the sidebar and the reader render
    /// from that list, so a caller sees another DID's feeds while `sub_ref` stays
    /// perfectly honest and every existing assertion stays green.
    ///
    /// Measured, not assumed: replacing `feeds_for_did(pool, did)` with
    /// `due_feeds(pool, "9999-…", 10_000)` over the whole shared cache — the
    /// exact historical bug the fallback's comment describes — left **all 663
    /// tests passing**. Cross-tenant isolation is the one property this project
    /// cannot regress quietly, and nothing observed it.
    ///
    /// So this asserts on the RETURN VALUE, which is the thing that reaches the
    /// user, and it deliberately does not look at `sub_ref` at all — that half is
    /// already covered above.
    #[tokio::test]
    async fn the_outage_fallback_returns_only_the_callers_own_feeds() {
        let did_a = "did:plc:aaaa";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did_a, None, "test", None)
            .await
            .unwrap();

        let feed_a = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://a.example/feed.xml".to_string(),
                title: Some("A".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let _feed_b = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://b.example/feed.xml".to_string(),
                title: Some("B".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        // A subscribes ONLY to feed_a. feed_b is in the shared cache and belongs
        // to nobody — exactly the row a whole-cache fallback would hand to A.
        store::replace_sub_refs(&state.db, did_a, &[feed_a])
            .await
            .unwrap();

        // No sidecar and no PDS are reachable from a test, so
        // `list_subscriptions_sorted` fails and this IS the outage path. Assert
        // that, rather than assuming it: if the repo ever starts succeeding here,
        // this test would silently stop exercising the fallback at all.
        assert!(
            state.repo().list_subscriptions_sorted(did_a).await.is_err(),
            "this test is only meaningful on the outage path; the repo answered",
        );

        let resolved = resolve_subscriptions(&state, did_a).await;

        let urls: Vec<&str> = resolved.iter().map(|r| r.sub.url.as_str()).collect();
        assert_eq!(
            urls,
            vec!["https://a.example/feed.xml"],
            "the outage fallback must return the caller's OWN subscriptions only; \
             any other feed here is cross-tenant read access granted by an outage",
        );
    }

    /// Build an [`AppState`] over a fresh in-memory DB with explicit feed caps,
    /// seeding `did` a beta seat + session-capable state.
    async fn test_state_with_caps(
        did: &str,
        max_subs_per_did: i64,
        max_feeds_global: i64,
    ) -> AppState {
        let db = store::init_url("sqlite::memory:").await.unwrap();
        let config = Config {
            cookie_secret: "test-cookie-secret-000".to_string(),
            beta_cap: 100,
            max_subs_per_did,
            max_feeds_global,
            ..Config::default()
        };
        store::grant_access(&db, did, None, "test", None)
            .await
            .unwrap();
        AppState::new(config, db).unwrap()
    }

    /// An OPML document with `n` distinct public feeds.
    fn opml_with_feeds(n: usize) -> String {
        let mut outlines = String::new();
        for i in 0..n {
            outlines.push_str(&format!(
                "<outline type=\"rss\" text=\"F{i}\" xmlUrl=\"https://f{i}.example/feed.xml\"/>\n"
            ));
        }
        format!(
            "<?xml version=\"1.0\"?>\n<opml version=\"2.0\"><head><title>t</title></head><body>\n{outlines}</body></opml>"
        )
    }

    /// OPML bulk import must honour the GLOBAL feeds ceiling: importing more
    /// distinct new feeds than the shared cache can hold caches only up to the
    /// ceiling — the rest are trimmed. (Regression: the import loop previously
    /// bypassed `max_feeds_global` entirely.)
    #[tokio::test]
    async fn opml_import_enforces_global_feeds_ceiling() {
        let did = "did:plc:importer";
        // Cap the shared cache at 3 feeds; import 10 distinct new ones.
        let state = test_state_with_caps(did, 0, 3).await;
        let cookie = session_cookie(&state, did, None);
        let (ct, body) = opml_multipart(opml_with_feeds(10).as_bytes());
        let app = router(state.clone());

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header(header::COOKIE, cookie)
                    .header("content-type", ct)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);

        let feeds = store::count_feeds(&state.db).await.unwrap();
        assert!(
            feeds <= 3,
            "OPML import blew past the global ceiling: {feeds} feeds cached with cap=3"
        );
    }

    /// **A malformed `at://` on the add path is "not a kind of feed we take",
    /// not "private/paid".** The first gate was the privacy classifier, whose
    /// at:// arm fails closed as `Private` for anything not a well-formed
    /// publication URI — so a typo (`did:plc:TOOSHORT`, a missing rkey) drew
    /// the private-feed flash and a "refused private/paid feed" log line. On
    /// main the same input reached `resolve_feed_url` and got "Couldn't find a
    /// feed". Storability is decided first for an at:// input, with its own
    /// message.
    #[tokio::test]
    async fn a_malformed_at_uri_on_the_add_path_is_refused_as_unsupported_not_private() {
        let did = "did:plc:typoist";
        let state = test_state_with_caps(did, 0, 0).await;
        let cookie = session_cookie(&state, did, None);
        for input in [
            "at%3A%2F%2Falice.example.com%2Fsite.standard.publication",
            "at%3A%2F%2Fdid%3Aplc%3ATOOSHORT%2Fsite.standard.publication%2F3lab2c4d5e6f7g8h",
        ] {
            let resp = router(state.clone())
                .oneshot(
                    Request::builder()
                        .method("POST")
                        .uri("/subscriptions")
                        .header(header::COOKIE, cookie.clone())
                        .header("content-type", "application/x-www-form-urlencoded")
                        .body(Body::from(format!("url={input}")))
                        .unwrap(),
                )
                .await
                .unwrap();
            assert_eq!(resp.status(), StatusCode::SEE_OTHER);
            let loc = resp
                .headers()
                .get(header::LOCATION)
                .unwrap()
                .to_str()
                .unwrap();
            assert!(
                loc.contains("kind%20of%20feed"),
                "expected the unsupported-feed flash for {input}, got {loc}"
            );
            assert!(
                !loc.contains("Private"),
                "a storability refusal was reported as a privacy one for {input}: {loc}"
            );
        }
        assert_eq!(store::count_feeds(&state.db).await.unwrap(), 0);
    }

    /// **An OPML entry this instance cannot store is counted and reported, not
    /// silently dropped.** The storability `continue` incremented nothing,
    /// while the privacy branch beside it produced a user-visible label — so
    /// an OPML exported from a standard.site-enabled instance imported
    /// "successfully" with entries missing and no reason given. The reader is
    /// told how many, and why.
    #[tokio::test]
    async fn opml_import_reports_entries_this_instance_cannot_store() {
        let did = "did:plc:renamer4";
        let (sidecar, _puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        assert!(!state.config.standard_site);
        let opml = format!(
            "<?xml version=\"1.0\"?>\n<opml version=\"2.0\"><head><title>t</title></head><body>\n\
             <outline type=\"rss\" text=\"Real\" xmlUrl=\"https://real.example/feed.xml\"/>\n\
             <outline type=\"rss\" text=\"Pub\" xmlUrl=\"{AT_URI_SUB}\"/>\n\
             </body></opml>"
        );
        let (ct, body) = opml_multipart(opml.as_bytes());
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header(header::COOKIE, cookie)
                    .header("content-type", ct)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("Imported%201%20feed"),
            "unexpected flash: {loc}"
        );
        assert!(
            loc.contains("1%20feed%28s%29%20skipped") && loc.contains("can%20subscribe%20to"),
            "the dropped entry was not reported: {loc}"
        );
        // Reported by count only: the at-URI itself is not echoed back.
        assert!(
            !loc.contains("site.standard.publication"),
            "the URI was echoed: {loc}"
        );
    }

    /// OPML bulk import must honour the PER-DID subscription cap: a DID at its
    /// cap imports zero new feeds.
    #[tokio::test]
    async fn opml_import_enforces_per_did_cap() {
        let did = "did:plc:capped";
        // Per-DID cap 2, global unlimited. Pre-seed the DID at its cap.
        let state = test_state_with_caps(did, 2, 0).await;
        let existing_a = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://have-a.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let existing_b = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://have-b.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::replace_sub_refs(&state.db, did, &[existing_a, existing_b])
            .await
            .unwrap();
        let before = store::count_feeds(&state.db).await.unwrap();

        let cookie = session_cookie(&state, did, None);
        let (ct, body) = opml_multipart(opml_with_feeds(10).as_bytes());
        let app = router(state.clone());
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header(header::COOKIE, cookie)
                    .header("content-type", ct)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        // Headroom was 0 → no new feeds imported into the shared cache.
        let after = store::count_feeds(&state.db).await.unwrap();
        assert_eq!(after, before, "over-cap DID imported new feeds anyway");
    }

    /// Single-add per-DID cap: a DID at its subscription cap is refused before
    /// any fetch, with the limit flash.
    #[tokio::test]
    async fn single_add_enforces_per_did_cap() {
        let did = "did:plc:subcapped";
        let state = test_state_with_caps(did, 1, 0).await;
        let f = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://have.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::replace_sub_refs(&state.db, did, &[f]).await.unwrap();
        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("url=https://another.example/feed.xml"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("Subscription%20limit%20reached"),
            "expected sub-limit flash, got {loc}"
        );
    }

    /// `GET /` renders at most one page of rows and offers a way to the rest.
    ///
    /// The handler used to materialize EVERY unread entry — `SELECT e.*`, no
    /// `LIMIT`, article bodies included — and hand the lot to the template. With
    /// 250 entries that is the whole list in one response; with a real backlog on
    /// a 512 MB box it is the OOM the operator review flagged. Asserts the page
    /// is capped, the heading still reports the true total, and page 2 is
    /// reachable and disjoint.
    #[tokio::test]
    async fn the_reader_index_pages_instead_of_rendering_everything() {
        let did = "did:plc:pager";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did, None, "test", None)
            .await
            .unwrap();
        let feed = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://pager.example/feed.xml".to_string(),
                title: Some("Pager".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let total = 250_usize;
        let entries: Vec<store::NewEntry> = (0..total)
            .map(|i| store::NewEntry {
                guid: format!("p-{i:04}"),
                url: Some(format!("https://pager.example/{i}")),
                title: Some(format!("Article {i:04}")),
                published: Some(format!("2026-07-{:02}T00:00:00Z", (i % 28) + 1)),
                content_html: Some("x".repeat(4_000)),
                ..Default::default()
            })
            .collect();
        store::insert_entries(&state.db, feed, &entries, 0)
            .await
            .unwrap();
        store::replace_sub_refs(&state.db, did, &[feed])
            .await
            .unwrap();

        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());
        let get = |uri: &str| {
            let app = app.clone();
            let cookie = cookie.clone();
            let uri = uri.to_string();
            async move {
                let resp = app
                    .oneshot(
                        Request::builder()
                            .uri(uri)
                            .header(header::COOKIE, cookie)
                            .body(Body::empty())
                            .unwrap(),
                    )
                    .await
                    .unwrap();
                assert_eq!(resp.status(), StatusCode::OK);
                let bytes = axum::body::to_bytes(resp.into_body(), 8 * 1024 * 1024)
                    .await
                    .unwrap();
                String::from_utf8(bytes.to_vec()).unwrap()
            }
        };

        let page1 = get("/").await;
        // One `<li class="entry…>` per rendered row. Counting "/entries/" would
        // over-count: each row carries several (the link plus the read/star
        // forms).
        let rows1 = page1.matches("<li class=\"entry").count();
        assert!(
            rows1 <= ENTRIES_PER_PAGE as usize,
            "page 1 rendered {rows1} entry links; the list is unbounded"
        );
        assert!(
            rows1 > 0,
            "page 1 rendered nothing at all: the page bound swallowed the list"
        );
        // The count is the TRUE total, not the page size — otherwise paging
        // would quietly relabel a 250-entry backlog as a 100-entry one.
        assert!(
            page1.contains("250 entries"),
            "heading must report the full total, not the page"
        );
        assert!(
            page1.contains("page=2"),
            "no way to reach the rest of the list: {}",
            &page1[..page1.len().min(400)]
        );
        // The body never belongs in a list response.
        assert!(
            !page1.contains(&"x".repeat(4_000)),
            "the list response carried an article body"
        );

        let page2 = get("/?page=2").await;
        assert!(
            page2.matches("<li class=\"entry").count() > 0,
            "page 2 rendered no rows at all"
        );
        assert!(
            page2.contains("page=1") || page2.contains("Newer"),
            "page 2 offers no way back"
        );
        // Disjoint: an article on page 1 must not reappear on page 2.
        let first_title = (0..total)
            .map(|i| format!("Article {i:04}"))
            .find(|t| page1.contains(t))
            .expect("page 1 shows at least one titled article");
        assert!(
            !page2.contains(&first_title),
            "{first_title} appears on both pages"
        );

        // A page past the end must not be a dead end. The empty state renders
        // instead of the pager, so an out-of-range page would leave a reader
        // with no link back — reachable by typing a number, and reachable
        // WITHOUT typing anything by paging to the end and then marking entries
        // read, which shrinks the list under the URL already in the address bar.
        let past_end = get("/?page=999").await;
        assert!(
            past_end.matches("<li class=\"entry").count() > 0,
            "an out-of-range page rendered nothing and offered no way back"
        );
        assert!(
            past_end.contains("page=2"),
            "the clamped page offers no pager"
        );
    }

    /// Reader-view mark-read (a request tagged `X-FR-Reader: 1`) must return the
    /// out-of-band action-bar fragment with FRESHLY re-read state so a second
    /// keypress reverses the toggle: `hx-swap-oob="outerHTML"` is present, and
    /// the hidden `read` input + `aria-pressed` reflect the NEW state. The list
    /// view (no reader header) instead swaps the row. This guards the reader OOB
    /// toggle wiring, which had no test.
    #[tokio::test]
    async fn reader_mark_read_returns_oob_actionbar_with_flipped_state() {
        let did = "did:plc:reader";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did, None, "test", None)
            .await
            .unwrap();
        let feed = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://reader.example/feed.xml".to_string(),
                title: Some("Reader".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::insert_entries(
            &state.db,
            feed,
            &[store::NewEntry {
                guid: "r-1".to_string(),
                url: Some("https://reader.example/1".to_string()),
                title: Some("Article".to_string()),
                published: Some("2026-07-11T00:00:00Z".to_string()),
                content_html: Some("<p>body</p>".to_string()),
                ..Default::default()
            }],
            0,
        )
        .await
        .unwrap();
        store::replace_sub_refs(&state.db, did, &[feed])
            .await
            .unwrap();
        let entry_id = store::entries_for_feed(&state.db, did, feed).await.unwrap()[0].id;

        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());

        // Reader-tagged mark-read → OOB action-bar fragment, entry now READ.
        let resp = app
            .clone()
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!("/entries/{entry_id}/read"))
                    .header(header::COOKIE, cookie.clone())
                    .header("HX-Request", "true")
                    .header("X-FR-Reader", "1")
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("read=true"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), 64 * 1024)
            .await
            .unwrap();
        let html = String::from_utf8(bytes.to_vec()).unwrap();
        assert!(
            html.contains("hx-swap-oob=\"outerHTML\""),
            "reader response must be an OOB swap: {html}"
        );
        assert!(
            html.contains(r#"id="entry-actionbar""#),
            "reader response must be the action-bar fragment: {html}"
        );
        // Now READ: the read button reflects it (aria-pressed=true) and the
        // hidden value flips to `false` so the next tap marks it UNREAD.
        assert!(
            html.contains(r#"aria-pressed="true""#),
            "read button must show pressed after marking read: {html}"
        );
        assert!(
            html.contains(r#"name="read" value="false""#),
            "hidden read value must flip to false so a second tap reverses: {html}"
        );

        // A second reader mark-read (submitting the flipped `read=false`) marks
        // it UNREAD again — the toggle reverses.
        let resp2 = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!("/entries/{entry_id}/read"))
                    .header(header::COOKIE, cookie)
                    .header("HX-Request", "true")
                    .header("X-FR-Reader", "1")
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("read=false"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp2.status(), StatusCode::OK);
        let bytes2 = axum::body::to_bytes(resp2.into_body(), 64 * 1024)
            .await
            .unwrap();
        let html2 = String::from_utf8(bytes2.to_vec()).unwrap();
        assert!(
            html2.contains(r#"aria-pressed="false""#),
            "read button must show un-pressed after reversing: {html2}"
        );
        assert!(
            html2.contains(r#"name="read" value="true""#),
            "hidden read value must flip back to true: {html2}"
        );
    }

    /// The LIST view (no `X-FR-Reader` header) swaps the row, not the OOB
    /// action-bar — the counterpart to the reader-OOB test above.
    #[tokio::test]
    async fn list_mark_read_returns_row_not_oob_actionbar() {
        let did = "did:plc:listv";
        let state = test_state(&[]).await;
        store::grant_access(&state.db, did, None, "test", None)
            .await
            .unwrap();
        let feed = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://list.example/feed.xml".to_string(),
                title: Some("List".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::insert_entries(
            &state.db,
            feed,
            &[store::NewEntry {
                guid: "l-1".to_string(),
                url: Some("https://list.example/1".to_string()),
                title: Some("Article".to_string()),
                published: Some("2026-07-11T00:00:00Z".to_string()),
                ..Default::default()
            }],
            0,
        )
        .await
        .unwrap();
        store::replace_sub_refs(&state.db, did, &[feed])
            .await
            .unwrap();
        let entry_id = store::entries_for_feed(&state.db, did, feed).await.unwrap()[0].id;

        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());

        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri(format!("/entries/{entry_id}/read"))
                    .header(header::COOKIE, cookie)
                    .header("HX-Request", "true")
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from("read=true"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let bytes = axum::body::to_bytes(resp.into_body(), 64 * 1024)
            .await
            .unwrap();
        let html = String::from_utf8(bytes.to_vec()).unwrap();
        assert!(
            !html.contains("hx-swap-oob"),
            "list-view response must NOT be an OOB swap: {html}"
        );
        // **And it must actually BE the row.** The assertion above is satisfied
        // by an empty body, or by any response that simply omits the attribute —
        // so on its own it pins half a property and the name promises the other
        // half.
        assert!(
            html.contains(&format!("/entries/{entry_id}")),
            "the response is not the row for this entry: {html}",
        );
        assert!(
            html.contains("Article"),
            "the row rendered without its title: {html}",
        );
        // **The row comes back carrying read state. That is all this proves.**
        //
        // It does NOT prove the state was persisted: the handler renders
        // `Some(read)` from the form value, so making `mark_read` roll back
        // instead of commit fails 11 store tests and leaves this one green.
        //
        // It does not prove the OVERRIDE either, which an earlier version of
        // this comment claimed. Verified: changing the call site to
        // `build_entry_row(pool, &did, id, None)` — deleting the override
        // wholesale — keeps the whole suite green, because `mark_read` has
        // already persisted the same value two lines earlier, so reading it back
        // from the database produces an identical row.
        //
        // Distinguishing the two needs a case where the override and the stored
        // state DISAGREE, which this handler never produces: it writes the value
        // it then renders. Left as a known gap rather than described as covered.
        assert!(
            html.contains("is-read"),
            "the row came back without the read state it was just given: {html}",
        );
    }

    // -----------------------------------------------------------------------
    // Rename parity (POST /subscriptions/{rkey}/rename)
    // -----------------------------------------------------------------------

    /// **Autodiscovery cannot smuggle a non-http(s) URL into storage.**
    ///
    /// The add path gates the URL the user *typed*; the URL it *stores* is
    /// whatever `resolve_feed_url` returns, which for an HTML page is a
    /// publisher-controlled `<link rel="alternate">` href. Two layers stop
    /// that: `discover_feed` yields only http(s), and the add path re-checks
    /// storability on the resolved URL. This test pins the DISJUNCTION —
    /// each layer alone holds it, both removed fails it — driven through the
    /// real route against a real local server.
    ///
    /// **Why the fixture is `ftp://`, not `at://`.** This began as the
    /// at-URI bypass test from #164, and it was vacuous twice over. Handle
    /// form: once storage became DID-only the privacy classifier refused it
    /// at its own gate. DID form: `Url::parse` cannot read it (invalid port
    /// — the colons in the DID), so `discover_feed` drops it before either
    /// layer exists. An at:// link cannot come out of autodiscovery under
    /// ANY mutation of the layers, so no test through this route can pin
    /// them with one. `ftp://` reaches both. The at:// case is guaranteed by
    /// structure and pinned where it lives: `discover_skips_a_non_http_
    /// alternate` and the storability tests in `feed.rs`.
    #[tokio::test]
    async fn autodiscovery_cannot_smuggle_a_non_http_url_into_storage() {
        let did = "did:plc:autodiscovered";
        // Access granted, both caps disabled — the only gates left are the
        // two under test.
        let state = test_state_with_caps(did, 0, 0).await;

        let page = r#"<!doctype html><html><head><title>Blog</title>
            <link rel="alternate" type="application/rss+xml" href="ftp://files.example/feed.xml">
            </head><body>hi</body></html>"#;
        let base = crate::net::tests::serve_body(page.as_bytes().to_vec()).await;
        let port: u16 = base
            .trim_end_matches('/')
            .rsplit(':')
            .next()
            .unwrap()
            .parse()
            .unwrap();
        crate::net::test_host_override(
            "autodiscover-ftp.test",
            std::net::SocketAddr::from(([127, 0, 0, 1], port)),
        );

        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!(
                        "url=http://autodiscover-ftp.test:{port}/"
                    )))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert_ne!(loc, "/login", "the test never reached the add path");
        assert_ne!(loc, "/", "the subscribe succeeded");

        assert_eq!(
            store::count_feeds(&state.db).await.unwrap(),
            0,
            "a non-http(s) URL from autodiscovery was stored"
        );
        assert_eq!(
            store::count_subscriptions_for_did(&state.db, did)
                .await
                .unwrap(),
            0
        );
    }

    /// A rename that points at a BRAND-NEW feed URL while the shared cache is at
    /// its global ceiling must be refused (capacity flash) and must NOT insert a
    /// new `feeds` row — parity with add_subscription's global-cap guard, so a
    /// rename loop can't inflate the shared cache past the cap.
    #[tokio::test]
    async fn rename_to_new_url_refused_at_global_feeds_cap() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        // Global cap 1; pre-fill it with one feed so headroom is 0.
        let state = test_state_with_sidecar_and(&[did], &sidecar, false, 1).await;
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://existing.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let before = store::count_feeds(&state.db).await.unwrap();
        assert_eq!(before, 1);

        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    // A URL not in the cache → would be a NEW feeds row.
                    .body(Body::from(
                        "url=https://brand-new.example/feed.xml&title=Renamed",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("feed%20capacity"),
            "expected the feed-capacity flash, got {loc}"
        );
        // No new feeds row was inserted, and nothing reached the PDS.
        assert_eq!(store::count_feeds(&state.db).await.unwrap(), before);
        assert!(
            puts.lock().unwrap().is_empty(),
            "a refused repoint reached the PDS"
        );
    }

    /// A repoint to an EXISTING URL adds no row, so it is allowed even at the
    /// global cap (only new URLs are gated) — the other half of the guard.
    ///
    /// On the sidecar fake, so "allowed" means the put actually happened: the
    /// earlier harness had no sidecar, and this passed on a "could not reach
    /// your PDS" flash that merely was not the capacity one.
    #[tokio::test]
    async fn rename_to_existing_url_allowed_at_global_feeds_cap() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar_and(&[did], &sidecar, false, 1).await;
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://existing.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let before = store::count_feeds(&state.db).await.unwrap();

        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(
                        "url=https://existing.example/feed.xml&title=Retitled",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert_eq!(loc, "/", "the repoint to a cached URL was refused: {loc}");
        assert_eq!(
            puts.lock().unwrap().len(),
            1,
            "the repoint did not reach the PDS"
        );
        assert_eq!(store::count_feeds(&state.db).await.unwrap(), before);
    }

    /// A rename with a blank URL writes nothing anywhere.
    #[tokio::test]
    async fn rename_with_blank_url_writes_nothing() {
        let did = "did:plc:renamer3";
        let state = test_state_with_caps(did, 0, 0).await;
        let before = store::count_feeds(&state.db).await.unwrap();
        assert_eq!(before, 0);

        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());
        let resp = app
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rkey123/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    // Whitespace-only URL trims to empty.
                    .body(Body::from("url=%20%20&title=Nope"))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        assert_eq!(
            resp.headers()
                .get(header::LOCATION)
                .unwrap()
                .to_str()
                .unwrap(),
            "/",
        );
        // Nothing was cached.
        assert_eq!(
            store::count_feeds(&state.db).await.unwrap(),
            0,
            "blank-URL rename wrote a junk feeds row"
        );
    }

    /// A sidecar mock that serves ONE existing subscription record and captures
    /// every `put` body a rename produces.
    ///
    /// **Reads to `content-length` rather than taking one `read`.** A single
    /// read gets whatever one segment carried; if the head and body land
    /// separately the capture holds no record and every field assertion below
    /// passes for the wrong reason. Each captured body must also mention the
    /// collection, so an empty capture fails loudly instead of quietly.
    async fn spawn_rename_sidecar(
        existing: serde_json::Value,
    ) -> (String, std::sync::Arc<std::sync::Mutex<Vec<String>>>) {
        use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let puts = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
        let sink = puts.clone();
        tokio::spawn(async move {
            loop {
                let Ok((mut sock, _)) = listener.accept().await else {
                    break;
                };
                let mut raw: Vec<u8> = Vec::new();
                let mut chunk = [0u8; 4096];
                let body_text = loop {
                    let Ok(n) = sock.read(&mut chunk).await else {
                        break String::new();
                    };
                    if n == 0 {
                        break String::from_utf8_lossy(&raw).to_string();
                    }
                    raw.extend_from_slice(&chunk[..n]);
                    let Some(split) = raw.windows(4).position(|w| w == b"\r\n\r\n") else {
                        continue;
                    };
                    let (head, body) = raw.split_at(split + 4);
                    let want = String::from_utf8_lossy(head).lines().find_map(|l| {
                        let (k, v) = l.split_once(':')?;
                        k.eq_ignore_ascii_case("content-length")
                            .then(|| v.trim().parse::<usize>().ok())?
                    });
                    if want.is_none_or(|want| body.len() >= want) {
                        break String::from_utf8_lossy(body).to_string();
                    }
                };

                // `"action":"put"` is the rename write; anything else is the read.
                let is_put = body_text.contains("\"action\":\"put\"");
                let data = if is_put {
                    sink.lock().unwrap().push(body_text.clone());
                    serde_json::json!({
                        "uri": "at://did:plc:x/community.lexicon.rss.subscription/rk-keep",
                        "cid": "bafyreiafter"
                    })
                } else {
                    serde_json::json!({ "records": [existing.clone()] })
                };
                let body = serde_json::json!({ "ok": true, "data": data }).to_string();
                let resp = format!(
                    "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
                    body.len(),
                    body
                );
                let _ = sock.write_all(resp.as_bytes()).await;
                let _ = sock.flush().await;
            }
        });
        (format!("http://{addr}"), puts)
    }

    /// The existing record a rename must not destroy.
    fn seeded_subscription() -> serde_json::Value {
        serde_json::json!({
            "uri": "at://did:plc:renamer4/community.lexicon.rss.subscription/rk-keep",
            "cid": "bafyreibefore",
            "value": {
                "$type": "community.lexicon.rss.subscription",
                "url": "https://example.com/feed.xml",
                "title": "Old title",
                "siteUrl": "https://example.com/blog",
                "fetchHint": "hourly",
                "private": false,
                "createdAt": "2024-03-01T00:00:00.000Z"
            }
        })
    }

    /// An existing standard.site subscription, as the 19 in production are:
    /// written before this reader refused the scheme, still in the repo.
    fn seeded_at_uri_subscription() -> serde_json::Value {
        seeded_subscription_with_url(AT_URI_SUB)
    }
    /// An existing subscription record at `rk-keep` with the given URL.
    fn seeded_subscription_with_url(url: &str) -> serde_json::Value {
        serde_json::json!({
            "uri": "at://did:plc:renamer5/community.lexicon.rss.subscription/rk-keep",
            "cid": "bafyreibefore",
            "value": {
                "$type": "community.lexicon.rss.subscription",
                "url": url,
                "title": "Old title",
                "private": false,
                "createdAt": "2024-03-01T00:00:00.000Z"
            }
        })
    }
    const AT_URI_SUB: &str =
        "at://did:plc:ohutz6x5acjmpuulp3x7wxxc/site.standard.publication/3lab2c4d5e6f7g8h";
    const AT_URI_SUB_ENC: &str =
        "at%3A%2F%2Fdid%3Aplc%3Aohutz6x5acjmpuulp3x7wxxc%2Fsite.standard.publication%2F3lab2c4d5e6f7g8h";

    /// **Retitling an existing `at://` subscription must work with the flag off.**
    ///
    /// The storability guard was placed before the repo lookup, so it refused
    /// any rename whose URL is an at-URI — including a pure title or folder
    /// change on a record that already exists. On main that rename succeeded;
    /// the 19 production records would have become un-editable. The flag gates
    /// what may be STORED in the cache, not whether a reader may edit their own
    /// record: the PDS write goes through, the cache row is simply not created.
    #[tokio::test]
    async fn retitling_an_existing_at_uri_subscription_survives_the_flag_being_off() {
        let did = "did:plc:renamer5";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_at_uri_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        assert!(
            !state.config.standard_site,
            "the flag must be off for this test"
        );
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!("url={AT_URI_SUB_ENC}&title=New+title")))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert_eq!(loc, "/", "the retitle was refused: {loc}");

        let bodies = puts.lock().unwrap().clone();
        assert_eq!(bodies.len(), 1, "expected exactly one put, got {bodies:?}");
        let sent: serde_json::Value = serde_json::from_str(&bodies[0]).expect("put body is JSON");
        assert_eq!(
            sent["record"]["title"], "New title",
            "the rename did not apply"
        );
        assert_eq!(
            sent["record"]["url"], AT_URI_SUB,
            "the rename changed the URL"
        );

        // The flag still means what it says for the CACHE: no at:// row.
        let cached: i64 = store::count_unpollable_feeds(&state.db).await.unwrap();
        assert_eq!(cached, 0, "a retitle stored an at:// row with the flag off");
    }

    /// **Repointing a subscription AT an `at://` URI is still refused with the
    /// flag off** — the half of the guard that has to survive the fix above.
    /// Nothing reaches the PDS and nothing reaches the cache.
    #[tokio::test]
    async fn repointing_a_subscription_at_an_at_uri_is_refused_with_the_flag_off() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!("url={AT_URI_SUB_ENC}&title=Moved")))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(loc.contains("flash="), "the repoint was not refused: {loc}");
        assert!(
            !loc.contains("Private"),
            "a storability refusal was reported as a privacy one: {loc}"
        );
        assert!(
            puts.lock().unwrap().is_empty(),
            "the repoint reached the PDS"
        );
        let cached: i64 = store::count_unpollable_feeds(&state.db).await.unwrap();
        assert_eq!(cached, 0);
    }

    /// Posts a retitle of `rk-keep` with its URL unchanged; returns the
    /// redirect location.
    async fn retitle_unchanged(state: &AppState, did: &str, url_enc: &str) -> String {
        let cookie = session_cookie(state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!("url={url_enc}&title=New+title")))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        resp.headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap()
            .to_string()
    }

    /// **The privacy gate has the same ordering bug the storable gate had.**
    ///
    /// Another client can write a subscription whose URL is an at-URI that is
    /// not a well-formed publication URI at all — a feed generator, say. On
    /// main a retitle of it succeeded (the DID form fails `Url::parse`, which
    /// the classifier reads as `Public`). The narrowed at:// arm now fails
    /// closed as `Private` for it, and the gate ran before `url_changed` was
    /// known — so the record became un-editable, with a flash claiming it "was
    /// not saved or sent anywhere". Both gates now apply to a repoint only.
    #[tokio::test]
    async fn retitling_an_existing_at_uri_record_that_is_not_a_publication_survives() {
        let did = "did:plc:renamer5";
        let other = "at://did:plc:ohutz6x5acjmpuulp3x7wxxc/app.bsky.feed.generator/whats-hot";
        let other_enc =
            "at%3A%2F%2Fdid%3Aplc%3Aohutz6x5acjmpuulp3x7wxxc%2Fapp.bsky.feed.generator%2Fwhats-hot";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription_with_url(other)).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let loc = retitle_unchanged(&state, did, other_enc).await;
        assert_eq!(loc, "/", "the retitle was refused: {loc}");
        let bodies = puts.lock().unwrap().clone();
        assert_eq!(bodies.len(), 1, "expected exactly one put, got {bodies:?}");
        let sent: serde_json::Value = serde_json::from_str(&bodies[0]).unwrap();
        assert_eq!(sent["record"]["title"], "New title");
        assert_eq!(sent["record"]["url"], other);
    }

    /// **A repoint to a secret-bearing URL is still refused** — the half of
    /// the privacy gate that has to survive moving it behind `url_changed`.
    /// Found by mutation: with the gate deleted outright, nothing failed.
    #[tokio::test]
    async fn repointing_a_subscription_at_a_private_feed_is_refused() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(
                        "url=https%3A%2F%2Fpaid.example%2Ffeed.xml%3Ftoken%3DZm9vYmFyc2VjcmV0dG9rZW4&title=Moved",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("Private"),
            "the private repoint was not refused: {loc}"
        );
        assert!(
            puts.lock().unwrap().is_empty(),
            "a secret-bearing URL reached the PDS"
        );
        // The repo's fixture token: opaque enough for the classifier, not a real
        // key shape (a Stripe-shaped fixture tripped the secret scanner — rightly).
        let leaked = "https://paid.example/feed.xml?token=Zm9vYmFyc2VjcmV0dG9rZW4";
        assert!(store::get_feed_by_url(&state.db, leaked)
            .await
            .unwrap()
            .is_none());
    }

    /// **A retitle of a never-cached at:// subscription is not "at feed
    /// capacity".** The global-ceiling check keyed on "URL not in the cache",
    /// and an at:// record is never cached with the flag off — so at capacity,
    /// a pure retitle was refused for a row the handler would not insert. The
    /// check now runs once `url_changed` is known and only for a repoint.
    #[tokio::test]
    async fn retitling_an_uncached_at_uri_subscription_is_not_refused_at_feed_capacity() {
        let did = "did:plc:renamer5";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_at_uri_subscription()).await;
        // Ceiling 1, and one real feed already fills it.
        let state = test_state_with_sidecar_and(&[did], &sidecar, false, 1).await;
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://filler.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let loc = retitle_unchanged(&state, did, AT_URI_SUB_ENC).await;
        assert_eq!(loc, "/", "the retitle was refused: {loc}");
        assert_eq!(
            puts.lock().unwrap().len(),
            1,
            "the retitle did not reach the PDS"
        );
        assert_eq!(
            store::count_feeds(&state.db).await.unwrap(),
            1,
            "a row was inserted"
        );
    }

    /// **With the flag ON, a well-formed at:// paste is still refused as
    /// unsupported** — not "Couldn't find a feed" plus a `warn!`. Nothing can
    /// fetch `at://` until the reader is wired, whatever the flag says, and the
    /// docs promise this answer "with the flag on or off". This is also the
    /// suite's first state with the flag on: every other site passes the flag
    /// through with `false`, where a literal `false` would be indistinguishable.
    #[tokio::test]
    async fn a_well_formed_at_uri_paste_is_refused_as_unsupported_with_the_flag_on() {
        let did = "did:plc:renamer5";
        let (sidecar, _puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar_and(&[did], &sidecar, true, 0).await;
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!("url={AT_URI_SUB_ENC}")))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("kind%20of%20feed"),
            "expected the unsupported flash: {loc}"
        );
        assert_eq!(store::count_feeds(&state.db).await.unwrap(), 0);
    }

    /// **With the flag ON, an OPML at:// entry is stored.** The one storage
    /// path that is meant to work today, asserted with the flag actually on.
    #[tokio::test]
    async fn opml_import_stores_an_at_uri_entry_with_the_flag_on() {
        let did = "did:plc:renamer5";
        let (sidecar, _puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar_and(&[did], &sidecar, true, 0).await;
        let opml = format!(
            "<?xml version=\"1.0\"?>\n<opml version=\"2.0\"><head><title>t</title></head><body>\n\
             <outline type=\"rss\" text=\"Real\" xmlUrl=\"https://real.example/feed.xml\"/>\n\
             <outline type=\"rss\" text=\"Pub\" xmlUrl=\"{AT_URI_SUB}\"/>\n\
             </body></opml>"
        );
        let (ct, body) = opml_multipart(opml.as_bytes());
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/opml")
                    .header(header::COOKIE, cookie)
                    .header("content-type", ct)
                    .body(Body::from(body))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("Imported%202%20feeds"),
            "unexpected flash: {loc}"
        );
        assert!(
            !loc.contains("skipped"),
            "the at:// entry was skipped with the flag on: {loc}"
        );
        let stored = store::get_feed_by_url(&state.db, AT_URI_SUB).await.unwrap();
        assert!(
            stored.is_some(),
            "the at:// entry was not stored with the flag on"
        );
    }

    /// **A retitle must not cache a secret-bearing URL.** Moving the privacy
    /// gate behind `url_changed` was right for the PDS write — the record is
    /// the reader's — but the cache write was gated only on `storable`, which
    /// any http(s) URL is. So a retitle of a record another client wrote with
    /// a tokened feed URL inserted that URL into the shared `feeds` table,
    /// where the poller would fail it every cycle and print it on the admin
    /// page. main refused the whole rename; this keeps the record editable and
    /// the cache clean, as `resolve_subscriptions` already does for the same
    /// record.
    #[tokio::test]
    async fn retitling_a_secret_bearing_record_does_not_cache_its_url() {
        let did = "did:plc:renamer5";
        let tokened = "https://www.patreon.com/rss/author?auth=Zm9vYmFyc2VjcmV0dG9rZW4";
        let tokened_enc =
            "https%3A%2F%2Fwww.patreon.com%2Frss%2Fauthor%3Fauth%3DZm9vYmFyc2VjcmV0dG9rZW4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription_with_url(tokened)).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let loc = retitle_unchanged(&state, did, tokened_enc).await;
        assert_eq!(loc, "/", "the retitle was refused: {loc}");
        assert_eq!(
            puts.lock().unwrap().len(),
            1,
            "the retitle did not reach the PDS"
        );
        assert!(
            store::get_feed_by_url(&state.db, tokened)
                .await
                .unwrap()
                .is_none(),
            "a secret-bearing URL was written to the shared cache by a retitle"
        );
    }

    /// **On a repoint, storability is decided before privacy and capacity** —
    /// the same ordering the add path got. A malformed at:// target drew the
    /// private/paid flash, and at capacity a well-formed one drew "try again
    /// later" for a URL that can never be accepted with the flag off.
    #[tokio::test]
    async fn repointing_at_a_malformed_at_uri_is_refused_as_unsupported() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(
                        "url=at%3A%2F%2Fdid%3Aplc%3ATOOSHORT%2Fsite.standard.publication%2F3lab&title=Moved",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("kind%20of%20feed"),
            "expected the unsupported flash: {loc}"
        );
        assert!(
            !loc.contains("Private"),
            "a typo was reported as a paid feed: {loc}"
        );
        assert!(puts.lock().unwrap().is_empty());
    }

    #[tokio::test]
    async fn repointing_at_an_at_uri_at_capacity_is_refused_as_unsupported_not_capacity() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar_and(&[did], &sidecar, false, 1).await;
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://filler.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(format!("url={AT_URI_SUB_ENC}&title=Moved")))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("kind%20of%20feed"),
            "expected the unsupported flash: {loc}"
        );
        assert!(
            !loc.contains("capacity"),
            "an unacceptable URL was reported as a capacity problem: {loc}"
        );
        assert!(puts.lock().unwrap().is_empty());
    }

    /// **`url_changed` compares like for like.** The form value is trimmed;
    /// the record's URL was compared raw, so a record another client wrote
    /// with a trailing space read as a repoint on every retitle and re-armed
    /// every gate — including the one that made an at:// record un-editable.
    #[tokio::test]
    async fn retitling_a_record_whose_url_carries_whitespace_is_not_a_repoint() {
        let did = "did:plc:renamer5";
        let padded = format!("{AT_URI_SUB} ");
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription_with_url(&padded)).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        // The manage row posts the record's URL verbatim, padding included.
        let loc = retitle_unchanged(&state, did, &format!("{AT_URI_SUB_ENC}%20")).await;
        assert_eq!(
            loc, "/",
            "the retitle was treated as a repoint and refused: {loc}"
        );
        let bodies = puts.lock().unwrap().clone();
        assert_eq!(bodies.len(), 1);
        let sent: serde_json::Value = serde_json::from_str(&bodies[0]).unwrap();
        assert_eq!(
            sent["record"]["url"], AT_URI_SUB,
            "the padding was not normalised away"
        );
    }

    /// **A retitle inserts no cache row.** The ceiling is checked on a repoint
    /// only, so the trailing upsert must not create a row for an unchanged URL
    /// that has none — with the flag on and the cache full, each retitle of a
    /// never-cached at:// record was a row past the cap. An existing row still
    /// gets its title kept in step.
    #[tokio::test]
    async fn retitling_an_uncached_record_at_capacity_inserts_no_row() {
        let did = "did:plc:renamer5";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_at_uri_subscription()).await;
        let state = test_state_with_sidecar_and(&[did], &sidecar, true, 1).await;
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://filler.example/feed.xml".to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        let loc = retitle_unchanged(&state, did, AT_URI_SUB_ENC).await;
        assert_eq!(loc, "/", "the retitle was refused: {loc}");
        assert_eq!(puts.lock().unwrap().len(), 1);
        assert_eq!(
            store::count_feeds(&state.db).await.unwrap(),
            1,
            "a retitle inserted a cache row past the ceiling"
        );
    }

    /// **The add path's at:// pre-check is about the MESSAGE, so it is
    /// case-insensitive.** `Url::parse` folds the scheme, so `AT://…` skipped
    /// the pre-check and the classifier's at:// arm alike, parsed as `at`, and
    /// tripped the secret heuristic on the rkey — the private/paid flash the
    /// pre-check exists to avoid. Storage stays case-sensitive; this does not
    /// touch it.
    #[tokio::test]
    async fn an_uppercase_at_scheme_paste_is_refused_as_unsupported() {
        let did = "did:plc:typoist";
        let state = test_state_with_caps(did, 0, 0).await;
        let cookie = session_cookie(&state, did, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(
                        "url=AT%3A%2F%2Falice.example.com%2Fsite.standard.publication%2F3lab2c4d5e6f7g8h",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("kind%20of%20feed"),
            "expected the unsupported flash: {loc}"
        );
        assert!(!loc.contains("Private"), "reported as a paid feed: {loc}");
    }

    /// **A rename must not destroy the fields the form never carries.**
    ///
    /// `update_subscription` is a `putRecord` — the WHOLE record is replaced, per
    /// its own doc. The handler built a fresh `Subscription::new(url, now())`, so
    /// every field absent from `templates/manage_row.html` (which posts only
    /// `url`, `title`, `folder`) was written back as its default:
    ///
    /// | field | before | after |
    /// |---|---|---|
    /// | `siteUrl` | whatever the feed advertised | gone |
    /// | `fetchHint` | as set | gone |
    /// | `private` | as set | gone |
    /// | `createdAt` | original subscribe time | reset to now |
    ///
    /// `createdAt` is the worst of the four: it is the sort key for "when did I
    /// subscribe", it is unrecoverable once overwritten, and nothing in the UI
    /// tells the reader it moved.
    ///
    /// Asserted on the BYTES THE SIDECAR RECEIVES, not on a `Subscription` built
    /// in the test — the record only becomes wrong on the way out, so checking
    /// the value we passed in would pass just as happily with the fix removed.
    #[tokio::test]
    async fn renaming_preserves_the_fields_the_form_never_carries() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    // Exactly what the manage row posts: url, title, folder.
                    .body(Body::from(
                        "url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=New+title&folder=Tech",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);

        let bodies = puts.lock().unwrap().clone();
        assert_eq!(bodies.len(), 1, "expected exactly one put, got {bodies:?}");
        let body = &bodies[0];
        // Anchors the negative assertions: an empty capture would satisfy them.
        assert!(
            body.contains("community.lexicon.rss.subscription"),
            "captured no usable put body: {body:?}"
        );

        let sent: serde_json::Value = serde_json::from_str(body).expect("put body is JSON");
        let record = &sent["record"];

        // What the form DID carry must be applied.
        assert_eq!(record["title"], "New title", "the rename did not apply");
        assert_eq!(record["folder"], "Tech", "the re-folder did not apply");

        // What the form did NOT carry must survive.
        assert_eq!(
            record["createdAt"], "2024-03-01T00:00:00.000Z",
            "the rename reset createdAt — the reader's subscribe time is gone \
             from their own repo, and nothing told them"
        );
        assert_eq!(
            record["siteUrl"], "https://example.com/blog",
            "the rename erased siteUrl"
        );
        assert_eq!(record["fetchHint"], "hourly", "the rename erased fetchHint");
        assert_eq!(record["private"], false, "the rename erased private");
    }

    /// **Repointing at a different feed drops that feed's properties, but not
    /// the subscription's.**
    ///
    /// `siteUrl` and `fetchHint` describe the feed the subscription points at,
    /// so carrying them onto a different URL would leave a site link for the old
    /// feed hanging off the new one. `createdAt` and `private` are properties of
    /// the SUBSCRIPTION and survive a repoint — the reader subscribed when they
    /// subscribed, whatever the URL was later corrected to.
    #[tokio::test]
    async fn repointing_a_feed_drops_the_old_feeds_properties_but_keeps_the_subscriptions() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    // A DIFFERENT feed URL from the seeded record.
                    .body(Body::from(
                        "url=https%3A%2F%2Fother.example%2Ffeed.xml&title=Repointed",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);

        let bodies = puts.lock().unwrap().clone();
        assert_eq!(bodies.len(), 1, "expected exactly one put, got {bodies:?}");
        assert!(
            bodies[0].contains("community.lexicon.rss.subscription"),
            "captured no usable put body: {:?}",
            bodies[0]
        );
        let sent: serde_json::Value = serde_json::from_str(&bodies[0]).expect("put body is JSON");
        let record = &sent["record"];

        assert_eq!(record["url"], "https://other.example/feed.xml");
        // The old feed's properties are gone rather than misattributed.
        assert!(
            record.get("siteUrl").is_none() || record["siteUrl"].is_null(),
            "the old feed's site link followed the subscription to a new feed: {record}"
        );
        assert!(
            record.get("fetchHint").is_none() || record["fetchHint"].is_null(),
            "the old feed's fetch hint followed the subscription to a new feed: {record}"
        );
        // The subscription's own properties survive.
        assert_eq!(
            record["createdAt"], "2024-03-01T00:00:00.000Z",
            "a repoint is still not a new subscription; createdAt must not move"
        );
        assert_eq!(record["private"], false, "the repoint erased private");
    }

    /// **A rename against an rkey that is not in the repo writes NOTHING.**
    ///
    /// `update_subscription` is a `putRecord`, which CREATES the record when the
    /// rkey does not exist — with whatever `createdAt` we hand it. So without
    /// this refusal a rename against a stale or wrong rkey manufactures a
    /// subscription dated today, which is the bug this whole change exists to
    /// fix, arriving by a different door.
    ///
    /// The guard was untested when first written: removing it left all 733 tests
    /// green. An untested guard against the exact defect being fixed is how the
    /// two previous rounds of this problem got through.
    #[tokio::test]
    async fn renaming_an_unknown_rkey_writes_nothing() {
        let did = "did:plc:renamer4";
        // The sidecar serves exactly one record, at rkey `rk-keep`.
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    // ...and this is not it.
                    .uri("/subscriptions/rk-does-not-exist/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(
                        "url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=Ghost",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("flash="),
            "an unknown rkey redirected as though the rename had worked: {loc}"
        );
        assert!(
            puts.lock().unwrap().is_empty(),
            "a rename against an unknown rkey wrote a record — putRecord would \
             CREATE it, dated today: {:?}",
            puts.lock().unwrap()
        );
    }

    /// **A `site_url` the client actually sends is applied, not dropped.**
    ///
    /// `templates/manage_row.html` does not post this field, so it is tempting
    /// to read the arm that handles it as dead code. It is not:
    /// `RenameSubForm` carries `site_url`, so a hand-crafted POST reaches it
    /// today. Discarding the value instead of applying it left all 733 tests
    /// green.
    ///
    /// The value is scheme-checked on the way out by the repo-boundary vet, so
    /// this is a coverage gap rather than an exposure — but an untested path
    /// that writes a URL into the reader's PDS should not stay untested.
    #[tokio::test]
    async fn a_client_supplied_site_url_reaches_the_record() {
        let did = "did:plc:renamer4";
        let (sidecar, puts) = spawn_rename_sidecar(seeded_subscription()).await;
        let state = test_state_with_sidecar(&[did], &sidecar).await;
        let cookie = session_cookie(&state, did, None);

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    // Same feed URL, but carrying a site_url the manage row
                    // never sends.
                    .body(Body::from(
                        "url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=Kept\
                         &site_url=https%3A%2F%2Ftyped.example%2Fsite",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::SEE_OTHER);

        let bodies = puts.lock().unwrap().clone();
        assert_eq!(bodies.len(), 1, "expected exactly one put, got {bodies:?}");
        assert!(
            bodies[0].contains("community.lexicon.rss.subscription"),
            "captured no usable put body: {:?}",
            bodies[0]
        );
        let sent: serde_json::Value = serde_json::from_str(&bodies[0]).expect("put body is JSON");
        assert_eq!(
            sent["record"]["siteUrl"], "https://typed.example/site",
            "the client's siteUrl was dropped; the seeded record's survived instead"
        );
    }

    /// **A rename whose read fails writes NOTHING.**
    ///
    /// This is the property most easily lost when someone later touches this
    /// handler: falling back to `Subscription::new` on a read error looks like
    /// graceful degradation and is in fact the original bug, reinstated on
    /// exactly the path where it is hardest to notice. The reader must be told
    /// instead.
    #[tokio::test]
    async fn a_rename_whose_read_fails_writes_nothing() {
        let did = "did:plc:renamer5";
        // A port that accepts nothing: the read cannot succeed.
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let dead = format!("http://{}", listener.local_addr().unwrap());
        drop(listener);

        let state = test_state_with_sidecar(&[did], &dead).await;
        let cookie = session_cookie(&state, did, None);
        let before = store::count_feeds(&state.db).await.unwrap();

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .method("POST")
                    .uri("/subscriptions/rk-keep/rename")
                    .header(header::COOKIE, cookie)
                    .header("content-type", "application/x-www-form-urlencoded")
                    .body(Body::from(
                        "url=https%3A%2F%2Fexample.com%2Ffeed.xml&title=Doomed",
                    ))
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::SEE_OTHER);
        let loc = resp
            .headers()
            .get(header::LOCATION)
            .unwrap()
            .to_str()
            .unwrap();
        assert!(
            loc.contains("flash="),
            "a failed read redirected as though the rename had worked: {loc}"
        );
        assert_eq!(
            store::count_feeds(&state.db).await.unwrap(),
            before,
            "a rename that could not read the record still wrote to the cache"
        );
    }

    /// Folder pre-selection regression: the manage rename row must mark the
    /// feed's CURRENT folder `<option>` as `selected`, so an untouched Save
    /// re-submits the current folder instead of silently un-foldering the feed.
    /// A loose (un-foldered) feed must mark "No folder" selected instead. Renders
    /// `ManageTemplate` directly so no PDS/sidecar round-trip is needed.
    #[test]
    fn manage_rename_row_preselects_current_folder() {
        let nav = Nav {
            handle: "@reader.example".to_string(),
            avatar: "RE".to_string(),
            view: "unread".to_string(),
            scope_qs: String::new(),
            folders: Vec::new(),
            loose_feeds: Vec::new(),
            manage_active: true,
        };
        let folder_options = vec![
            FolderOption {
                uri: "at://did:plc:x/app.folder/work".to_string(),
                name: "Work".to_string(),
            },
            FolderOption {
                uri: "at://did:plc:x/app.folder/fun".to_string(),
                name: "Fun".to_string(),
            },
        ];
        // A foldered feed (in "Work") and a loose feed (no folder), each with a
        // non-empty rkey so the rename form renders.
        let foldered = FeedView {
            rkey: "sub-foldered".to_string(),
            url: "https://work.example/feed.xml".to_string(),
            title: "Work Feed".to_string(),
            unread: 0,
            selected: false,
            folder: Some("at://did:plc:x/app.folder/work".to_string()),
        };
        let loose = FeedView {
            rkey: "sub-loose".to_string(),
            url: "https://loose.example/feed.xml".to_string(),
            title: "Loose Feed".to_string(),
            unread: 0,
            selected: false,
            folder: None,
        };
        let tmpl = ManageTemplate {
            version: VERSION,
            repo_url: REPO_URL,
            kofi_url: KOFI_URL,
            flash: String::new(),
            nav,
            folder_options,
            folders: vec![FolderView {
                rkey: "folder-work".to_string(),
                uri: "at://did:plc:x/app.folder/work".to_string(),
                name: "Work".to_string(),
                feeds: vec![foldered],
                selected: false,
            }],
            loose_feeds: vec![loose],
        };
        let html = tmpl.render().unwrap();

        // The foldered feed's "Work" option is pre-selected.
        assert!(
            html.contains(
                r#"<option value="at://did:plc:x/app.folder/work" selected>Work</option>"#
            ),
            "foldered feed must pre-select its current folder: {html}"
        );
        // The loose feed's "No folder" option is pre-selected (appears for the
        // loose row, which has folder=None).
        assert!(
            html.contains(r#"<option value="" selected>No folder</option>"#),
            "loose feed must pre-select 'No folder': {html}"
        );
    }

    /// **The public stats page carries no user data.**
    ///
    /// It is reachable by anyone, so the thing worth pinning is what it does
    /// NOT say: nothing about how many people use the instance, nothing about
    /// which feeds fail, nothing about who reads what.
    #[tokio::test]
    async fn the_public_stats_page_exposes_no_user_data() {
        let state = test_state(&[]).await;
        store::ensure_seed(&state.db, &["did:plc:someone".to_string()])
            .await
            .unwrap();

        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri("/stats")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK, "stats must be public");

        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();

        // Structural checks, not word checks. The page's own prose says it
        // publishes no error rates, so searching for that PHRASE finds the
        // disclaimer rather than a leak — the first version of this test failed
        // on exactly that. What matters is whether identifiers or the
        // admin-only figures are present.
        assert!(
            !body.contains("did:"),
            "the public stats page leaked an identifier"
        );
        for admin_only in ["errp50ms", "p95ms", "live backend", "ok_count"] {
            assert!(
                !body.contains(admin_only),
                "the public page is showing the admin metrics column {admin_only:?}"
            );
        }
        // And it does render the aggregate it exists for.
        assert!(body.contains("Feeds tracked"));
        assert!(body.contains("Waiting to be polled"));
    }

    /// **The two states that stop feeds updating must be visible.**
    ///
    /// `overdue` and `polled_last_hour` move in BOTH and distinguish neither —
    /// and `overdue` moves the WRONG WAY for backoff, because backoff is applied
    /// by pushing `next_poll` forward, so a feed failing every fetch drops out of
    /// the backlog and makes the page read healthier. That inversion is what this
    /// test pins: a broken feed must raise a number, not lower one.
    #[tokio::test]
    async fn stats_distinguishes_backoff_from_a_watermark_pause() {
        let state = test_state(&[]).await;
        // Three feeds: one healthy, one flaky, one long dead.
        for (url, errors) in [
            ("https://ok.example/f.xml", 0),
            ("https://flaky.example/f.xml", 2),
            ("https://dead.example/f.xml", 9),
        ] {
            store::upsert_feed(
                &state.db,
                &store::NewFeed {
                    url: url.to_string(),
                    // Pushed forward, exactly as backoff does — so none of these
                    // are counted as `overdue`.
                    next_poll: Some("2099-01-01T00:00:00Z".to_string()),
                    ..Default::default()
                },
            )
            .await
            .unwrap();
            for _ in 0..errors {
                store::bump_feed_errors(
                    &state.db,
                    url,
                    feed::FailureKind::Fetch,
                    "connection refused",
                )
                .await
                .unwrap();
            }
        }

        let render_stats = |state: AppState| async move {
            let resp = router(state)
                .oneshot(
                    Request::builder()
                        .uri("/stats")
                        .body(Body::empty())
                        .unwrap(),
                )
                .await
                .unwrap();
            assert_eq!(resp.status(), StatusCode::OK);
            String::from_utf8(
                axum::body::to_bytes(resp.into_body(), usize::MAX)
                    .await
                    .unwrap()
                    .to_vec(),
            )
            .unwrap()
        };

        // **The fixture must actually be RUNNING, or this test measures nothing.**
        // `test_state` leaves `schedulers_enabled` false, and `fetching_state`
        // checks that BEFORE the watermark — so without these two lines every
        // render below reports "off" and the watermark can never surface. The
        // assertions still passed, for reasons unrelated to what they name: see
        // the two comments below.
        state.runtime_health.set_schedulers_enabled(true);
        state
            .runtime_health
            .poll_tick_completed(crate::store::now_unix());

        let body = render_stats(state.clone()).await;
        assert!(
            body.contains("Failing"),
            "backoff is still invisible on the public page"
        );
        // 2 failing, 1 of them badly (>= BADLY_BROKEN_ERRORS). Matched on the
        // value rather than on surrounding whitespace, so re-indenting the
        // template cannot break this.
        assert!(
            body.contains("2, 1 badly"),
            "expected '2, 1 badly' in the failing row; got:\n{}",
            body.split("Failing")
                .nth(1)
                .unwrap_or("")
                .chars()
                .take(300)
                .collect::<String>()
        );
        // Not paused, and the backlog is genuinely empty — which is exactly the
        // reading that used to be indistinguishable from healthy.
        //
        // **Asserted by EXCLUDING the other states, not by matching "running".**
        // The `off` row reads "the poller is not running on this instance", which
        // contains "running" — so the bare substring passed while the page was
        // reporting the exact opposite of what this line claims to check.
        assert!(
            !body.contains("the poller is not running")
                && !body.contains("the cache is at its size limit")
                && !body.contains("has not completed a round"),
            "expected the running state; the page reported a stopped one",
        );

        // Now trip the watermark. Nothing in the database changes; only the
        // recorded runtime state does — which is the whole reason it needed a
        // home outside the log stream.
        state.runtime_health.set_watermark(true);
        let paused = render_stats(state.clone()).await;
        // Matched on the paused row's OWN sentence. The bare word "paused" also
        // appeared in the page's explanatory prose, so this assertion passed
        // whether or not the row rendered — and trimming that prose is what
        // exposed it. This phrase exists only inside the `paused` branch.
        assert!(
            paused.contains("the cache is at its size limit"),
            "a watermark pause is still invisible on the public page"
        );

        // Still no identifiers: these are counts, not feeds.
        for leak in ["ok.example", "flaky.example", "dead.example", "did:"] {
            assert!(
                !paused.contains(leak),
                "the public page leaked {leak:?} while reporting failures"
            );
        }
    }

    /// **`/admin/metrics` is gated, and nothing checked that it was.**
    ///
    /// Deleting the `admin_seed_dids` check left the entire suite green. That
    /// was survivable while the page held only aggregate timings; it is not now,
    /// because this branch puts **per-feed URLs and remote error text** behind
    /// that gate. A guarantee nothing checks is a comment, and this one is now
    /// the only thing standing between a signed-in stranger and the operational
    /// picture the handler's own doc says is not public.
    ///
    /// All three doors: no session, a session that is not an admin, and the
    /// admin itself.
    #[tokio::test]
    async fn admin_metrics_is_refused_to_everyone_but_an_admin() {
        let admin = "did:plc:adminseed";
        // **Only the admin is in ALLOWED_DIDS**, because `admin_seed_dids()`
        // IS that list — deliberately, per its doc: "the same people I trust on
        // this instance". Production sets it to the bootstrap DID alone.
        //
        // A genuine non-admin is therefore someone holding a beta seat granted
        // by an invite, not by the allow-list. Seeding both would have made
        // both admins and quietly turned the 403 assertion below into a test of
        // nothing — which is exactly what the first draft of this did.
        let state = test_state(&[admin]).await;
        store::grant_access(&state.db, "did:plc:ordinaryuser", None, "invite", None)
            .await
            .unwrap();
        let url = "https://broken.example/f.xml";
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: url.to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::bump_feed_errors(
            &state.db,
            url,
            feed::FailureKind::Fetch,
            "SENTINEL_ADMIN_ONLY",
        )
        .await
        .unwrap();

        let get = |state: AppState, cookie: Option<String>| async move {
            let mut req = Request::builder().uri("/admin/metrics");
            if let Some(c) = cookie {
                req = req.header(header::COOKIE, c);
            }
            let resp = router(state)
                .oneshot(req.body(Body::empty()).unwrap())
                .await
                .unwrap();
            let status = resp.status();
            let body = String::from_utf8(
                axum::body::to_bytes(resp.into_body(), usize::MAX)
                    .await
                    .unwrap()
                    .to_vec(),
            )
            .unwrap();
            (status, body)
        };

        // No session at all.
        let (status, body) = get(state.clone(), None).await;
        assert_eq!(status, StatusCode::UNAUTHORIZED);
        assert!(
            !body.contains("SENTINEL_ADMIN_ONLY"),
            "leaked to anonymous: {body}"
        );

        // A real, signed-in user who is not an admin.
        let ordinary = session_cookie(&state, "did:plc:ordinaryuser", None);
        let (status, body) = get(state.clone(), Some(ordinary)).await;
        assert_eq!(
            status,
            StatusCode::FORBIDDEN,
            "a non-admin session was let in"
        );
        assert!(
            !body.contains("SENTINEL_ADMIN_ONLY") && !body.contains("broken.example"),
            "leaked to a non-admin: {body}",
        );

        // The admin does get it — otherwise the two refusals above are
        // satisfied by the endpoint being broken for everyone.
        let admin_cookie = session_cookie(&state, admin, None);
        let (status, body) = get(state, Some(admin_cookie)).await;
        assert_eq!(status, StatusCode::OK);
        assert!(
            body.contains("SENTINEL_ADMIN_ONLY"),
            "admin cannot see it: {body}"
        );
    }

    /// **The cause a public count cannot carry belongs on the admin page.**
    ///
    /// The public histogram is four coarse buckets, and `fetch` is the coarsest:
    /// #159's own error — `guarded_get` bailing on a 304 — lands there beside
    /// DNS failure, timeout and SSRF refusal. So the histogram alone would NOT
    /// have separated "sixty dead publishers" from "one bug here", which is the
    /// case it was justified by.
    ///
    /// The answer is not a finer public vocabulary — `/stats` promises never
    /// which feed and never whose, and a bucket per error string would break
    /// that. It is to put the detail where per-feed data is already allowed.
    /// `/admin/metrics` is gated on `ALLOWED_DIDS` and already carries an
    /// operational picture.
    ///
    /// Asserts both halves: the detail IS on the admin page, and is NOT on the
    /// public one.
    #[tokio::test]
    async fn the_admin_page_names_failing_feeds_and_the_public_page_does_not() {
        let admin = "did:plc:adminseed";
        let state = test_state(&[admin]).await;
        let url = "https://broken.example/f.xml";
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: url.to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::bump_feed_errors(
            &state.db,
            url,
            feed::FailureKind::Fetch,
            "SENTINEL_REDIRECT_NO_LOCATION",
        )
        .await
        .unwrap();

        let cookie = session_cookie(&state, admin, None);
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .uri("/admin/metrics")
                    .header(header::COOKIE, cookie)
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let admin_body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();
        assert!(
            admin_body.contains("SENTINEL_REDIRECT_NO_LOCATION"),
            "the admin page does not carry the failure detail: {admin_body}",
        );
        assert!(
            admin_body.contains("broken.example"),
            "the admin page does not name the failing feed: {admin_body}",
        );

        // The public page still carries neither.
        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri("/stats")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        let public = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();
        for secret in ["SENTINEL_REDIRECT_NO_LOCATION", "broken.example"] {
            assert!(
                !public.contains(secret),
                "{secret:?} reached the PUBLIC stats page: {public}",
            );
        }
    }

    /// **A direct poll must settle the error columns, like the scheduler does.**
    ///
    /// `add_subscription` polls through `feed::poll_feed` rather than the
    /// scheduler, and `poll_feed` writes validators and `last_polled` but never
    /// touches `consecutive_errors` — that is the scheduler's job, and this path
    /// is not the scheduler.
    ///
    /// So a feed that was failing, is re-subscribed, and polls SUCCESSFULLY kept
    /// its old count and its old cause: the public page went on reporting it
    /// under `Failing`, under `badly_broken`, and under a cause, for as long as
    /// the stale backoff horizon lasted — up to 24h — while the reader was
    /// demonstrably fetching it.
    #[tokio::test]
    async fn a_successful_direct_poll_clears_a_stale_failure() {
        let state = test_state(&[]).await;
        let url = "https://recovered.example/f.xml";
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: url.to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::bump_feed_errors(&state.db, url, feed::FailureKind::Fetch, "SENTINEL_OLD")
            .await
            .unwrap();
        // Park it on a stale backoff horizon, as a real failing feed would be.
        sqlx::query("UPDATE feeds SET next_poll = '2099-01-01T00:00:00Z' WHERE url = ?1")
            .bind(url)
            .execute(&state.db)
            .await
            .unwrap();

        // The publisher is fixed: a successful poll happens on this path.
        feed::settle_poll(
            &state.db,
            url,
            &feed::PollOutcome::NotModified,
            state.config.poll_interval,
        )
        .await;

        let row: (i64, Option<String>, Option<String>) = sqlx::query_as(
            "SELECT consecutive_errors, last_error_kind, next_poll FROM feeds WHERE url = ?1",
        )
        .bind(url)
        .fetch_one(&state.db)
        .await
        .unwrap();
        assert_eq!(row.0, 0, "a successful direct poll left the error streak");
        assert_eq!(row.1, None, "a successful direct poll left a stale cause");
        // **The half the first fix missed.** Clearing the count fixed the
        // REPORTING; the feed stayed parked until 2099. A working feed must be
        // rescheduled on its normal cadence, not left on the failure horizon.
        let next = row.2.expect("next_poll was cleared to NULL");
        // Not merely "moved off 2099" — rescheduled on the CADENCE, not a
        // backoff. A mutation that reschedules successes with backoff_for(1)
        // (5 min) also moves it off 2099, so the interval is asserted.
        let parsed = chrono::DateTime::parse_from_rfc3339(&next).unwrap();
        let delta = parsed
            .signed_duration_since(chrono::Utc::now())
            .num_seconds();
        let cadence = state.config.poll_interval.as_secs() as i64;
        assert!(
            (cadence - 60..=cadence + 60).contains(&delta),
            "expected rescheduling on the {cadence}s cadence, got {delta}s (next_poll={next})"
        );
    }

    /// The mirror case: a first poll that FAILS must be visible at all.
    ///
    /// `Ok(outcome) => info!(...)` discarded a `PollOutcome::Failed`, so a
    /// subscription whose very first fetch failed sat at `consecutive_errors = 0`
    /// with a NULL cause — invisible to the page built to count exactly that.
    #[tokio::test]
    async fn a_failing_direct_poll_is_recorded() {
        let state = test_state(&[]).await;
        let url = "https://born-broken.example/f.xml";
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: url.to_string(),
                ..Default::default()
            },
        )
        .await
        .unwrap();

        feed::settle_poll(
            &state.db,
            url,
            &feed::PollOutcome::Failed {
                backoff: std::time::Duration::from_secs(300),
                kind: feed::FailureKind::Parse,
                detail: "SENTINEL_BORN_BROKEN".to_string(),
            },
            state.config.poll_interval,
        )
        .await;

        let row: (i64, Option<String>, Option<String>) = sqlx::query_as(
            "SELECT consecutive_errors, last_error_kind, next_poll FROM feeds WHERE url = ?1",
        )
        .bind(url)
        .fetch_one(&state.db)
        .await
        .unwrap();
        assert_eq!(row.0, 1, "a failed first poll was not counted");
        assert_eq!(
            row.1.as_deref(),
            Some("parse"),
            "its cause was not recorded"
        );
        // And it is BACKED OFF on the schedule the scheduler would use — not
        // left with a NULL next_poll that `due_feeds` sorts first and re-polls
        // on the very next tick.
        let next = row.2.expect("a failed direct poll left next_poll NULL");
        let parsed = chrono::DateTime::parse_from_rfc3339(&next).unwrap();
        let delta = parsed
            .signed_duration_since(chrono::Utc::now())
            .num_seconds();
        assert!(
            (240..=360).contains(&delta),
            "expected ~300s backoff after one failure, got {delta}s (next_poll={next})"
        );
    }

    /// **The breakdown must sum to the Failing figure above it.**
    ///
    /// The histogram counts `last_error_kind IS NOT NULL`; `Failing` counts
    /// `consecutive_errors > 0`. On a migrated database every row that was
    /// already failing has a NULL kind — correctly, it was never recorded — so
    /// the two do not reconcile and the page shows "70 failing" beside "3
    /// fetch" with 67 silently unaccounted for. On deploy day the row vanishes
    /// entirely while the prose still promises a breakdown.
    ///
    /// An explicit `unknown` bucket is the honest shape: the page says how many
    /// it cannot explain rather than omitting them.
    #[tokio::test]
    async fn the_failure_breakdown_accounts_for_every_failing_feed() {
        let state = test_state(&[]).await;
        // Two legacy rows: failing, with no recorded cause.
        for url in [
            "https://legacy1.example/f.xml",
            "https://legacy2.example/f.xml",
        ] {
            store::upsert_feed(
                &state.db,
                &store::NewFeed {
                    url: url.to_string(),
                    next_poll: Some("2099-01-01T00:00:00Z".to_string()),
                    ..Default::default()
                },
            )
            .await
            .unwrap();
            sqlx::query("UPDATE feeds SET consecutive_errors = 4 WHERE url = ?1")
                .bind(url)
                .execute(&state.db)
                .await
                .unwrap();
        }
        // One row with a recorded cause.
        store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://known.example/f.xml".to_string(),
                next_poll: Some("2099-01-01T00:00:00Z".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        store::bump_feed_errors(
            &state.db,
            "https://known.example/f.xml",
            feed::FailureKind::Status,
            "SENTINEL",
        )
        .await
        .unwrap();

        let now = chrono::Utc::now();
        let health = store::poll_health(
            &state.db,
            &now.to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
            &(now - chrono::Duration::hours(1)).to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
        )
        .await
        .unwrap();
        let counted: i64 = health.failure_kinds.iter().map(|(_, n)| n).sum();
        assert_eq!(
            counted, health.in_backoff,
            "the breakdown ({counted}) does not account for all {} failing feeds: {:?}",
            health.in_backoff, health.failure_kinds,
        );
        assert!(
            health
                .failure_kinds
                .iter()
                .any(|(k, n)| k == "unknown" && *n == 2),
            "no unknown bucket for the legacy rows: {:?}",
            health.failure_kinds,
        );
    }

    /// **The breakdown is ordered by count, and the assertion can see it.**
    ///
    /// The first version of this asserted with three `contains` calls, which
    /// cannot observe order — deleting `ORDER BY` from the query passed.
    #[tokio::test]
    async fn the_failure_breakdown_is_ordered_by_count() {
        let state = test_state(&[]).await;
        for (url, kind, n) in [
            ("https://p1.example/f.xml", feed::FailureKind::Parse, 1),
            ("https://f1.example/f.xml", feed::FailureKind::Fetch, 1),
            ("https://f2.example/f.xml", feed::FailureKind::Fetch, 1),
            ("https://f3.example/f.xml", feed::FailureKind::Fetch, 1),
            ("https://s1.example/f.xml", feed::FailureKind::Status, 1),
            ("https://s2.example/f.xml", feed::FailureKind::Status, 1),
        ] {
            store::upsert_feed(
                &state.db,
                &store::NewFeed {
                    url: url.to_string(),
                    next_poll: Some("2099-01-01T00:00:00Z".to_string()),
                    ..Default::default()
                },
            )
            .await
            .unwrap();
            for _ in 0..n {
                store::bump_feed_errors(&state.db, url, kind, "d")
                    .await
                    .unwrap();
            }
        }
        let now = chrono::Utc::now();
        let health = store::poll_health(
            &state.db,
            &now.to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
            &(now - chrono::Duration::hours(1)).to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
        )
        .await
        .unwrap();
        let labels: Vec<&str> = health
            .failure_kinds
            .iter()
            .map(|(k, _)| k.as_str())
            .collect();
        assert_eq!(
            labels,
            ["fetch", "status", "parse"],
            "not ordered by count, descending: {:?}",
            health.failure_kinds,
        );
    }

    /// **Failing feeds are grouped by CAUSE, and still never named.**
    ///
    /// `badly_broken` could say that sixty feeds were failing and not whether
    /// that was sixty dead publishers or one bug here. It was the latter — #159,
    /// a `304 Not Modified` read as a malformed redirect — and the page could
    /// not say so, which is most of why it went unexamined.
    ///
    /// The second half of this test is the constraint that shapes the first:
    /// `/stats` is public and promises machines-not-people, *never which feed
    /// and never whose*. A histogram of causes keeps that promise; a list of
    /// failing URLs would break it, and is the obvious way to build this.
    #[tokio::test]
    async fn stats_groups_failures_by_cause_without_naming_any_feed() {
        let state = test_state(&[]).await;
        for (url, kind, detail, errors) in [
            // Detail strings are distinctive SENTINELS, not plausible English.
            // A first pass used "not a feed", which the page's own explanation
            // of the `parse` kind contains verbatim — the privacy assertion
            // fired on static copy rather than on a leak. A sentinel cannot
            // collide with prose.
            (
                "https://a.example/f.xml",
                feed::FailureKind::Fetch,
                "SENTINEL_CONNREFUSED",
                3,
            ),
            (
                "https://b.example/f.xml",
                feed::FailureKind::Fetch,
                "SENTINEL_DNSFAIL",
                2,
            ),
            (
                "https://c.example/f.xml",
                feed::FailureKind::Status,
                "SENTINEL_404",
                1,
            ),
            (
                "https://d.example/f.xml",
                feed::FailureKind::Parse,
                "SENTINEL_UNPARSEABLE",
                1,
            ),
        ] {
            store::upsert_feed(
                &state.db,
                &store::NewFeed {
                    url: url.to_string(),
                    next_poll: Some("2099-01-01T00:00:00Z".to_string()),
                    ..Default::default()
                },
            )
            .await
            .unwrap();
            for _ in 0..errors {
                store::bump_feed_errors(&state.db, url, kind, detail)
                    .await
                    .unwrap();
            }
        }

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .uri("/stats")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();

        // Descending by count: two fetch, then one each, tie-broken by name.
        assert!(
            body.contains("2 fetch") && body.contains("1 status") && body.contains("1 parse"),
            "the cause histogram did not render: {body}",
        );

        // **The privacy half.** No feed URL, host, or error detail reaches the
        // public page — only counts by kind.
        for secret in [
            "a.example",
            "b.example",
            "c.example",
            "d.example",
            "SENTINEL_CONNREFUSED",
            "SENTINEL_DNSFAIL",
            "SENTINEL_404",
            "SENTINEL_UNPARSEABLE",
        ] {
            assert!(
                !body.contains(secret),
                "{secret:?} reached the PUBLIC stats page: {body}",
            );
        }
    }

    /// `/health` must prove the process can reach its database, and must report
    /// the loop state without letting it change the status code.
    #[tokio::test]
    async fn health_checks_the_database_and_reports_the_loops() {
        let state = test_state(&[]).await;
        let body_of = |state: AppState| async move {
            let resp = router(state)
                .oneshot(
                    Request::builder()
                        .uri("/health")
                        .body(Body::empty())
                        .unwrap(),
                )
                .await
                .unwrap();
            let status = resp.status();
            let body = String::from_utf8(
                axum::body::to_bytes(resp.into_body(), usize::MAX)
                    .await
                    .unwrap()
                    .to_vec(),
            )
            .unwrap();
            (status, body)
        };

        // The boot stamp is what `main` sets; the router alone does not, so this
        // starts "unknown" and the uptime branch below drives it explicitly.
        state
            .runtime_health
            .set_started_at(chrono::Utc::now().timestamp());

        let (status, body) = body_of(state.clone()).await;
        assert_eq!(status, StatusCode::OK);
        assert!(
            body.contains("db: ok"),
            "health did not probe the DB: {body}"
        );
        assert!(
            body.contains("uptime:"),
            "no uptime — the first thing anyone asks about a container that may \
             be restarting: {body}"
        );
        assert!(body.contains("poller:"), "no scheduler heartbeat: {body}");
        assert!(body.contains("polling-paused: no"), "{body}");
        assert!(body.contains("backend:"), "{body}");
        assert!(body.contains("oauth-runtime:"), "{body}");

        // A watermark pause is REPORTED but must not fail the check. A failed
        // check DEREGISTERS this machine from the proxy — and it is the only
        // machine — so it would turn "feeds are behind" into "the site is down"
        // for as long as the disk stays full.
        state.runtime_health.set_watermark(true);
        state.runtime_health.set_schedulers_enabled(true);
        let (status, body) = body_of(state.clone()).await;
        assert_eq!(
            status,
            StatusCode::OK,
            "a watermark pause must not fail the liveness check: {body}"
        );
        assert!(body.contains("polling-paused: yes"), "{body}");
        // Schedulers on but no tick yet — and that must not read as "0s ago",
        // which is the healthiest possible answer to an unanswered question.
        assert!(
            body.contains("poller: not-yet-ticked"),
            "a never-ticked poller must say so: {body}"
        );

        // A stale heartbeat is likewise reported, not fatal.
        let stale_after = health_tick_stale_secs(configured_poll_tick());
        let long_ago = chrono::Utc::now().timestamp() - (stale_after + 60);
        state.runtime_health.poll_tick_completed(long_ago);
        let (status, body) = body_of(state.clone()).await;
        assert_eq!(
            status,
            StatusCode::OK,
            "a stale poller must not 503: {body}"
        );
        assert!(body.contains("poller: stale"), "{body}");

        // **A poller that has never ticked stops being benign.**
        //
        // In a crash loop with 30 s+ boot cycles the poller never reaches its
        // first tick, so `not-yet-ticked` was reported forever and the heartbeat
        // could not detect the one failure mode the startup delays were added
        // for. It is read against uptime now.
        state.runtime_health.poll_tick_completed(0); // reset to "never"
        state
            .runtime_health
            .set_started_at(chrono::Utc::now().timestamp() - (HEALTH_FIRST_TICK_GRACE_SECS + 60));
        let (status, body) = body_of(state.clone()).await;
        assert_eq!(status, StatusCode::OK);
        assert!(
            body.contains("poller: stale never-ticked"),
            "a poller that never ticked long after boot still reads as benign: {body}"
        );

        // A closed pool is a real outage: nothing can be served, and a restart is
        // the correct response. THIS is what the status code is for.
        state.db.close().await;
        let (status, body) = body_of(state.clone()).await;
        assert_eq!(
            status,
            StatusCode::SERVICE_UNAVAILABLE,
            "an unreachable database must fail the check: {body}"
        );
        assert!(body.starts_with("FAIL"), "{body}");
        // Coarse, not the raw sqlx error: an unauthenticated caller learning
        // exactly which failure it hit is an attack-progress oracle, and this
        // endpoint is exempt from the origin lock.
        assert!(
            !body.contains("PoolClosed") && !body.contains("sqlx"),
            "health leaked the raw database error to an unauthenticated caller: {body}"
        );
    }

    /// The staleness threshold must track the configured tick.
    ///
    /// Hardcoded at 15 minutes, an operator who raised
    /// `FEATHERREADER_POLL_TICK_SECS` above 900 got a permanent `poller: stale`
    /// in the body the deployment docs tell them to alert on.
    #[test]
    fn the_stale_threshold_follows_the_poll_tick() {
        // A fast tick keeps the floor — five 60 s ticks is 5 minutes, and
        // alerting that early would fire on any brief hiccup.
        assert_eq!(
            health_tick_stale_secs(Duration::from_secs(60)),
            HEALTH_TICK_STALE_FLOOR_SECS
        );
        // A slow tick raises it, so a legitimately-configured loop is never
        // permanently "stale".
        let slow = Duration::from_secs(30 * 60);
        assert!(
            health_tick_stale_secs(slow) > slow.as_secs() as i64,
            "a 30-minute tick must not be stale after one interval"
        );
        assert_eq!(health_tick_stale_secs(slow), 30 * 60 * 5);
        // And it cannot overflow into nonsense on an absurd value.
        assert!(health_tick_stale_secs(Duration::from_secs(u64::MAX)) > 0);
    }

    /// `/stats` must distinguish "nothing is polling" from "polling is fine".
    ///
    /// `polling_paused` alone rendered "running" for three different states,
    /// including the two where nothing polls at all — on the page added to
    /// answer exactly that question.
    #[tokio::test]
    async fn stats_does_not_call_a_stopped_poller_running() {
        let state = test_state(&[]).await;
        let render = |state: AppState| async move {
            let resp = router(state)
                .oneshot(
                    Request::builder()
                        .uri("/stats")
                        .body(Body::empty())
                        .unwrap(),
                )
                .await
                .unwrap();
            assert_eq!(resp.status(), StatusCode::OK);
            String::from_utf8(
                axum::body::to_bytes(resp.into_body(), usize::MAX)
                    .await
                    .unwrap()
                    .to_vec(),
            )
            .unwrap()
        };

        // Schedulers never started: not "running".
        let body = render(state.clone()).await;
        assert!(
            body.contains("the poller is not running on this instance"),
            "a disabled poller renders as healthy"
        );

        // Started, but no tick has finished yet.
        state.runtime_health.set_schedulers_enabled(true);
        let body = render(state.clone()).await;
        assert!(
            body.contains("no poll has finished since this instance booted"),
            "a poller that has not ticked renders as healthy"
        );

        // Ticking: running.
        state
            .runtime_health
            .poll_tick_completed(chrono::Utc::now().timestamp());
        let body = render(state.clone()).await;
        assert!(
            body.contains("running"),
            "a healthy poller must read as running"
        );

        // Paused at the watermark still wins over "running".
        state.runtime_health.set_watermark(true);
        let body = render(state.clone()).await;
        assert!(
            body.contains("the cache is at its size limit"),
            "a watermark pause is hidden once the poller is ticking"
        );
    }

    /// **An UNMEASURED database must not fail the check.**
    ///
    /// `/health` is the one path exempt from the Cloudflare origin lock and
    /// absent from the rate limiter, and `DbProbeGuard` releases its claim on
    /// drop WITHOUT recording a verdict — so a cancelled request (a client
    /// disconnect is enough) leaves the verdict at "none", and a concurrent
    /// caller reads it. Treating that as a failure turned an unauthenticated
    /// request into a lever on the only signal the platform acts on. The
    /// previous version of this code had the opposite bug and reported `ok` for
    /// a database nothing had read; "unknown" is neither.
    #[tokio::test]
    async fn health_reports_an_unmeasured_database_without_failing() {
        use crate::runtime_health::DbProbe;
        let state = test_state(&[]).await;

        // Hold the probe claim, exactly as an in-flight request would, and never
        // record a verdict — the cancelled-request state.
        let held = state
            .runtime_health
            .begin_db_probe()
            .unwrap_or_else(|_| panic!("a fresh RuntimeHealth must grant the first claim"));

        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .uri("/health")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        let status = resp.status();
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();
        drop(held);

        assert_eq!(
            status,
            StatusCode::OK,
            "an unmeasured database failed the check, which an unauthenticated \
             caller can cause on demand: {body}"
        );
        assert!(
            body.contains("db: unknown"),
            "the unmeasured state must still be REPORTED: {body}"
        );
        assert!(!body.starts_with("FAIL"), "{body}");
        // **And it must not read as `ok` either.** `fly.toml` tells operators to
        // alert on the BODY for everything the status code ignores, so a first
        // line identical to the healthy one makes a monitor keying on `^ok` read
        // green in exactly the state this enum exists to surface.
        assert!(
            !body.starts_with("ok"),
            "the unmeasured state is indistinguishable from healthy to a \
             body-matching monitor: {body}"
        );
        assert!(body.starts_with("unknown"), "{body}");

        // **A BORROWED failure must 503 too.**
        //
        // This previously recorded `Failed` and then closed the pool — but
        // `record` consumes the guard and releases the claim, so the request won
        // it, ran a live probe against the closed pool, and failed on its own.
        // The 503 passed for the wrong reason and the borrow path — the whole
        // point of the three-state enum on the read side — had no coverage.
        //
        // Holding the claim forces the borrow, so the recorded verdict is what
        // gets reported.
        let held = state
            .runtime_health
            .begin_db_probe()
            .unwrap_or_else(|_| panic!("claim"));
        state
            .runtime_health
            .record_for_test(DbProbe::Failed("unavailable".to_string()));
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .uri("/health")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        let status = resp.status();
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();
        drop(held);
        assert_eq!(
            status,
            StatusCode::SERVICE_UNAVAILABLE,
            "a BORROWED failure verdict must fail the check, not just a freshly \
             measured one: {body}"
        );
        assert!(body.starts_with("FAIL"), "{body}");

        state.db.close().await;
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .uri("/health")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(
            resp.status(),
            StatusCode::SERVICE_UNAVAILABLE,
            "a measured database failure must still fail the check"
        );
    }

    /// **A disconnected client must not be able to cancel the probe.**
    ///
    /// Axum drops the handler future when a caller goes away. With the probe
    /// inline that dropped it mid-flight and released the claim WITHOUT
    /// recording a verdict — which let an unauthenticated caller manufacture the
    /// no-verdict state on demand and freeze what every other caller, including
    /// Fly's own check, reads. The probe runs detached now, so the verdict is
    /// recorded whatever happens to the request that started it.
    #[tokio::test]
    async fn an_abandoned_request_still_records_its_probe() {
        use crate::runtime_health::DbProbe;
        let state = test_state(&[]).await;
        let rh = state.runtime_health.clone();

        // Drive /health and abandon it immediately — the disconnect case.
        let app = router(state.clone());
        let fut = app.oneshot(
            Request::builder()
                .uri("/health")
                .body(Body::empty())
                .unwrap(),
        );
        let handle = tokio::spawn(fut);
        handle.abort();
        let _ = handle.await;

        // The detached probe still completes and publishes a verdict, so the
        // claim is free and the next caller gets a MEASURED answer.
        for _ in 0..50 {
            if rh.begin_db_probe().is_ok() {
                break;
            }
            tokio::time::sleep(Duration::from_millis(20)).await;
        }
        let resp = router(state.clone())
            .oneshot(
                Request::builder()
                    .uri("/health")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();
        assert!(
            body.contains("db: ok"),
            "after an abandoned request the next caller still reads an \
             unmeasured database — the probe was cancelled with it: {body}"
        );
        // Sanity: the type still distinguishes the three states.
        assert_ne!(DbProbe::Unknown, DbProbe::Ok);
    }

    /// **The probe must read a real page.**
    ///
    /// `SELECT 1` compiles to `Init/Integer/ResultRow/Halt` — no `OpenRead`, so
    /// it never touches a b-tree and returns success against a corrupted
    /// database. Asserted by asking SQLite what the statement actually compiles
    /// to, so it survives someone "simplifying" the query later.
    #[tokio::test]
    async fn the_health_probe_opens_a_real_table() {
        use sqlx::Row;
        let state = test_state(&[]).await;
        // `EXPLAIN` lists the VM program; the `opcode` column is the second.
        let opcodes = |sql: &'static str| {
            let db = state.db.clone();
            async move {
                sqlx::query(sql)
                    .fetch_all(&db)
                    .await
                    .unwrap()
                    .into_iter()
                    .map(|r| r.get::<String, _>("opcode"))
                    .collect::<Vec<String>>()
            }
        };

        // The statement `health_db_probe` really runs — it is the sole path, so
        // there is no second string for the handler to use instead.
        let explain: &'static str =
            Box::leak(format!("EXPLAIN {HEALTH_DB_PROBE_SQL}").into_boxed_str());
        let probe = opcodes(explain).await;
        // And the probe itself works against a real schema.
        assert!(
            health_db_probe(&state.db).await.is_ok(),
            "the probe does not run against the real schema",
        );
        assert!(
            probe.iter().any(|op| op == "OpenRead"),
            "the health probe reads no page; it cannot detect a broken database: {probe:?}"
        );
        // And the bare form genuinely does not, which is the whole point.
        let bare = opcodes("EXPLAIN SELECT 1").await;
        assert!(
            !bare.iter().any(|op| op == "OpenRead"),
            "premise check failed: bare SELECT 1 now reads a page: {bare:?}"
        );
    }

    /// A fresh instance says "never", not "0" — which would read as "polled
    /// just now", the opposite of the truth.
    #[test]
    fn an_instance_that_has_never_polled_says_so() {
        assert_eq!(humanise_ago(None), "never");
        assert_eq!(humanise_ago(Some(0)), "0s ago");
        assert_eq!(humanise_ago(Some(59)), "59s ago");
        assert_eq!(humanise_ago(Some(60)), "1m ago");
        assert_eq!(humanise_ago(Some(3600)), "1h 0m ago");
        assert_eq!(humanise_ago(Some(11_460)), "3h 11m ago");
    }

    /// A sidecar mock that answers `/internal/repo` listRecords with one saved
    /// record, and anything else with an empty list. Serves repeatedly.
    async fn spawn_saved_sidecar(saved_url: &str, saved_title: &str) -> String {
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let (url, title) = (saved_url.to_string(), saved_title.to_string());
        tokio::spawn(async move {
            loop {
                let Ok((mut sock, _)) = listener.accept().await else {
                    break;
                };
                let mut buf = vec![0u8; 8192];
                let Ok(n) = sock.read(&mut buf).await else {
                    continue;
                };
                let req = String::from_utf8_lossy(&buf[..n]).to_string();
                let wants_saved = req.contains("community.lexicon.rss.saved");
                let records = if wants_saved {
                    serde_json::json!([{
                        "uri": "at://did:plc:x/community.lexicon.rss.saved/rk1",
                        "cid": "bafy",
                        "value": {
                            "$type": "community.lexicon.rss.saved",
                            "url": url,
                            "title": title,
                            "createdAt": "2026-01-01T00:00:00Z"
                        }
                    }])
                } else {
                    serde_json::json!([])
                };
                let body = serde_json::json!({
                    "ok": true, "data": { "records": records }
                })
                .to_string();
                let resp = format!(
                    "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
                    body.len(), body
                );
                let _ = sock.write_all(resp.as_bytes()).await;
                let _ = sock.flush().await;
            }
        });
        format!("http://{addr}")
    }

    /// A sidecar mock serving `n` distinct saved records, none of them cached
    /// locally — the shape that exercises the uncached-row append.
    async fn spawn_saved_sidecar_many(n: usize, subscribed_feed: &str) -> String {
        let feed = subscribed_feed.to_string();
        use tokio::io::{AsyncReadExt, AsyncWriteExt};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        tokio::spawn(async move {
            loop {
                let Ok((mut sock, _)) = listener.accept().await else {
                    break;
                };
                let mut buf = vec![0u8; 8192];
                let Ok(read) = sock.read(&mut buf).await else {
                    continue;
                };
                let req = String::from_utf8_lossy(&buf[..read]).to_string();
                let records = if req.contains("community.lexicon.rss.saved") {
                    serde_json::Value::Array(
                        (0..n)
                            .map(|i| {
                                serde_json::json!({
                                    "uri": format!("at://did:plc:x/community.lexicon.rss.saved/rk{i}"),
                                    "cid": "bafy",
                                    "value": {
                                        "$type": "community.lexicon.rss.saved",
                                        "url": format!("https://elsewhere.example/{i}"),
                                        "title": format!("Elsewhere {i}"),
                                        "createdAt": "2026-01-01T00:00:00Z"
                                    }
                                })
                            })
                            .collect(),
                    )
                } else if req.contains("community.lexicon.rss.subscription") {
                    // Without this the handler's `sync_sub_refs` would REPLACE
                    // sub_ref with an empty set on every render, and every
                    // sub_ref-scoped read — including the cached starred list
                    // this test is about — would come back empty.
                    serde_json::json!([{
                        "uri": "at://did:plc:x/community.lexicon.rss.subscription/sub1",
                        "cid": "bafy",
                        "value": {
                            "$type": "community.lexicon.rss.subscription",
                            "url": feed,
                            "createdAt": "2026-01-01T00:00:00Z"
                        }
                    }])
                } else {
                    serde_json::json!([])
                };
                let body =
                    serde_json::json!({ "ok": true, "data": { "records": records } }).to_string();
                let resp = format!(
                    "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
                    body.len(), body
                );
                let _ = sock.write_all(resp.as_bytes()).await;
                let _ = sock.flush().await;
            }
        });
        format!("http://{addr}")
    }

    /// **The pager must not advertise a page the clamp cannot reach.**
    ///
    /// The page clamp is computed from the CACHED total; the uncached PDS rows
    /// are appended to the last page rather than paged. Inflating `total` with
    /// them made `page_count` and the "Older →" link point one page past the end:
    /// requesting it clamped straight back, re-rendered the same last page, and
    /// still offered the link. An infinite "next" that never advances.
    #[tokio::test]
    async fn the_starred_pager_does_not_advertise_an_unreachable_page() {
        let did = "did:plc:pagerloop";
        let sidecar = spawn_saved_sidecar_many(80, "https://loop.example/feed.xml").await;
        let state = test_state_with_sidecar(&[], &sidecar).await;
        store::grant_access(&state.db, did, None, "test", None)
            .await
            .unwrap();
        let feed = store::upsert_feed(
            &state.db,
            &store::NewFeed {
                url: "https://loop.example/feed.xml".to_string(),
                title: Some("Loop".to_string()),
                ..Default::default()
            },
        )
        .await
        .unwrap();
        // 250 cached starred entries: the last page holds 50, so 50 + 80 > 100
        // and the old arithmetic reported a fourth page.
        let entries: Vec<store::NewEntry> = (0..250)
            .map(|i| store::NewEntry {
                guid: format!("s-{i:04}"),
                url: Some(format!("https://loop.example/{i}")),
                title: Some(format!("Starred {i:04}")),
                published: Some(format!("2026-06-{:02}T00:00:00Z", (i % 28) + 1)),
                ..Default::default()
            })
            .collect();
        store::insert_entries(&state.db, feed, &entries, 0)
            .await
            .unwrap();
        store::replace_sub_refs(&state.db, did, &[feed])
            .await
            .unwrap();
        for row in store::list_entries(&state.db, did, store::ListView::All, None, 1_000, 0)
            .await
            .unwrap()
        {
            store::mark_starred(&state.db, did, row.id, true)
                .await
                .unwrap();
        }

        let cookie = session_cookie(&state, did, None);
        let app = router(state.clone());
        let get = |uri: &str| {
            let (app, cookie, uri) = (app.clone(), cookie.clone(), uri.to_string());
            async move {
                let resp = app
                    .oneshot(
                        Request::builder()
                            .uri(uri)
                            .header(header::COOKIE, cookie)
                            .body(Body::empty())
                            .unwrap(),
                    )
                    .await
                    .unwrap();
                assert_eq!(resp.status(), StatusCode::OK);
                String::from_utf8(
                    axum::body::to_bytes(resp.into_body(), 16 * 1024 * 1024)
                        .await
                        .unwrap()
                        .to_vec(),
                )
                .unwrap()
            }
        };

        // 250 cached + 80 uncached = 330 rows over 4 pages. The pager and the
        // clamp must agree on that, and EVERY page it offers must have content —
        // the original bug advertised a fourth page that clamped back to the
        // third and re-rendered it, still offering the link.
        let p3 = get("/?view=starred&page=3").await;
        assert!(
            p3.contains("Page 3 of 4"),
            "the pager and the clamp disagree on the total: {}",
            p3.split("pager-pos")
                .nth(1)
                .unwrap_or("")
                .chars()
                .take(120)
                .collect::<String>()
        );
        // Page 3 is the boundary: the last 50 cached rows, then the first 50
        // uncached ones.
        assert!(
            p3.contains("Elsewhere 0"),
            "page 3 should start the uncached run"
        );
        assert_eq!(
            p3.matches("<li class=\"entry").count(),
            ENTRIES_PER_PAGE as usize,
            "the boundary page is not full"
        );

        // **The heading, which the previous round broke by deleting this.**
        //
        // `total` includes the uncached records, so the parenthetical is a
        // SUBSET of it, not an addition — "330 entries (80 saved elsewhere)".
        // The version that said "plus N" double counted once `total` started
        // including them, and N had become page-local in the same commit while
        // the template stayed put. It shipped because this assertion was deleted
        // rather than updated.
        {
            let body = &p3;
            assert!(
                body.contains("330 entries"),
                "the heading must count the whole sequence: {}",
                body.split("content-count")
                    .nth(1)
                    .unwrap_or("")
                    .chars()
                    .take(120)
                    .collect::<String>()
            );
            assert!(
                body.contains("(80 saved elsewhere)"),
                "the heading must say how many of the total the cache cannot show, \
                 as a whole-list figure and not a per-page one: {}",
                body.split("content-count")
                    .nth(1)
                    .unwrap_or("")
                    .chars()
                    .take(120)
                    .collect::<String>()
            );
            assert!(
                !body.contains("plus 50") && !body.contains("plus 80"),
                "the heading is adding the uncached rows to a total that already \
                 includes them"
            );
        }

        let p4 = get("/?view=starred&page=4").await;
        assert!(
            p4.contains("Page 4 of 4"),
            "page 4 was advertised but clamps somewhere else — the unreachable-page bug"
        );
        assert_eq!(
            p4.matches("<li class=\"entry").count(),
            30,
            "page 4 should hold the remaining 30 uncached records"
        );
        assert!(
            p4.contains("Elsewhere 79"),
            "the LAST saved record is unreachable — it can only be removed from here"
        );

        // No uncached record appears on two pages.
        assert!(
            !p4.contains("Elsewhere 0"),
            "an uncached record was rendered on more than one page"
        );
        // Page 1 is all cached — and still reports the same whole-list heading,
        // because the parenthetical describes the LIST, not the page.
        let first = get("/?view=starred").await;
        assert!(
            first.contains("330 entries") && first.contains("(80 saved elsewhere)"),
            "the heading changed between pages; it describes the list, not the page"
        );
        assert!(
            !first.contains("Elsewhere "),
            "uncached saved records leaked onto the first page"
        );
    }

    /// **A saved record whose article is not cached here is still shown.**
    ///
    /// The starred view is built from local `entries`, so before this a record
    /// starred in ANOTHER atproto reader — the portability the shared lexicon
    /// exists for — was simply invisible. It now renders from the PDS record,
    /// visually distinct, linking straight out.
    #[tokio::test]
    async fn a_saved_record_with_no_cached_entry_is_shown_as_a_link() {
        let did = "did:plc:ewvi7nxzyoun6zhxrhs64oiz";
        let sidecar =
            spawn_saved_sidecar("https://elsewhere.example/article", "Starred elsewhere").await;
        let mut state = test_state_with_sidecar(&[did], &sidecar).await;
        std::sync::Arc::get_mut(&mut state.config).unwrap().dev_did = Some(did.to_string());

        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri("/?view=starred")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();

        assert!(
            body.contains("Starred elsewhere"),
            "the saved record was not rendered at all"
        );
        assert!(
            body.contains("entry-uncached"),
            "it was not marked as uncached, so it looks like a normal entry"
        );
        assert!(
            body.contains("https://elsewhere.example/article"),
            "the row must link straight to the article"
        );
        assert!(
            !body.contains("/entries/0/"),
            "an uncached row must not offer entry actions against a nonexistent id"
        );
    }

    /// **A PDS `createdAt` must not be able to panic the starred view.**
    ///
    /// `display_date` byte-sliced `p[..10]`. Every prior caller passed a
    /// timestamp the feed parser produced; the saved-record path passes a bare
    /// string off a PDS record, written by whatever client the reader used. A
    /// multi-byte value panicked the handler, and with no catch-panic layer the
    /// view stayed down until the record was removed — from that same view.
    #[test]
    fn a_multibyte_timestamp_does_not_panic_the_date_formatter() {
        for hostile in [
            "日本語日本語日本",
            "é",
            "",
            "2026",
            "🙂🙂🙂🙂🙂🙂🙂🙂🙂🙂🙂",
        ] {
            let out = display_date(Some(hostile));
            assert!(out.chars().count() <= 10, "{hostile:?} -> {out:?}");
        }
        assert_eq!(display_date(Some("2026-01-01T00:00:00Z")), "2026-01-01");
        assert_eq!(display_date(None), "");
    }

    /// Unsaving makes a DPoP-signed PDS round-trip, which is the stated reason
    /// its neighbours are limited. It was added as a route and not added here.
    #[test]
    fn the_unsave_route_is_rate_limited() {
        use axum::http::Method;
        assert!(is_rate_limited_path("/saved/3abc/delete", &Method::POST));
        // And the neighbours still are.
        assert!(is_rate_limited_path("/entries/1/star", &Method::POST));
    }

    /// **The probe detects a broken database — asserted through `/health`
    /// itself, not through a string.**
    ///
    /// A named constant did not bind the handler: it stayed free to call
    /// `query_scalar` with a different literal, so degrading the real probe to
    /// `SELECT 1` shipped green twice over. This drops the table the probe reads
    /// and asserts the endpoint stops saying `ok` — behaviour no substituted SQL
    /// can fake, because `SELECT 1` still succeeds against a wrecked schema.
    #[tokio::test]
    async fn health_reports_a_broken_database() {
        let state = test_state(&[]).await;
        // Sanity: healthy first, so the assertion below is about the damage.
        assert!(
            health_db_probe(&state.db).await.is_ok(),
            "the fixture was not healthy to begin with",
        );

        sqlx::query("DROP TABLE feeds")
            .execute(&state.db)
            .await
            .unwrap();

        assert!(
            health_db_probe(&state.db).await.is_err(),
            "the probe reported success against a database missing the table it \
             claims to read; `SELECT 1` would do exactly this",
        );

        let resp = router(state)
            .oneshot(
                Request::builder()
                    .uri("/health")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        let body = String::from_utf8(
            axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap()
                .to_vec(),
        )
        .unwrap();
        // The documented contract: the FIRST token is the state.
        assert!(
            body.starts_with("FAIL"),
            "/health did not report FAIL for a broken database: {body}",
        );
        assert!(
            !body.contains("db: ok"),
            "/health still called the database ok: {body}",
        );
    }
}