Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
64.2 KB
Raw Blame
//! Mounting orchestration for the `/api/v1` + web-UI HTTP surfaces.
//!
//! The host binary (`ai-memory serve`) splits the JSON API and either the
//! operator's custom SPA (`--web-ui-dir`) or built-in server-rendered wiki,
//! attaches the appropriate public/dual-auth middleware, then merges them.
//! Base-path normalisation and `<base href>` injection live here too so
//! served HTML resolves relative URLs under the configured prefix.

use std::convert::Infallible;
use std::path::Path;
use std::sync::Arc;
use std::time::Duration;

use ai_memory_store::ReaderPool;
use ai_memory_wiki::Wiki;
use anyhow::{Context, Result};
use axum::body::Body;
use axum::extract::State;
use axum::http::{HeaderName, Method, Request, StatusCode, header};
use axum::middleware::Next;
use axum::response::{IntoResponse, Response};
use tower::service_fn;
use tower_http::cors::CorsLayer;
use tower_http::services::ServeDir;
use tracing::info;

/// 10 MB cap on response bodies buffered for `<base href>` injection.
/// Matches the inbound body cap the HTTP server applies; a custom-SPA
/// `index.html` over the cap is misconfigured at the operator level, and
/// refusing here keeps a runaway template (or a hostile asset
/// masquerading as text/html) from streaming unbounded into memory
/// before injection.
const MAX_INJECT_BODY_BYTES: usize = 10 * 1024 * 1024;

/// Normalise an operator-supplied path prefix into either `""` (root) or
/// `/<core>` — exactly one leading slash, no trailing slash, internal
/// empty/`//` segments collapsed.
///
/// Each segment must be a non-trivial member of the RFC 3986 *unreserved*
/// set (`ALPHA / DIGIT / "-" / "." / "_" / "~"`). Dot-segments `.` and
/// `..` are rejected outright even though their characters are unreserved
/// — at the segment level they re-encode "current directory" and "parent
/// directory" and would let a malformed env var hand the operator a
/// traversal vector through every URL the server emits.
///
/// Anything that falls outside the rule collapses to `""` (root) so a
/// bad env var can never inject markup or a protocol-relative `//` into
/// served HTML.
pub fn normalize_prefix(raw: &str) -> String {
    let segs: Vec<&str> = raw.trim().split('/').filter(|s| !s.is_empty()).collect();
    if segs.is_empty() {
        return String::new();
    }
    let safe = segs.iter().all(|s| {
        // Reject dot-segments (`.` / `..`) — they pass the per-char
        // unreserved test but mean "current" / "parent" at the segment
        // boundary and turn `/<base>` into `/<base>/..` traversal.
        *s != "." && *s != ".." && s.chars().all(is_unreserved_url_char)
    });
    if !safe {
        return String::new();
    }
    format!("/{}", segs.join("/"))
}

/// RFC 3986 `unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"`. Kept
/// here as a single source of truth for both the path-prefix charset
/// check and any future per-segment validation.
fn is_unreserved_url_char(c: char) -> bool {
    c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.' | '~')
}

/// Build the `<base href>` value (always trailing-slash-terminated, never
/// the protocol-relative `//`) for the web UI mounted at `base_path` +
/// `web_slug`.
pub fn web_base_href(base_path: &str, web_slug: &str) -> String {
    let combined = format!(
        "{}{}",
        normalize_prefix(base_path),
        normalize_prefix(web_slug)
    );
    if combined.is_empty() {
        "/".to_string()
    } else {
        format!("{combined}/")
    }
}

/// Escape a string for safe inclusion inside a double-quoted HTML attribute.
fn escape_attr(s: &str) -> String {
    s.replace('&', "&amp;")
        .replace('"', "&quot;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
}

/// Insert `snippet` immediately after the first `<head…>` tag (or prepend
/// it when there is no head).
///
/// Matches outside HTML comments only: `<!-- … <head … --> <head>` skips
/// the comment-internal occurrence and injects after the real `<head>`.
/// Anything inside `<textarea>`, `<script>`, or other raw-text elements
/// is NOT specially handled — built-in askama templates never put
/// `<head` in those, and a custom `--web-ui-dir` SPA that does is a
/// misconfiguration the operator can fix at the source. Avoiding a
/// full HTML parser here keeps injection a single pass + alloc.
fn inject_into_head(html: &str, snippet: &str) -> String {
    let bytes = html.as_bytes();
    let mut cursor = 0usize;
    while cursor < bytes.len() {
        // Skip past any HTML comment opening here so a `<head` literal
        // sitting inside it cannot win the search.
        if html[cursor..].starts_with("<!--") {
            match html[cursor..].find("-->") {
                Some(end) => cursor += end + 3,
                None => break, // Unterminated comment — bail out of injection.
            }
            continue;
        }
        if html[cursor..].starts_with("<head")
            && let Some(gt) = html[cursor..].find('>')
        {
            let pos = cursor + gt + 1;
            let mut out = String::with_capacity(html.len() + snippet.len());
            out.push_str(&html[..pos]);
            out.push_str(snippet);
            out.push_str(&html[pos..]);
            return out;
        }
        // Step a whole character: slicing `html[cursor..]` inside a
        // multi-byte one (a UTF-8 BOM, an accented attribute value) panics.
        cursor += html[cursor..].chars().next().map_or(1, char::len_utf8);
    }
    format!("{snippet}{html}")
}

/// Inject `<base href="{href}">` so the served SPA's relative asset/router
/// URLs resolve under the configured prefix.
pub fn inject_base_href(html: &str, href: &str) -> String {
    inject_into_head(html, &format!("<base href=\"{}\">", escape_attr(href)))
}

/// Inject `<meta name="ai-memory-base-path" content="{base_path}">` so the
/// SPA can build API URLs as `{base_path}/api/v1`. The `<base href>` alone is
/// ambiguous for this because it also folds in the web slug (e.g. `/web`),
/// whereas `/api/v1` hangs off the base path, not the web mount.
pub fn inject_base_path_meta(html: &str, base_path: &str) -> String {
    inject_into_head(
        html,
        &format!(
            "<meta name=\"ai-memory-base-path\" content=\"{}\">",
            escape_attr(base_path)
        ),
    )
}

#[cfg(test)]
mod web_base_tests {
    use super::{inject_base_href, inject_base_path_meta, normalize_prefix, web_base_href};

    #[test]
    fn normalize_prefix_edge_cases() {
        assert_eq!(normalize_prefix(""), "");
        assert_eq!(normalize_prefix("/"), "");
        assert_eq!(normalize_prefix("//"), "");
        assert_eq!(normalize_prefix("  /  "), "");
        assert_eq!(normalize_prefix("wiki"), "/wiki");
        assert_eq!(normalize_prefix("/wiki"), "/wiki");
        assert_eq!(normalize_prefix("/wiki/"), "/wiki");
        assert_eq!(normalize_prefix("//wiki//"), "/wiki");
        assert_eq!(normalize_prefix("/wiki/sub"), "/wiki/sub");
        // Unsafe chars fall back to root — never inject markup or `//`.
        assert_eq!(normalize_prefix("/wi\"ki"), "");
        assert_eq!(normalize_prefix("/wiki space"), "");
        assert_eq!(normalize_prefix("/<script>"), "");
    }

    /// Dot-segments must NOT survive normalisation. Their characters
    /// pass the unreserved per-char allowlist (`.` is unreserved), so
    /// the segment-level rejection is what stops `/..` and `/.` from
    /// turning the base prefix into a traversal vector. Regression
    /// guard — without this, `AI_MEMORY_BASE_PATH=/..` would serve
    /// `/..` and let an upstream redirect normalise it to `/`.
    #[test]
    fn normalize_prefix_rejects_dot_segments() {
        assert_eq!(normalize_prefix("/.."), "", "/.. must collapse to root");
        assert_eq!(normalize_prefix("/."), "", "/. must collapse to root");
        assert_eq!(
            normalize_prefix("/wiki/.."),
            "",
            "any embedded /.. fails the whole prefix"
        );
        assert_eq!(
            normalize_prefix("/wiki/./sub"),
            "",
            "any embedded /. fails the whole prefix"
        );
        // Segments that merely START with a dot but aren't pure
        // dot-segments are still valid (RFC 3986 unreserved chars).
        assert_eq!(normalize_prefix("/.wellknown"), "/.wellknown");
    }

    /// Nested base paths (`/a/b/c`) are valid; the normaliser keeps the
    /// hierarchy intact instead of collapsing to one level.
    #[test]
    fn normalize_prefix_keeps_nested_paths() {
        assert_eq!(normalize_prefix("/a/b/c"), "/a/b/c");
        assert_eq!(normalize_prefix("a/b/c"), "/a/b/c");
        assert_eq!(normalize_prefix("//a//b//c//"), "/a/b/c");
        assert_eq!(normalize_prefix("/a/b/c/d/e"), "/a/b/c/d/e");
    }

    /// `inject_into_head` must skip `<head` literals sitting inside an
    /// HTML comment, otherwise a custom SPA whose `index.html` had a
    /// `<!-- <head> placeholder -->` comment would have the snippet
    /// injected at the wrong place.
    #[test]
    fn inject_base_href_skips_head_inside_html_comment() {
        let html =
            "<!-- <head fake --><html><head><meta charset=\"utf-8\"></head><body></body></html>";
        let out = inject_base_href(html, "/w/");
        // Snippet must follow the REAL <head>, not the commented one —
        // the comment must remain unmodified.
        assert!(out.contains("<!-- <head fake -->"));
        assert!(out.contains("<head><base href=\"/w/\"><meta"));
    }

    /// `inject_into_head` falls back to the prepend path on an
    /// unterminated comment instead of looping forever (defensive).
    #[test]
    fn inject_base_href_on_unterminated_comment_falls_back_to_prepend() {
        let html = "<!-- never closes <head>";
        let out = inject_base_href(html, "/w/");
        assert!(out.starts_with("<base href=\"/w/\">"));
    }

    #[test]
    fn web_base_href_never_protocol_relative() {
        assert_eq!(web_base_href("", "/web"), "/web/");
        assert_eq!(web_base_href("/wiki", "/web"), "/wiki/web/");
        assert_eq!(web_base_href("/wiki", "/"), "/wiki/");
        assert_eq!(web_base_href("", "/"), "/");
        assert_eq!(web_base_href("/", "/"), "/");
        assert_eq!(web_base_href("/wiki/", "web"), "/wiki/web/");
        for (b, s) in [("", "/"), ("/", "/"), ("//", "//")] {
            assert!(!web_base_href(b, s).starts_with("//"));
        }
    }

    #[test]
    fn inject_base_href_after_head() {
        let html = "<!doctype html><html><head><meta charset=\"utf-8\"></head><body></body></html>";
        let out = inject_base_href(html, "/wiki/web/");
        assert!(out.contains("<head><base href=\"/wiki/web/\"><meta"));
    }

    /// The scan walks the page byte by byte, and slicing inside a multi-byte
    /// character panics. A custom SPA `index.html` saved with a UTF-8 BOM,
    /// or with any non-ASCII text before `<head>`, took `serve
    /// --web-ui-dir` down at startup.
    #[test]
    fn inject_base_href_steps_over_non_ascii_before_head() {
        let bom = "\u{feff}<!doctype html><html><head><meta charset=\"utf-8\"></head></html>";
        let out = inject_base_href(bom, "/w/");
        assert!(out.starts_with('\u{feff}'), "the BOM stays where it was");
        assert!(out.contains("<head><base href=\"/w/\"><meta"));

        let accent = "<html data-app=\"Mémoire\"><head></head></html>";
        assert!(inject_base_href(accent, "/w/").contains("<head><base href=\"/w/\"></head>"));
    }

    #[test]
    fn inject_base_href_no_head_prepends() {
        let out = inject_base_href("<html></html>", "/x/");
        assert!(out.starts_with("<base href=\"/x/\"><html>"));
    }

    #[test]
    fn inject_base_href_escapes_attr() {
        let out = inject_base_href("<head></head>", "/a\"b/");
        assert!(out.contains("<base href=\"/a&quot;b/\">"));
    }

    #[test]
    fn inject_base_path_meta_emits_meta() {
        let out = inject_base_path_meta("<head></head>", "/wiki");
        assert!(out.contains("<meta name=\"ai-memory-base-path\" content=\"/wiki\">"));
        // Empty base path => empty content (SPA falls back to root).
        let empty = inject_base_path_meta("<head></head>", "");
        assert!(empty.contains("content=\"\""));
    }
}

/// Path / URL config the web mount needs. Bundling these together keeps
/// [`split_web_routers`] below clippy's `too_many_arguments` threshold
/// without hiding the call shape.
pub struct WebMountSpec<'a> {
    /// Mount `/api/v1` even when the browser UI is disabled. The browser UI
    /// always implies the API for backward compatibility.
    pub enable_api: bool,
    /// Operator-supplied custom SPA directory (`--web-ui-dir`). `None`
    /// mounts the built-in server-rendered wiki browser instead.
    pub web_ui_dir: Option<&'a Path>,
    /// Pre-validated CORS origins scoped to `/api/v1` only.
    pub cors_origins: &'a [String],
    /// Raw `--web-slug` value; normalised internally by the mount.
    pub web_slug: &'a str,
    /// `<base href>` value (base path + slug, trailing slash) injected
    /// into every served HTML page.
    pub base_href: &'a str,
    /// Normalised base path (`""` or `/<core>`) the whole surface is
    /// nested under; stamped into the `ai-memory-base-path` meta tag.
    pub base_path: &'a str,
    /// A trusted identity proxy is configured; the root-only pending-writes
    /// page needs it to decide whether operators are told apart.
    pub trusted_proxy_identity: bool,
    /// The server's configured embedder and reranker, so project search in
    /// `/web` and `/api/v1` ranks like `memory_query`.
    pub recall: crate::Recall,
    /// Safe configuration switches read once by the host.
    pub runtime: Option<crate::features::RuntimeFeatures>,
    /// Process-side sources for the root-only health page.
    pub health: Option<Arc<crate::health::HealthSources>>,
}

/// Public SPA vs dual-auth wiki/API split.
///
/// Custom `--web-ui-dir` shells are public (session login lives in the SPA).
/// Builtin wiki pages and `/api/v1` are dual-auth.
pub struct SplitWebRouters {
    /// Unauthenticated custom SPA (empty when builtin wiki is mounted).
    pub public: axum::Router,
    /// `/api/v1` plus the builtin wiki when that is the chosen UI.
    pub protected: axum::Router,
    /// Builtin login / change-password redirect targets. `None` when web is
    /// disabled or a custom SPA is mounted (no builtin auth pages).
    pub html_auth: Option<Arc<crate::HtmlAuthRedirectConfig>>,
}

/// Refuse to be framed by any page. With auth off, a page inside an iframe
/// makes same-origin requests the cross-origin guard rightly allows, so a
/// foreign site could frame `/web/pending` and trick a click on Approve or
/// Reject. Set only when a handler has not chosen its own value.
async fn deny_framing(mut response: axum::response::Response) -> axum::response::Response {
    use axum::http::{HeaderValue, header};
    let headers = response.headers_mut();
    headers
        .entry(header::X_FRAME_OPTIONS)
        .or_insert(HeaderValue::from_static("DENY"));
    headers
        .entry(header::CONTENT_SECURITY_POLICY)
        .or_insert(HeaderValue::from_static("frame-ancestors 'none'"));
    response
}

/// Split the web surfaces so the host can attach different auth layers.
/// Every web surface refuses framing (see [`deny_framing`]).
///
/// # Errors
/// Custom SPA `index.html` cannot be read.
pub fn split_web_routers(
    enable_web: bool,
    reader: ReaderPool,
    wiki: Wiki,
    spec: WebMountSpec<'_>,
) -> Result<SplitWebRouters> {
    split_web_routers_with_metrics(enable_web, reader, wiki, None, spec)
}

/// Metric-aware variant of [`split_web_routers`]. The optional input keeps
/// the web crate embeddable without coupling custom frontends to hook state.
pub fn split_web_routers_with_metrics(
    enable_web: bool,
    reader: ReaderPool,
    wiki: Wiki,
    ingest_metrics: Option<Arc<ai_memory_core::IngestMetrics>>,
    spec: WebMountSpec<'_>,
) -> Result<SplitWebRouters> {
    let split = split_web_routers_unframed(enable_web, reader, wiki, ingest_metrics, spec)?;
    let layer = || axum::middleware::map_response(deny_framing);
    Ok(SplitWebRouters {
        public: split.public.layer(layer()),
        protected: split.protected.layer(layer()),
        html_auth: split.html_auth,
    })
}

fn split_web_routers_unframed(
    enable_web: bool,
    reader: ReaderPool,
    wiki: Wiki,
    ingest_metrics: Option<Arc<ai_memory_core::IngestMetrics>>,
    spec: WebMountSpec<'_>,
) -> Result<SplitWebRouters> {
    if !enable_web && !spec.enable_api {
        return Ok(SplitWebRouters {
            public: axum::Router::new(),
            protected: axum::Router::new(),
            html_auth: None,
        });
    }
    let mut state = crate::WebState::new(reader, wiki)
        .with_trusted_proxy_identity(spec.trusted_proxy_identity)
        .with_recall(spec.recall)
        .with_runtime(spec.runtime);
    if let Some(health) = spec.health {
        state = state.with_health(health);
    }
    if let Some(metrics) = ingest_metrics {
        state = state.with_ingest_metrics(metrics);
    }
    let api = build_api_router(state.clone(), spec.cors_origins);
    let protected_api = axum::Router::new().nest("/api/v1", api);
    if !enable_web {
        return Ok(SplitWebRouters {
            public: axum::Router::new(),
            protected: protected_api,
            html_auth: None,
        });
    }
    let slug = normalize_prefix(spec.web_slug);
    let mount = if slug.is_empty() { "/" } else { slug.as_str() };
    if let Some(dir) = spec.web_ui_dir {
        let public = mount_custom_spa(
            axum::Router::new(),
            dir,
            &slug,
            spec.base_href,
            spec.base_path,
            mount,
        )?;
        return Ok(SplitWebRouters {
            public,
            protected: protected_api,
            html_auth: None,
        });
    }
    let auth_cfg = Arc::new(crate::HtmlAuthRedirectConfig::from_mount(
        spec.base_path,
        spec.web_slug,
    ));
    let browser_inject = Arc::new(WebInjectState {
        base_href: spec.base_href.to_string(),
        base_path: spec.base_path.to_string(),
        login_path: auth_cfg.login_path.clone(),
    });
    Ok(SplitWebRouters {
        public: mount_builtin_public(
            auth_cfg.clone(),
            &slug,
            spec.base_href,
            spec.base_path,
            mount,
        ),
        protected: mount_builtin_browser(protected_api, state, &slug, mount, browser_inject),
        html_auth: Some(auth_cfg),
    })
}

/// Test-only composition helper. Production must attach distinct auth
/// middleware to [`SplitWebRouters::public`] and
/// [`SplitWebRouters::protected`] before merging them.
#[cfg(test)]
fn mount_web_router(
    router: axum::Router,
    enable_web: bool,
    reader: ReaderPool,
    wiki: Wiki,
    spec: WebMountSpec<'_>,
) -> Result<axum::Router> {
    let split = split_web_routers(enable_web, reader, wiki, spec)?;
    Ok(router.merge(split.protected).merge(split.public))
}

/// Build the `/api/v1` router and apply the per-origin CORS layer if
/// the operator configured any. The layer is scoped to this router only
/// (CORS_NOT_APPLIED_TO_OTHER_ROUTES invariant — `/mcp`, `/hook`,
/// `/admin`, and `/web` must remain CORS-free).
fn build_api_router(state: crate::WebState, cors_origins: &[String]) -> axum::Router {
    let api = crate::routes::build_api(Arc::new(state));
    if cors_origins.is_empty() {
        return api;
    }
    // Origins were already validated before binding, so parsing here
    // is expected to succeed; `.expect` surfaces a logic bug if it does not.
    let parsed: Vec<axum::http::HeaderValue> = cors_origins
        .iter()
        .map(|o| o.parse().expect("pre-validated origin must parse"))
        .collect();
    let cors = CorsLayer::new()
        .allow_origin(parsed)
        .allow_methods([Method::GET, Method::POST, Method::OPTIONS])
        .allow_headers([
            header::AUTHORIZATION,
            header::CONTENT_TYPE,
            HeaderName::from_static("x-csrf-token"),
        ])
        .allow_credentials(true)
        .max_age(Duration::from_secs(600));
    info!(origins = ?cors_origins, "CORS layer attached to /api/v1");
    api.layer(cors)
}

/// Mount the operator's custom SPA from `--web-ui-dir`. Reads
/// `index.html`, injects `<base href>` plus the `ai-memory-base-path`
/// meta, and serves the rest as static assets with an SPA fallback to
/// the injected shell. Errors surface as `anyhow` with the dir path.
fn mount_custom_spa(
    router: axum::Router,
    dir: &Path,
    slug: &str,
    base_href: &str,
    base_path: &str,
    mount: &str,
) -> Result<axum::Router> {
    let dir = dir.to_path_buf();
    let raw = std::fs::read_to_string(dir.join("index.html"))
        .with_context(|| format!("reading custom web UI index at {}", dir.display()))?;
    let injected = inject_base_path_meta(&inject_base_href(&raw, base_href), base_path);
    info!(mount, base_href, base_path, "custom web UI mounted");
    let spa = custom_spa_router(dir, injected.clone());
    Ok(if slug.is_empty() {
        router.merge(spa)
    } else {
        // `nest(slug, …)` routes `{slug}` (→ inner `/`) and `{slug}/<path>`
        // (→ inner `/{*path}`), but NOT the bare trailing-slash root
        // `{slug}/` — that empty sub-path matches neither, so it 404s. The
        // SPA router normalises its home to exactly that URL, so a refresh on
        // the app root returned a hard 404 (`custom_spa_trailing_slash_root_*`).
        // Serve the injected shell there too. Unlike the builtin browser —
        // which redirects `{slug}/` → `{slug}` — a SPA is happier staying put
        // on a 200 than bouncing through a redirect on every root refresh.
        let slash_index = Arc::new(injected);
        router
            .route(
                &format!("{slug}/"),
                axum::routing::get(move || {
                    let body = slash_index.clone();
                    async move { axum::response::Html((*body).clone()) }
                }),
            )
            .nest(slug, spa)
    })
}

/// Mount public builtin auth pages + static assets at `slug`.
fn mount_builtin_public(
    auth_cfg: Arc<crate::HtmlAuthRedirectConfig>,
    slug: &str,
    base_href: &str,
    base_path: &str,
    mount: &str,
) -> axum::Router {
    let inject = Arc::new(WebInjectState {
        base_href: base_href.to_string(),
        base_path: base_path.to_string(),
        login_path: auth_cfg.login_path.clone(),
    });
    let public = crate::routes::build_public_auth(auth_cfg).layer(
        axum::middleware::from_fn_with_state(inject, inject_web_base_href),
    );
    info!(mount, base_href, "builtin public auth pages mounted");
    if slug.is_empty() {
        public
    } else {
        axum::Router::new().nest(slug, public)
    }
}

/// Mount the built-in server-rendered wiki browser at `slug` with
/// `<base href>` injection middleware. When `slug` is non-empty also
/// register the trailing-slash → canonical redirect, preserving any
/// query string the caller passed.
fn mount_builtin_browser(
    router: axum::Router,
    state: crate::WebState,
    slug: &str,
    mount: &str,
    inject: Arc<WebInjectState>,
) -> axum::Router {
    // The built-in browser emits RELATIVE asset/link URLs (`static/…`,
    // `w/…`, `search`, `.`). Inject a `<base href>` into every HTML
    // response so they resolve under `{base_path}{web_slug}/` — the
    // same anchoring the custom SPA gets via its injected index.
    let base_href = inject.base_href.clone();
    let web_router = crate::routes::build(Arc::new(state)).layer(
        axum::middleware::from_fn_with_state(inject, inject_web_base_href),
    );
    info!(mount, base_href, "read-only wiki browser mounted");
    if slug.is_empty() {
        return router.merge(web_router);
    }
    // Strip-trailing-slash redirect. The target must carry the full
    // external prefix because the surrounding `nest(&base_path, …)`
    // does NOT rewrite Location headers. Derive it from base_href
    // (which already folds in base_path + slug). The closure takes
    // `Uri` so `?q=x` survives — see
    // `trailing_slash_redirect_preserves_query_string`.
    let canonical = {
        let trimmed = base_href.trim_end_matches('/');
        if trimmed.is_empty() {
            "/".to_string()
        } else {
            trimmed.to_string()
        }
    };
    router
        .route(
            &format!("{slug}/"),
            axum::routing::get(move |uri: axum::http::Uri| {
                let to = match uri.query() {
                    Some(q) if !q.is_empty() => format!("{canonical}?{q}"),
                    _ => canonical.clone(),
                };
                async move { axum::response::Redirect::permanent(&to) }
            }),
        )
        .nest(slug, web_router)
}

fn custom_spa_router(dir: std::path::PathBuf, injected_index: String) -> axum::Router {
    let index = Arc::new(injected_index);
    let root_index = index.clone();
    let direct_index = index.clone();
    let fallback_index = index.clone();

    // Assets are served as files; any missing asset path falls back to the
    // injected index for SPA client routes. Direct `/index.html` is routed
    // explicitly so it cannot bypass injection by being served from disk.
    let assets = ServeDir::new(dir)
        .append_index_html_on_directories(false)
        .fallback(service_fn(move |_req: Request<Body>| {
            let body = fallback_index.clone();
            async move {
                Ok::<_, Infallible>(axum::response::Html((*body).clone()).into_response())
            }
        }));

    axum::Router::new()
        .route(
            "/",
            axum::routing::get(move || {
                let body = root_index.clone();
                async move { axum::response::Html((*body).clone()) }
            }),
        )
        .route(
            "/index.html",
            axum::routing::get(move || {
                let body = direct_index.clone();
                async move { axum::response::Html((*body).clone()) }
            }),
        )
        .route_service("/{*path}", assets)
}

/// Values injected into every builtin HTML response.
struct WebInjectState {
    base_href: String,
    base_path: String,
    login_path: String,
}

/// Response middleware: inject `<base href>` plus auth meta tags into
/// `text/html` responses from the built-in browser / auth pages, so
/// relative URLs and logout/login fetch paths resolve under the
/// configured prefix. Non-HTML responses (static assets, redirects)
/// pass through untouched.
async fn inject_web_base_href(
    State(inject): State<Arc<WebInjectState>>,
    req: Request<Body>,
    next: Next,
) -> Response {
    let resp = next.run(req).await;
    let is_html = resp
        .headers()
        .get(header::CONTENT_TYPE)
        .and_then(|v| v.to_str().ok())
        .is_some_and(|ct| ct.starts_with("text/html"));
    if !is_html {
        return resp;
    }
    let (mut parts, body) = resp.into_parts();
    // Bound the buffer at MAX_INJECT_BODY_BYTES — same cap inbound bodies use.
    // A custom-SPA `index.html` over the cap is misconfigured at the
    // operator level; refusing here keeps a runaway template (or a
    // hostile asset masquerading as text/html) from streaming
    // unbounded into memory before injection.
    let bytes = match axum::body::to_bytes(body, MAX_INJECT_BODY_BYTES).await {
        Ok(b) => b,
        Err(_) => {
            return (
                StatusCode::INTERNAL_SERVER_ERROR,
                "response body too large or read error\n",
            )
                .into_response();
        }
    };
    match std::str::from_utf8(&bytes) {
        Ok(html) => {
            let with_base = inject_base_href(html, &inject.base_href);
            let with_path = inject_base_path_meta(&with_base, &inject.base_path);
            let injected = inject_into_head(
                &with_path,
                &format!(
                    "<meta name=\"ai-memory-login-path\" content=\"{}\">",
                    escape_attr(&inject.login_path)
                ),
            );
            // Stale length from the pre-injection body; let hyper recompute.
            parts.headers.remove(header::CONTENT_LENGTH);
            Response::from_parts(parts, Body::from(injected))
        }
        Err(_) => Response::from_parts(parts, Body::from(bytes)),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use ai_memory_store::Store;
    use tempfile::TempDir;
    use tower::ServiceExt;
    /// Assemble the web/API surface under `base_path` + `web_slug` exactly the
    /// way the `serve` handler does (mount, then `nest(&base_path, …)`), with
    /// no auth/host layers so tests probe routing + injection in isolation.
    /// Returns the `TempDir` guard too — the caller must keep it alive for the
    /// router's lifetime (the store's SQLite + wiki files live under it).
    fn based_web_router(base_path: &str, web_slug: &str) -> (TempDir, axum::Router) {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let base = normalize_prefix(base_path);
        let base_href = web_base_href(base_path, web_slug);
        let router = mount_web_router(
            axum::Router::new(),
            true,
            store.reader.clone(),
            wiki,
            WebMountSpec {
                enable_api: false,
                web_ui_dir: None,
                cors_origins: &[],
                web_slug,
                base_href: &base_href,
                base_path: &base,
                trusted_proxy_identity: false,
                recall: crate::Recall::default(),
                runtime: None,
                health: None,
            },
        )
        .unwrap();
        let router = if base.is_empty() {
            router
        } else {
            axum::Router::new().nest(&base, router)
        };
        // Mirror the production favicon mount in serve handler: at the
        // absolute host root, outside the base-path nest.
        let router = router.merge(crate::favicon_router());
        (tmp, router)
    }

    /// The homepage shows the pre-migration backup notice while the
    /// archive exists, and drops it once the archive is deleted
    /// (docs/okf.md).
    /// 2.0.1: the always-on backup banner is gone — the migration
    /// dialog is the single carrier of the archive path and restore
    /// pointer (and `ai-memory status` keeps the durable reminder).
    #[tokio::test]
    async fn homepage_has_no_backup_banner_and_dialog_carries_the_archive() {
        let (tmp, router) = based_web_router("", "/web");

        async fn body_of(router: &axum::Router) -> String {
            let resp = router
                .clone()
                .oneshot(Request::builder().uri("/web").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();
            String::from_utf8(bytes.to_vec()).unwrap()
        }

        // No receipt: neither banner nor dialog.
        let body = body_of(&router).await;
        assert!(!body.contains("pre-migration backup of your memory"));
        assert!(!body.contains("okf-dialog-overlay"));

        // Receipt + archive present: still no banner — the dialog holds
        // the archive path and the restore pointer instead.
        let archive = tmp.path().join("fake-archive.tar.gz");
        std::fs::write(&archive, b"gz").unwrap();
        let receipt = ai_memory_wiki::backup::BackupReceipt {
            archive_path: archive.clone(),
            size_bytes: 2,
            entries: 1,
            created_at: "2026-09-01T00:00:00Z".into(),
            label: "okf-v0.2".into(),
            dest_free_bytes: None,
        };
        std::fs::write(
            tmp.path().join(ai_memory_wiki::backup::BACKUP_RECEIPT_FILE),
            serde_json::to_vec(&receipt).unwrap(),
        )
        .unwrap();
        let body = body_of(&router).await;
        assert!(
            !body.contains("pre-migration backup of your memory"),
            "the redundant banner must never render"
        );
        assert!(body.contains("okf-dialog-overlay"), "dialog missing");
        assert!(body.contains("fake-archive.tar.gz"), "archive path missing");
        assert!(body.contains("MIGRATION-2.0.md"), "restore pointer missing");
    }

    /// The one-time 2.0 explainer dialog renders whenever a migration
    /// receipt exists — with recovery steps while the archive is
    /// present, with the git-checkpoint fallback after it was deleted —
    /// keyed for per-browser "do not show me again" dismissal.
    #[tokio::test]
    async fn homepage_migration_dialog_adapts_to_the_archive() {
        let (tmp, router) = based_web_router("", "/web");

        async fn body_of(router: &axum::Router) -> String {
            let resp = router
                .clone()
                .oneshot(Request::builder().uri("/web").body(Body::empty()).unwrap())
                .await
                .unwrap();
            let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap();
            String::from_utf8(bytes.to_vec()).unwrap()
        }

        // No receipt → no dialog at all.
        assert!(!body_of(&router).await.contains("okf-dialog-overlay"));

        let archive = tmp.path().join("fake-archive.tar.gz");
        std::fs::write(&archive, b"gz").unwrap();
        let receipt = ai_memory_wiki::backup::BackupReceipt {
            archive_path: archive.clone(),
            size_bytes: 2,
            entries: 1,
            created_at: "2026-09-01T00:00:00Z".into(),
            label: "okf-v0.2".into(),
            dest_free_bytes: None,
        };
        std::fs::write(
            tmp.path().join(ai_memory_wiki::backup::BACKUP_RECEIPT_FILE),
            serde_json::to_vec(&receipt).unwrap(),
        )
        .unwrap();

        // Archive present → dialog with restore steps + dismissal key.
        let body = body_of(&router).await;
        assert!(body.contains("okf-dialog-overlay"));
        assert!(body.contains("upgraded to the 2.0 format"));
        assert!(body.contains("Do not show me again"));
        assert!(
            body.contains("ai-memory-okf-dialog-2026-09-01T00:00:00Z"),
            "dismissal key must be migration-stamped"
        );
        assert!(body.contains("Unpack the archive"));
        // Keyboard contract for the aria-modal dialog.
        assert!(
            body.contains(r#"id="okf-dialog-close" type="button""#),
            "close button must not default to submit"
        );
        assert!(body.contains("\"Escape\"") && body.contains("keydown"));
        assert!(body.contains("closeBtn.focus()"), "dialog must take focus");
        assert!(
            body.contains("!e.shiftKey && active === closeBtn"),
            "Tab from the last control must wrap to the first"
        );

        // Archive deleted → dialog still explains, recovery falls back
        // to the git checkpoint; the inline banner is gone.
        std::fs::remove_file(&archive).unwrap();
        let body = body_of(&router).await;
        assert!(body.contains("okf-dialog-overlay"));
        assert!(body.contains("pre-okf-migration checkpoint"));
        assert!(!body.contains("pre-migration backup of your memory"));
    }

    #[tokio::test]
    async fn base_path_nests_all_surfaces_and_root_404s() {
        let (_tmp, router) = based_web_router("/wiki", "/web");

        // The web UI is reachable UNDER the prefix…
        let under = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/wiki/web")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(under.status(), StatusCode::OK);

        // …and the API too.
        let api = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/wiki/api/v1/projects")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(api.status(), StatusCode::OK);

        // The same paths at the host ROOT must 404 — nothing leaks outside the
        // prefix (the whole point of base-path hosting behind a shared proxy).
        for uri in ["/web", "/api/v1/projects"] {
            let root = router
                .clone()
                .oneshot(Request::builder().uri(uri).body(Body::empty()).unwrap())
                .await
                .unwrap();
            assert_eq!(
                root.status(),
                StatusCode::NOT_FOUND,
                "{uri} must 404 at root"
            );
        }
    }

    #[tokio::test]
    async fn inject_web_base_href_targets_html_only() {
        let (_tmp, router) = based_web_router("/wiki", "/web");

        // HTML response carries the injected <base href> under the prefix.
        let html_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/wiki/web")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(html_resp.status(), StatusCode::OK);
        let html = axum::body::to_bytes(html_resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let html = std::str::from_utf8(&html).unwrap();
        assert!(
            html.contains(r#"<base href="/wiki/web/">"#),
            "expected injected base href, got: {html}"
        );

        // A non-HTML asset passes through untouched (no <base> smuggled in).
        let css_resp = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/wiki/web/static/tailwind.css")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(css_resp.status(), StatusCode::OK);
        let css = axum::body::to_bytes(css_resp.into_body(), usize::MAX)
            .await
            .unwrap();
        assert!(
            !std::str::from_utf8(&css).unwrap().contains("<base href"),
            "non-HTML asset must not receive a <base href> injection"
        );
    }

    #[tokio::test]
    async fn trailing_slash_redirect_carries_the_prefix() {
        let (_tmp, router) = based_web_router("/wiki", "/web");
        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/wiki/web/")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::PERMANENT_REDIRECT);
        // Location must include the external prefix — the surrounding base nest
        // does NOT rewrite Location headers, so a bare `/web` would drop `/wiki`.
        assert_eq!(resp.headers().get(header::LOCATION).unwrap(), "/wiki/web",);
    }

    /// Trailing-slash redirect must preserve the query string. The
    /// original handler took `()` and silently dropped `?q=x`, so a
    /// link in the SPA that appended a filter param round-tripped to
    /// the canonical URL with the param missing. Fragments are
    /// client-only and never reach the server, so we only assert query.
    #[tokio::test]
    async fn trailing_slash_redirect_preserves_query_string() {
        let (_tmp, router) = based_web_router("/wiki", "/web");
        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/wiki/web/?q=foo&limit=5")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::PERMANENT_REDIRECT);
        assert_eq!(
            resp.headers().get(header::LOCATION).unwrap(),
            "/wiki/web?q=foo&limit=5",
            "redirect must carry the original query, not drop it"
        );
    }

    /// Nested base paths (`/a/b/c`) — exercised by the normaliser
    /// unit test but not previously end-to-end. Routes must be
    /// reachable under the full prefix and 404 at any shorter prefix.
    #[tokio::test]
    async fn nested_base_path_nests_web_and_api() {
        let (_tmp, router) = based_web_router("/a/b/c", "/web");
        // Full nested prefix reaches both surfaces.
        for uri in ["/a/b/c/web", "/a/b/c/api/v1/projects"] {
            let resp = router
                .clone()
                .oneshot(Request::builder().uri(uri).body(Body::empty()).unwrap())
                .await
                .unwrap();
            assert_eq!(
                resp.status(),
                StatusCode::OK,
                "{uri} must reach the surface"
            );
        }
        // A SHORTER prefix (e.g. only /a/b) must NOT leak — the nest is
        // exactly `/a/b/c` and any partial mount is unmapped.
        for uri in ["/a/b/web", "/a/api/v1/projects"] {
            let resp = router
                .clone()
                .oneshot(Request::builder().uri(uri).body(Body::empty()).unwrap())
                .await
                .unwrap();
            assert_eq!(
                resp.status(),
                StatusCode::NOT_FOUND,
                "{uri} must 404 — leaks the prefix otherwise"
            );
        }
    }

    /// Custom-SPA index that already carries its own `<base href>` —
    /// today we prepend another one; HTML5 says the browser honours
    /// the FIRST `<base>` so the injection becomes a silent no-op.
    /// Documented behaviour (see `inject_into_head` doc-comment) but
    /// also exercised here so a future change to "replace existing"
    /// gets noticed by a failing test rather than silently shipping.
    #[test]
    fn inject_base_href_with_existing_base_tag_does_not_replace() {
        let html = "<html><head><base href=\"/old/\"><title>x</title></head></html>";
        let out = inject_base_href(html, "/new/");
        // Injected snippet appears first, the old <base> remains too.
        let new_pos = out.find("<base href=\"/new/\">").expect("new injected");
        let old_pos = out.find("<base href=\"/old/\">").expect("old preserved");
        assert!(
            new_pos < old_pos,
            "injected base must appear before the pre-existing one (browser ignores duplicates after the first)"
        );
    }

    /// Post-merge audit (Phase 7 live test) caught that PR #79's
    /// `/favicon.ico` route was nested inside `/web`, so it lived at
    /// `/web/favicon.ico` and the browser's automatic root fetch always
    /// 404'd. Fix: a separate `favicon_router()` mounted at the absolute
    /// HOST root, outside `--base-path` and outside the `/web` nest.
    /// This test pins both:
    ///   * `/favicon.ico` at the host root returns the PNG.
    ///   * Under `--base-path /wiki`, the favicon STAYS at root —
    ///     browsers fetch `<host>/favicon.ico` regardless of where the
    ///     app is mounted; the route must not move with the prefix.
    #[tokio::test]
    async fn favicon_lives_at_host_root_regardless_of_base_path() {
        for base_path in ["", "/wiki"] {
            let (_tmp, router) = based_web_router(base_path, "/web");
            let resp = router
                .oneshot(
                    Request::builder()
                        .uri("/favicon.ico")
                        .body(Body::empty())
                        .unwrap(),
                )
                .await
                .unwrap();
            assert_eq!(
                resp.status(),
                StatusCode::OK,
                "/favicon.ico must be reachable at host root (base_path={base_path:?})"
            );
            assert_eq!(
                resp.headers()
                    .get(axum::http::header::CONTENT_TYPE)
                    .and_then(|v| v.to_str().ok()),
                Some("image/png"),
            );
        }
    }

    #[tokio::test]
    async fn no_base_path_is_byte_equivalent_at_root() {
        let (_tmp, router) = based_web_router("", "/web");
        let resp = router
            .clone()
            .oneshot(Request::builder().uri("/web").body(Body::empty()).unwrap())
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        assert!(
            std::str::from_utf8(&body)
                .unwrap()
                .contains(r#"<base href="/web/">"#),
            "default mount should inject the root-relative base href"
        );
    }

    #[tokio::test]
    async fn custom_spa_index_routes_are_injected_under_base_path() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let ui = TempDir::new().unwrap();
        std::fs::write(
            ui.path().join("index.html"),
            "<!doctype html><html><head><title>spa</title></head><body>shell</body></html>",
        )
        .unwrap();
        std::fs::write(ui.path().join("app.js"), "console.log('asset');").unwrap();

        let base = normalize_prefix("/wiki");
        let base_href = web_base_href("/wiki", "/web");
        let router = mount_web_router(
            axum::Router::new(),
            true,
            store.reader.clone(),
            wiki,
            WebMountSpec {
                enable_api: false,
                web_ui_dir: Some(ui.path()),
                cors_origins: &[],
                web_slug: "/web",
                base_href: &base_href,
                base_path: &base,
                trusted_proxy_identity: false,
                recall: crate::Recall::default(),
                runtime: None,
                health: None,
            },
        )
        .unwrap();
        let router = axum::Router::new().nest(&base, router);

        for uri in [
            "/wiki/web",
            "/wiki/web/", // trailing-slash root: SPA home after router normalises it
            "/wiki/web/index.html",
            "/wiki/web/client/route",
        ] {
            let resp = router
                .clone()
                .oneshot(Request::builder().uri(uri).body(Body::empty()).unwrap())
                .await
                .unwrap();
            assert_eq!(resp.status(), StatusCode::OK, "{uri}");
            let body = axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap();
            let html = std::str::from_utf8(&body).unwrap();
            assert!(
                html.contains(r#"<base href="/wiki/web/">"#),
                "{uri} must receive injected base href: {html}"
            );
            assert!(
                html.contains(r#"<meta name="ai-memory-base-path" content="/wiki">"#),
                "{uri} must receive injected API base-path meta: {html}"
            );
            assert!(html.contains("shell"), "{uri} returns the SPA shell");
        }

        let asset = router
            .oneshot(
                Request::builder()
                    .uri("/wiki/web/app.js")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(asset.status(), StatusCode::OK);
        let body = axum::body::to_bytes(asset.into_body(), usize::MAX)
            .await
            .unwrap();
        let js = std::str::from_utf8(&body).unwrap();
        assert_eq!(js, "console.log('asset');");
    }

    /// `serve --web-ui-dir` mounts the SPA at startup, so an `index.html`
    /// saved with a UTF-8 BOM (Notepad's "UTF-8 with BOM", Visual Studio's
    /// "UTF-8 with signature") panicked the server before it listened.
    #[tokio::test]
    async fn custom_spa_index_with_a_bom_mounts_and_is_injected() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let ui = TempDir::new().unwrap();
        std::fs::write(
            ui.path().join("index.html"),
            "\u{feff}<!doctype html><html><head><title>spa</title></head><body>shell</body></html>",
        )
        .unwrap();

        let base_href = web_base_href("", "/web");
        let router = mount_web_router(
            axum::Router::new(),
            true,
            store.reader.clone(),
            wiki,
            WebMountSpec {
                enable_api: false,
                web_ui_dir: Some(ui.path()),
                cors_origins: &[],
                web_slug: "/web",
                base_href: &base_href,
                base_path: "",
                trusted_proxy_identity: false,
                recall: crate::Recall::default(),
                runtime: None,
                health: None,
            },
        )
        .unwrap();
        let resp = router
            .oneshot(Request::builder().uri("/web").body(Body::empty()).unwrap())
            .await
            .unwrap();
        assert_eq!(resp.status(), StatusCode::OK);
        let body = axum::body::to_bytes(resp.into_body(), usize::MAX)
            .await
            .unwrap();
        let html = std::str::from_utf8(&body).unwrap();
        assert!(
            html.contains(r#"<base href="/web/"><title>spa</title>"#),
            "the base href belongs in the head: {html}"
        );
    }

    /// Every web surface refuses framing: the built-in pages (the pending
    /// writes page among them), the login page, and the API. A foreign site
    /// that frames `/web/pending` on an auth-off server could otherwise trick
    /// a click on Approve or Reject (GHSA-6mc4-46pr-w82w).
    #[tokio::test]
    async fn web_surfaces_refuse_to_be_framed() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        // A page version and a session, so the history and timeline routes
        // answer 200 rather than an error page.
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        store
            .writer
            .upsert_page(ai_memory_core::NewPage {
                workspace_id: ws,
                project_id: proj,
                path: ai_memory_core::PagePath::new("notes/a.md").unwrap(),
                title: "A".into(),
                body: "a".into(),
                tier: ai_memory_core::Tier::Semantic,
                frontmatter_json: serde_json::json!({}),
                pinned: false,
                links: Vec::new(),
                author_id: None,
                expires_at: None,
                entities: Vec::new(),
                evidence: Vec::new(),
            })
            .await
            .unwrap();
        let session = ai_memory_core::SessionId::new();
        store
            .writer
            .begin_session(ai_memory_core::NewSession {
                occurred_at: None,
                id: session,
                workspace_id: ws,
                project_id: proj,
                agent_kind: ai_memory_core::AgentKind::ClaudeCode,
                cwd: None,
                actor_user: None,
            })
            .await
            .unwrap();
        let base_href = web_base_href("", "/web");
        let router = mount_web_router(
            axum::Router::new(),
            true,
            store.reader.clone(),
            wiki,
            WebMountSpec {
                enable_api: true,
                web_ui_dir: None,
                cors_origins: &[],
                web_slug: "/web",
                base_href: &base_href,
                base_path: "",
                trusted_proxy_identity: false,
                recall: crate::Recall::default(),
                runtime: None,
                health: None,
            },
        )
        .unwrap();
        let session_uri = format!("/web/w/default/scratch/s/{session}");
        for uri in [
            "/web",
            "/web/graph",
            "/web/w/default/scratch/graph",
            "/web/pending",
            "/web/login",
            "/api/v1/projects",
            "/web/w/default/scratch/h/notes/a.md",
            session_uri.as_str(),
            "/api/v1/workspaces/default/projects/scratch/history/notes/a.md",
        ] {
            let resp = router
                .clone()
                .oneshot(Request::builder().uri(uri).body(Body::empty()).unwrap())
                .await
                .unwrap();
            if uri.contains("/h/") || uri.contains("/s/") || uri.contains("/history/") {
                assert_eq!(resp.status(), StatusCode::OK, "{uri}");
            }
            let headers = resp.headers();
            assert_eq!(
                headers.get("x-frame-options").map(|v| v.to_str().unwrap()),
                Some("DENY"),
                "{uri} ({})",
                resp.status()
            );
            assert_eq!(
                headers
                    .get("content-security-policy")
                    .map(|v| v.to_str().unwrap()),
                Some("frame-ancestors 'none'"),
                "{uri}"
            );
        }
    }

    /// Regression for the prod 404: with `base_path=""` (host root) the custom
    /// SPA mounts at slug `/web`. `nest("/web", …)` served `/web` and
    /// `/web/<route>` but left the bare trailing-slash root `/web/` unrouted →
    /// hard 404. The SPA normalises its home to exactly `/web/`, so refreshing
    /// the app root broke (both a host-root deploy and one mounted under a base
    /// path like `/wiki`).
    #[tokio::test]
    async fn custom_spa_trailing_slash_root_serves_shell() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let ui = TempDir::new().unwrap();
        std::fs::write(
            ui.path().join("index.html"),
            "<!doctype html><html><head><title>spa</title></head><body>shell</body></html>",
        )
        .unwrap();

        let base_href = web_base_href("", "/web");
        let router = mount_web_router(
            axum::Router::new(),
            true,
            store.reader.clone(),
            wiki,
            WebMountSpec {
                enable_api: false,
                web_ui_dir: Some(ui.path()),
                cors_origins: &[],
                web_slug: "/web",
                base_href: &base_href,
                base_path: "",
                trusted_proxy_identity: false,
                recall: crate::Recall::default(),
                runtime: None,
                health: None,
            },
        )
        .unwrap();

        // `/web`, the trailing-slash root `/web/`, and a deep client route all
        // serve the injected shell — none may 404.
        for uri in ["/web", "/web/", "/web/projects/x"] {
            let resp = router
                .clone()
                .oneshot(Request::builder().uri(uri).body(Body::empty()).unwrap())
                .await
                .unwrap();
            assert_eq!(
                resp.status(),
                StatusCode::OK,
                "{uri} must serve the SPA shell, not 404"
            );
            let body = axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap();
            let html = std::str::from_utf8(&body).unwrap();
            assert!(
                html.contains("shell"),
                "{uri} returns the SPA shell: {html}"
            );
            assert!(
                html.contains(r#"<base href="/web/">"#),
                "{uri} must receive the injected base href: {html}"
            );
        }
    }

    #[tokio::test]
    async fn custom_spa_root_slug_does_not_shadow_api_routes() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let ui = TempDir::new().unwrap();
        std::fs::write(
            ui.path().join("index.html"),
            "<!doctype html><html><head><title>spa</title></head><body>root shell</body></html>",
        )
        .unwrap();
        std::fs::write(ui.path().join("app.js"), "console.log('root asset');").unwrap();

        let base = normalize_prefix("/wiki");
        let base_href = web_base_href("/wiki", "/");
        let router = mount_web_router(
            axum::Router::new(),
            true,
            store.reader.clone(),
            wiki,
            WebMountSpec {
                enable_api: false,
                web_ui_dir: Some(ui.path()),
                cors_origins: &[],
                web_slug: "/",
                base_href: &base_href,
                base_path: &base,
                trusted_proxy_identity: false,
                recall: crate::Recall::default(),
                runtime: None,
                health: None,
            },
        )
        .unwrap();
        let router = axum::Router::new().nest(&base, router);

        for uri in ["/wiki", "/wiki/index.html", "/wiki/client/route"] {
            let resp = router
                .clone()
                .oneshot(Request::builder().uri(uri).body(Body::empty()).unwrap())
                .await
                .unwrap();
            assert_eq!(resp.status(), StatusCode::OK, "{uri}");
            let body = axum::body::to_bytes(resp.into_body(), usize::MAX)
                .await
                .unwrap();
            let html = std::str::from_utf8(&body).unwrap();
            assert!(
                html.contains(r#"<base href="/wiki/">"#),
                "{uri} must receive injected base href: {html}"
            );
            assert!(
                html.contains(r#"<meta name="ai-memory-base-path" content="/wiki">"#),
                "{uri} must receive injected API base-path meta: {html}"
            );
            assert!(html.contains("root shell"), "{uri} returns the SPA shell");
        }

        let api = router
            .clone()
            .oneshot(
                Request::builder()
                    .uri("/wiki/api/v1/projects")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(api.status(), StatusCode::OK);
        let content_type = api
            .headers()
            .get(header::CONTENT_TYPE)
            .and_then(|h| h.to_str().ok())
            .unwrap_or_default();
        assert!(
            content_type.starts_with("application/json"),
            "API route must not be shadowed by the root SPA: {content_type}"
        );

        let asset = router
            .oneshot(
                Request::builder()
                    .uri("/wiki/app.js")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();
        assert_eq!(asset.status(), StatusCode::OK);
        let body = axum::body::to_bytes(asset.into_body(), usize::MAX)
            .await
            .unwrap();
        let js = std::str::from_utf8(&body).unwrap();
        assert_eq!(js, "console.log('root asset');");
    }
    #[tokio::test]
    async fn cors_layer_on_api_v1_allows_configured_origin() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();

        let cors_origins = ["https://app.example.com".to_string()];
        let router = mount_web_router(
            axum::Router::new(),
            true,
            store.reader.clone(),
            wiki,
            WebMountSpec {
                enable_api: false,
                web_ui_dir: None,
                cors_origins: &cors_origins,
                web_slug: "/web",
                base_href: "/web/",
                base_path: "",
                trusted_proxy_identity: false,
                recall: crate::Recall::default(),
                runtime: None,
                health: None,
            },
        )
        .unwrap();
        // No auth layer so we can reach /api/v1 directly.
        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/api/v1/workspaces")
                    .header("Origin", "https://app.example.com")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(resp.status(), StatusCode::OK);
        let acao = resp
            .headers()
            .get("access-control-allow-origin")
            .expect("ACAO header must be present for allowed origin")
            .to_str()
            .unwrap();
        assert_eq!(acao, "https://app.example.com");
        let acac = resp
            .headers()
            .get("access-control-allow-credentials")
            .expect("ACAC header must be present")
            .to_str()
            .unwrap();
        assert_eq!(acac, "true");
    }

    #[tokio::test]
    async fn cors_layer_on_api_v1_denies_unlisted_origin() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();

        let cors_origins = ["https://app.example.com".to_string()];
        let router = mount_web_router(
            axum::Router::new(),
            true,
            store.reader.clone(),
            wiki,
            WebMountSpec {
                enable_api: false,
                web_ui_dir: None,
                cors_origins: &cors_origins,
                web_slug: "/web",
                base_href: "/web/",
                base_path: "",
                trusted_proxy_identity: false,
                recall: crate::Recall::default(),
                runtime: None,
                health: None,
            },
        )
        .unwrap();
        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/api/v1/workspaces")
                    .header("Origin", "https://evil.example.com")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        // The request is still served (CORS does not block on the server side),
        // but the ACAO header must be absent so the browser enforces the policy.
        assert!(
            resp.headers().get("access-control-allow-origin").is_none(),
            "unlisted origin must not receive ACAO header"
        );
    }

    #[tokio::test]
    async fn cors_not_applied_to_other_routes() {
        // /mcp and /admin routes must not carry CORS headers even when
        // a CORS origin list is configured (CORS_NOT_APPLIED_TO_OTHER_ROUTES
        // invariant). We verify by checking that a request to a non-/api/v1
        // path that 404s (no actual handler mounted here) still lacks ACAO.
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        let cors_origins = ["https://app.example.com".to_string()];
        let router = mount_web_router(
            axum::Router::new(),
            true,
            store.reader.clone(),
            wiki,
            WebMountSpec {
                enable_api: false,
                web_ui_dir: None,
                cors_origins: &cors_origins,
                web_slug: "/web",
                base_href: "/web/",
                base_path: "",
                trusted_proxy_identity: false,
                recall: crate::Recall::default(),
                runtime: None,
                health: None,
            },
        )
        .unwrap();
        // /web is a non-api route; sending an Origin header must not trigger CORS.
        let resp = router
            .oneshot(
                Request::builder()
                    .uri("/web")
                    .header("Origin", "https://app.example.com")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert!(
            resp.headers().get("access-control-allow-origin").is_none(),
            "/web must not carry CORS headers: {:?}",
            resp.headers()
        );
    }
}