csaf-crud 1.5.28

// SPDX-License-Identifier: Apache-2.0
// Copyright (c) 2026 Pierre Gronau, ndaal in Cologne

//! Static information page route handlers.
//!
//! Provides About, License, System Information, Privacy, and Security pages.

use csaf_core::config::AppConfig;
use http::{Response, StatusCode};

use crate::app_state::AppState;
use crate::i18n::{self, Lang, t};
use crate::router::{Body, html_response};
use crate::routes::imprint::{IMPRINT_HEADING, imprint_body_html};
use crate::routes::layout::{Nav, PageContext, html_escape, theme_for, wrap_page};

/// Render the sub-nav card shown at the top of every Info-section page
/// (About/License/System/Privacy/Security plus the four document pages).
fn info_sub_nav(lang: Lang) -> String {
    format!(
        r#"<nav class="card subnav" aria-label="{label}">
  <ul class="subnav-list">
    <li><a href="/info/about" class="subnav-link">{about}</a></li>
    <li><a href="/info/license" class="subnav-link">{license}</a></li>
    <li><a href="/info/system" class="subnav-link">{system}</a></li>
    <li><a href="/info/privacy" class="subnav-link">{privacy}</a></li>
    <li><a href="/info/security" class="subnav-link">{security}</a></li>
    <li><a href="/imprint" class="subnav-link">{imprint}</a></li>
    <li><a href="/changelog" class="subnav-link">{changelog}</a></li>
    <li><a href="/readme" class="subnav-link">{readme}</a></li>
    <li><a href="/administrator" class="subnav-link">{administrator}</a></li>
    <li><a href="/user" class="subnav-link">{user}</a></li>
    <li><a href="/developer" class="subnav-link">{developer}</a></li>
    <li><a href="/troubleshooting" class="subnav-link">{troubleshooting}</a></li>
  </ul>
</nav>"#,
        label = t(lang, "nav.info"),
        about = t(lang, "info.subnav_about"),
        license = t(lang, "info.subnav_license"),
        system = t(lang, "info.subnav_system"),
        privacy = t(lang, "info.subnav_privacy"),
        security = t(lang, "info.subnav_security"),
        imprint = t(lang, "info.subnav_imprint"),
        changelog = t(lang, "info.subnav_changelog"),
        readme = t(lang, "info.subnav_readme"),
        administrator = t(lang, "info.subnav_administrator"),
        user = t(lang, "info.subnav_user"),
        developer = t(lang, "info.subnav_developer"),
        troubleshooting = t(lang, "info.subnav_troubleshooting"),
    )
}

/// Render an info page with the shared layout and a sub-nav for the Info
/// section.
fn render_info_page(title: &str, ctx: PageContext<'_>, body: &str) -> Response<Body> {
    let content = format!("{}{body}", info_sub_nav(ctx.lang));
    html_response(StatusCode::OK, wrap_page(title, ctx, Nav::Info, &content))
}

/// `GET /info/about` -- About page.
pub async fn about(
    state: AppState,
    parts: http::request::Parts,
    _params: Vec<(String, String)>,
) -> Response<Body> {
    let lang = i18n::from_parts(&parts);
    let heading = t(lang, "info.about_heading");
    let body = format!(
        r#"<h1>{heading}</h1>
<div class="card">
  <p>{intro}</p>

  <p>{version_label} <strong>{app_version}</strong></p>

  <h2>{features_heading}</h2>
  <ul>
{features_list}
  </ul>

  <h2>{standards_heading}</h2>
  <ul>
    <li><a href="https://docs.oasis-open.org/csaf/csaf/v2.0/csaf-v2.0.html"
           target="_blank" rel="noopener">OASIS CSAF 2.0</a></li>
    <li><a href="https://docs.oasis-open.org/csaf/csaf/v2.1/csaf-v2.1.html"
           target="_blank" rel="noopener">OASIS CSAF 2.1</a></li>
  </ul>

  <h2>{source_heading}</h2>
  <p>{source_intro}</p>
  <ul>
    <li>{repository_label}
      <a href="https://gitlab.com/vPierre/ndaal_public_csaf_crud"
         target="_blank" rel="noopener">https://gitlab.com/vPierre/ndaal_public_csaf_crud</a></li>
    <li>{releases_label}
      <a href="https://gitlab.com/vPierre/ndaal_public_csaf_crud/-/releases"
         target="_blank" rel="noopener">https://gitlab.com/vPierre/ndaal_public_csaf_crud/-/releases</a></li>
    <li>{cratesio_label}
      <a href="https://crates.io/crates/csaf-crud" target="_blank"
         rel="noopener">csaf-crud</a> ·
      <a href="https://crates.io/crates/ndaal-csaf-cli" target="_blank"
         rel="noopener">ndaal-csaf-cli</a> ·
      <a href="https://crates.io/crates/csaf-core" target="_blank"
         rel="noopener">csaf-core</a> ·
      <a href="https://crates.io/crates/csaf-models" target="_blank"
         rel="noopener">csaf-models</a></li>
  </ul>
  <p>{sha_note}</p>

  <h2>{contact_heading}</h2>
  <p>{contact_text}</p>
</div>"#,
        heading = heading,
        intro = t(lang, "info.about_intro"),
        version_label = t(lang, "info.about_version_label"),
        app_version = env!("CARGO_PKG_VERSION"),
        features_heading = t(lang, "info.about_features_heading"),
        features_list = t(lang, "info.about_features_list"),
        standards_heading = t(lang, "info.about_standards_heading"),
        source_heading = t(lang, "info.about_source_heading"),
        source_intro = t(lang, "info.about_source_intro"),
        repository_label = t(lang, "info.about_repository_label"),
        releases_label = t(lang, "info.about_releases_label"),
        cratesio_label = t(lang, "info.about_cratesio_label"),
        sha_note = t(lang, "info.about_sha_note"),
        contact_heading = t(lang, "info.about_contact_heading"),
        contact_text = t(lang, "info.about_contact_text"),
    );

    let settings = state.settings();
    let ctx = PageContext {
        theme: theme_for(&parts, &settings.theme),
        lang,
    };
    render_info_page(heading, ctx, &body)
}

/// `GET /info/license` -- License page.
pub async fn license(
    state: AppState,
    parts: http::request::Parts,
    _params: Vec<(String, String)>,
) -> Response<Body> {
    let lang = i18n::from_parts(&parts);
    let heading = t(lang, "info.license_heading");
    let body = format!(
        r#"<h1>{heading}</h1>
<div class="card">
  <p>{intro}</p>
  <p>{spdx_label} <code>Apache-2.0</code></p>
  <p>Copyright (c) 2026 Pierre Gronau, ndaal in Cologne.</p>

  <h2>{summary_heading}</h2>
  <ul>
{summary_list}
  </ul>
  <p>{full_text_label}
    <a href="https://www.apache.org/licenses/LICENSE-2.0"
       target="_blank" rel="noopener">https://www.apache.org/licenses/LICENSE-2.0</a>
  </p>
</div>"#,
        heading = heading,
        intro = t(lang, "info.license_intro"),
        spdx_label = t(lang, "info.license_spdx_label"),
        summary_heading = t(lang, "info.license_summary_heading"),
        summary_list = t(lang, "info.license_summary_list"),
        full_text_label = t(lang, "info.license_full_text_label"),
    );

    let settings = state.settings();
    let ctx = PageContext {
        theme: theme_for(&parts, &settings.theme),
        lang,
    };
    render_info_page(heading, ctx, &body)
}

/// The value of the "HTTP/3 address (UDP)" row of the System Information page:
/// the address the HTTP/3 listener binds, or "off" when there is none (the
/// `quic_port` setting is `off`, `listen_port` is 65535 so no UDP port follows
/// it, or this build has no HTTP/3).
fn http3_row(config: &AppConfig, lang: Lang) -> String {
    match config.quic_listen_port() {
        Some(port) if cfg!(feature = "quic") => {
            html_escape(&format!("{}:{port}", config.listen_addr))
        },
        _ => t(lang, "info.system_http3_off").to_owned(),
    }
}

/// `GET /info/system` -- System information page.
pub async fn system_info(
    state: AppState,
    parts: http::request::Parts,
    _params: Vec<(String, String)>,
) -> Response<Body> {
    let lang = i18n::from_parts(&parts);
    let mut sys = sysinfo::System::new_all();
    sys.refresh_all();

    let os_name = sysinfo::System::name().unwrap_or_else(|| "Unknown".to_owned());
    let os_version = sysinfo::System::os_version().unwrap_or_else(|| "Unknown".to_owned());
    let kernel_version = sysinfo::System::kernel_version().unwrap_or_else(|| "Unknown".to_owned());
    let hostname = sysinfo::System::host_name().unwrap_or_else(|| "Unknown".to_owned());

    let total_memory_mb = sys.total_memory() / 1_048_576;
    let used_memory_mb = sys.used_memory() / 1_048_576;
    let cpu_count = sys.cpus().len();

    let doc_count = state.csaf_storage().count_documents().unwrap_or(0);
    let storage_ok = state.csaf_storage().check_storage_up().unwrap_or(false);

    let config = state.config();
    let settings = state.settings();

    let heading = t(lang, "info.system_heading");
    let body = format!(
        r#"<h1>{heading}</h1>
<div class="card">
  <h2 id="host-heading">{host_heading}</h2>
  <table aria-labelledby="host-heading">
    <tr><th scope="row">{hostname_label}</th><td>{hostname}</td></tr>
    <tr><th scope="row">{os_label}</th><td>{os_name} {os_version}</td></tr>
    <tr><th scope="row">{kernel_label}</th><td>{kernel_version}</td></tr>
    <tr><th scope="row">{cpus_label}</th><td>{cpu_count}</td></tr>
    <tr><th scope="row">{memory_label}</th><td>{used_memory_mb} MB / {total_memory_mb} MB</td></tr>
  </table>
</div>
<div class="card">
  <h2 id="application-heading">{application_heading}</h2>
  <table aria-labelledby="application-heading">
    <tr><th scope="row">{version_label}</th><td>{app_version}</td></tr>
    <tr><th scope="row">{rust_version_label}</th><td>{rust_version}</td></tr>
    <tr><th scope="row">{listen_address_label}</th><td>{listen}</td></tr>
    <tr><th scope="row">{http3_label}</th><td>{http3}</td></tr>
    <tr><th scope="row">{data_directory_label}</th><td>{data_dir}</td></tr>
    <tr><th scope="row">{storage_status_label}</th><td>{storage_status}</td></tr>
    <tr><th scope="row">{documents_stored_label}</th><td>{doc_count}</td></tr>
    <tr><th scope="row">{csaf_mode_label}</th><td>{csaf_mode}</td></tr>
  </table>
</div>"#,
        heading = heading,
        host_heading = t(lang, "info.system_host_heading"),
        hostname_label = t(lang, "info.system_hostname_label"),
        hostname = html_escape(&hostname),
        os_label = t(lang, "info.system_os_label"),
        os_name = html_escape(&os_name),
        os_version = html_escape(&os_version),
        kernel_label = t(lang, "info.system_kernel_label"),
        kernel_version = html_escape(&kernel_version),
        cpus_label = t(lang, "info.system_cpus_label"),
        cpu_count = cpu_count,
        memory_label = t(lang, "info.system_memory_label"),
        used_memory_mb = used_memory_mb,
        total_memory_mb = total_memory_mb,
        application_heading = t(lang, "info.system_application_heading"),
        version_label = t(lang, "info.system_version_label"),
        app_version = env!("CARGO_PKG_VERSION"),
        rust_version_label = t(lang, "info.system_rust_version_label"),
        rust_version = html_escape(env!("CARGO_PKG_RUST_VERSION", "unknown")),
        listen_address_label = t(lang, "info.system_listen_address_label"),
        listen = html_escape(&config.listen_address()),
        http3_label = t(lang, "info.system_http3_label"),
        http3 = http3_row(config, lang),
        data_directory_label = t(lang, "info.system_data_directory_label"),
        data_dir = html_escape(&config.data_dir.display().to_string()),
        storage_status_label = t(lang, "info.system_storage_status_label"),
        storage_status = if storage_ok {
            t(lang, "info.system_status_healthy")
        } else {
            t(lang, "info.system_status_degraded")
        },
        documents_stored_label = t(lang, "info.system_documents_stored_label"),
        doc_count = doc_count,
        csaf_mode_label = t(lang, "info.system_csaf_mode_label"),
        csaf_mode = html_escape(&settings.csaf_mode),
    );

    let ctx = PageContext {
        theme: theme_for(&parts, &settings.theme),
        lang,
    };
    render_info_page(heading, ctx, &body)
}

/// `GET /info/privacy` -- Privacy page.
pub async fn privacy(
    state: AppState,
    parts: http::request::Parts,
    _params: Vec<(String, String)>,
) -> Response<Body> {
    let lang = i18n::from_parts(&parts);
    let heading = t(lang, "info.privacy_heading");
    let body = format!(
        r#"<h1>{heading}</h1>
<div class="card">
  <h2>{data_processing_heading}</h2>
  <p>{data_processing_text}</p>

  <h2>{data_collected_heading}</h2>
  <ul>
{data_collected_list}
  </ul>

  <h2>{no_external_heading}</h2>
  <p>{no_external_text}</p>

  <h2>{retention_heading}</h2>
  <p>{retention_text}</p>

  <h2>{gdpr_heading}</h2>
  <p>{gdpr_text}</p>
</div>"#,
        heading = heading,
        data_processing_heading = t(lang, "info.privacy_data_processing_heading"),
        data_processing_text = t(lang, "info.privacy_data_processing_text"),
        data_collected_heading = t(lang, "info.privacy_data_collected_heading"),
        data_collected_list = t(lang, "info.privacy_data_collected_list"),
        no_external_heading = t(lang, "info.privacy_no_external_heading"),
        no_external_text = t(lang, "info.privacy_no_external_text"),
        retention_heading = t(lang, "info.privacy_retention_heading"),
        retention_text = t(lang, "info.privacy_retention_text"),
        gdpr_heading = t(lang, "info.privacy_gdpr_heading"),
        gdpr_text = t(lang, "info.privacy_gdpr_text"),
    );

    let settings = state.settings();
    let ctx = PageContext {
        theme: theme_for(&parts, &settings.theme),
        lang,
    };
    render_info_page(heading, ctx, &body)
}

/// `GET /info/security` -- Security page.
pub async fn security(
    state: AppState,
    parts: http::request::Parts,
    _params: Vec<(String, String)>,
) -> Response<Body> {
    let lang = i18n::from_parts(&parts);
    let heading = t(lang, "info.security_heading");
    let body = format!(
        r#"<h1>{heading}</h1>
<div class="card">
  <h2>{transport_heading}</h2>
  <ul>
{transport_list}
  </ul>

  <h2>{auth_heading}</h2>
  <ul>
{auth_list}
  </ul>

  <h2>{integrity_heading}</h2>
  <ul>
{integrity_list}
  </ul>

  <h2>{input_heading}</h2>
  <ul>
{input_list}
  </ul>

  <h2>{reporting_heading}</h2>
  <p>{reporting_text}</p>
</div>"#,
        heading = heading,
        transport_heading = t(lang, "info.security_transport_heading"),
        transport_list = t(lang, "info.security_transport_list"),
        auth_heading = t(lang, "info.security_auth_heading"),
        auth_list = t(lang, "info.security_auth_list"),
        integrity_heading = t(lang, "info.security_integrity_heading"),
        integrity_list = t(lang, "info.security_integrity_list"),
        input_heading = t(lang, "info.security_input_heading"),
        input_list = t(lang, "info.security_input_list"),
        reporting_heading = t(lang, "info.security_reporting_heading"),
        reporting_text = t(lang, "info.security_reporting_text"),
    );

    let settings = state.settings();
    let ctx = PageContext {
        theme: theme_for(&parts, &settings.theme),
        lang,
    };
    render_info_page(heading, ctx, &body)
}

/// The full Imprint page: the Info sub-navigation, then the German notice.
fn imprint_page_html(ctx: PageContext<'_>) -> String {
    let content = format!("{}{}", info_sub_nav(ctx.lang), imprint_body_html());
    wrap_page(IMPRINT_HEADING, ctx, Nav::Info, &content)
}

/// `GET /imprint` -- Imprint (Impressum) page.
pub async fn imprint(
    state: AppState,
    parts: http::request::Parts,
    _params: Vec<(String, String)>,
) -> Response<Body> {
    let lang = i18n::from_parts(&parts);
    let settings = state.settings();
    let ctx = PageContext {
        theme: theme_for(&parts, &settings.theme),
        lang,
    };
    html_response(StatusCode::OK, imprint_page_html(ctx))
}

// These embed from crates/csaf-crud/embedded_docs/, a synced local copy of
// the workspace-root files, not the originals directly: `cargo package`/
// `cargo publish` never bundles files outside the crate directory, so a
// source-file-relative include_str! into ../../CHANGELOG.md etc. compiles
// fine in a normal workspace build but fails package verification (and
// would 404 for anyone building the crate standalone from crates.io). The
// `on_disk()` helper in `doc_page_tests` below still reads the canonical
// workspace-root files directly, so any drift between the two fails CI.

/// The repository's `CHANGELOG.md`, embedded at compile time from the
/// crate-local synced copy (see comment above).
const CHANGELOG_MD: &str = include_str!("../../embedded_docs/CHANGELOG.md");
/// The repository's `README.md`, embedded at compile time from the
/// crate-local synced copy.
const README_MD: &str = include_str!("../../embedded_docs/README.md");
/// The repository's `documentation/Administrator_Guide.md`, embedded at
/// compile time from the crate-local synced copy.
const ADMINISTRATOR_GUIDE_MD: &str = include_str!("../../embedded_docs/Administrator_Guide.md");
/// The repository's `documentation/User_Guide.md`, embedded at compile
/// time from the crate-local synced copy.
const USER_GUIDE_MD: &str = include_str!("../../embedded_docs/User_Guide.md");
/// The repository's `documentation/Developer_Guide.md`, embedded at
/// compile time from the crate-local synced copy.
const DEVELOPER_GUIDE_MD: &str = include_str!("../../embedded_docs/Developer_Guide.md");
/// The repository's `documentation/Troubleshooting_Guide.md`, embedded
/// at compile time from the crate-local synced copy.
const TROUBLESHOOTING_GUIDE_MD: &str = include_str!("../../embedded_docs/Troubleshooting_Guide.md");

/// Build a document page's full HTML: the raw Markdown source,
/// HTML-escaped and shown as preformatted text (no Markdown-to-HTML
/// rendering — matches the sibling `grundschutz-oscal-viewer` project's
/// doc-page convention). Pure function, synchronously testable without a
/// live `AppState`. The Markdown body itself is a raw file embed and is
/// never translated -- only `title`/`heading` (the caller's chrome text)
/// vary by language.
fn doc_page_html(title: &str, ctx: PageContext<'_>, heading: &str, markdown: &str) -> String {
    let body = format!(
        r#"<h1>{heading}</h1>
<div class="card">
  <pre class="u-pre-wrap">{content}</pre>
</div>"#,
        heading = html_escape(heading),
        content = html_escape(markdown),
    );
    wrap_page(
        title,
        ctx,
        Nav::Info,
        &format!("{}{body}", info_sub_nav(ctx.lang)),
    )
}

/// Render a document page as an HTTP response.
fn render_doc_page(
    title: &str,
    ctx: PageContext<'_>,
    heading: &str,
    markdown: &str,
) -> Response<Body> {
    html_response(StatusCode::OK, doc_page_html(title, ctx, heading, markdown))
}

/// `GET /changelog` -- Changelog page.
pub async fn changelog(
    state: AppState,
    parts: http::request::Parts,
    _params: Vec<(String, String)>,
) -> Response<Body> {
    let lang = i18n::from_parts(&parts);
    let heading = t(lang, "info.changelog_heading");
    let settings = state.settings();
    let ctx = PageContext {
        theme: theme_for(&parts, &settings.theme),
        lang,
    };
    render_doc_page(heading, ctx, heading, CHANGELOG_MD)
}

/// `GET /readme` -- README page.
pub async fn readme(
    state: AppState,
    parts: http::request::Parts,
    _params: Vec<(String, String)>,
) -> Response<Body> {
    let lang = i18n::from_parts(&parts);
    let heading = t(lang, "info.readme_heading");
    let settings = state.settings();
    let ctx = PageContext {
        theme: theme_for(&parts, &settings.theme),
        lang,
    };
    render_doc_page(heading, ctx, heading, README_MD)
}

/// `GET /administrator` -- Administrator Guide page.
pub async fn administrator_guide(
    state: AppState,
    parts: http::request::Parts,
    _params: Vec<(String, String)>,
) -> Response<Body> {
    let lang = i18n::from_parts(&parts);
    let heading = t(lang, "info.administrator_heading");
    let settings = state.settings();
    let ctx = PageContext {
        theme: theme_for(&parts, &settings.theme),
        lang,
    };
    render_doc_page(heading, ctx, heading, ADMINISTRATOR_GUIDE_MD)
}

/// `GET /user` -- User Guide page.
pub async fn user_guide(
    state: AppState,
    parts: http::request::Parts,
    _params: Vec<(String, String)>,
) -> Response<Body> {
    let lang = i18n::from_parts(&parts);
    let heading = t(lang, "info.user_heading");
    let settings = state.settings();
    let ctx = PageContext {
        theme: theme_for(&parts, &settings.theme),
        lang,
    };
    render_doc_page(heading, ctx, heading, USER_GUIDE_MD)
}

/// `GET /developer` -- Developer Guide page.
pub async fn developer_guide(
    state: AppState,
    parts: http::request::Parts,
    _params: Vec<(String, String)>,
) -> Response<Body> {
    let lang = i18n::from_parts(&parts);
    let heading = t(lang, "info.developer_heading");
    let settings = state.settings();
    let ctx = PageContext {
        theme: theme_for(&parts, &settings.theme),
        lang,
    };
    render_doc_page(heading, ctx, heading, DEVELOPER_GUIDE_MD)
}

/// `GET /troubleshooting` -- Troubleshooting Guide page.
pub async fn troubleshooting_guide(
    state: AppState,
    parts: http::request::Parts,
    _params: Vec<(String, String)>,
) -> Response<Body> {
    let lang = i18n::from_parts(&parts);
    let heading = t(lang, "info.troubleshooting_heading");
    let settings = state.settings();
    let ctx = PageContext {
        theme: theme_for(&parts, &settings.theme),
        lang,
    };
    render_doc_page(heading, ctx, heading, TROUBLESHOOTING_GUIDE_MD)
}

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

    fn ctx(theme: &str) -> PageContext<'_> {
        PageContext {
            theme,
            lang: Lang::En,
        }
    }

    fn on_disk(rel: &str) -> String {
        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("../../")
            .join(rel);
        std::fs::read_to_string(root).expect("read on-disk doc file")
    }

    #[test]
    fn changelog_embed_matches_on_disk_file() {
        assert_eq!(CHANGELOG_MD, on_disk("CHANGELOG.md"));
    }

    #[test]
    fn readme_embed_matches_on_disk_file() {
        assert_eq!(README_MD, on_disk("README.md"));
    }

    #[test]
    fn administrator_guide_embed_matches_on_disk_file() {
        assert_eq!(
            ADMINISTRATOR_GUIDE_MD,
            on_disk("documentation/Administrator_Guide.md")
        );
    }

    #[test]
    fn user_guide_embed_matches_on_disk_file() {
        assert_eq!(USER_GUIDE_MD, on_disk("documentation/User_Guide.md"));
    }

    #[test]
    fn developer_guide_embed_matches_on_disk_file() {
        assert_eq!(
            DEVELOPER_GUIDE_MD,
            on_disk("documentation/Developer_Guide.md")
        );
    }

    #[test]
    fn troubleshooting_guide_embed_matches_on_disk_file() {
        assert_eq!(
            TROUBLESHOOTING_GUIDE_MD,
            on_disk("documentation/Troubleshooting_Guide.md")
        );
    }

    #[test]
    fn all_six_embeds_are_non_trivial() {
        for (name, content) in [
            ("CHANGELOG_MD", CHANGELOG_MD),
            ("README_MD", README_MD),
            ("ADMINISTRATOR_GUIDE_MD", ADMINISTRATOR_GUIDE_MD),
            ("USER_GUIDE_MD", USER_GUIDE_MD),
            ("DEVELOPER_GUIDE_MD", DEVELOPER_GUIDE_MD),
            ("TROUBLESHOOTING_GUIDE_MD", TROUBLESHOOTING_GUIDE_MD),
        ] {
            assert!(
                content.len() > 200,
                "{name} is suspiciously short ({} bytes) -- embed likely broken",
                content.len()
            );
        }
    }

    #[test]
    fn changelog_page_renders_full_content_without_truncation() {
        let html = doc_page_html("Changelog", ctx("light"), "Changelog", CHANGELOG_MD);
        assert!(html.contains(r#"<h1 class="page-title">"#) && html.contains("Changelog</h1>"));
        // The escaped changelog body must be present in full -- assert the
        // first and last non-blank lines of the source both appear, which
        // fails if the page ever truncates the content.
        let first_line = CHANGELOG_MD.lines().next().unwrap_or_default();
        let last_line = CHANGELOG_MD.lines().last().unwrap_or_default();
        assert!(html.contains(&html_escape(first_line)));
        if !last_line.trim().is_empty() {
            assert!(html.contains(&html_escape(last_line)));
        }
    }

    #[test]
    fn readme_page_renders_ok() {
        let html = doc_page_html("README", ctx("light"), "README", README_MD);
        assert!(html.contains(r#"<h1 class="page-title">"#) && html.contains("README</h1>"));
    }

    #[test]
    fn administrator_guide_page_renders_ok() {
        let html = doc_page_html(
            "Administrator Guide",
            ctx("light"),
            "Administrator Guide",
            ADMINISTRATOR_GUIDE_MD,
        );
        assert!(
            html.contains(r#"<h1 class="page-title">"#)
                && html.contains("Administrator Guide</h1>")
        );
    }

    #[test]
    fn user_guide_page_renders_ok() {
        let html = doc_page_html("User Guide", ctx("light"), "User Guide", USER_GUIDE_MD);
        assert!(html.contains(r#"<h1 class="page-title">"#) && html.contains("User Guide</h1>"));
    }

    #[test]
    fn developer_guide_page_renders_the_whole_document_unrendered() {
        let html = doc_page_html(
            "Developer Guide",
            ctx("light"),
            "Developer Guide",
            DEVELOPER_GUIDE_MD,
        );
        assert!(
            html.contains(r#"<h1 class="page-title">"#) && html.contains("Developer Guide</h1>")
        );
        // The first and last lines must both reach the page (no truncation),
        // and the Markdown must stay text inside the escaped <pre>.
        let first = DEVELOPER_GUIDE_MD.lines().next().unwrap_or_default();
        assert!(html.contains(&html_escape(first)));
        assert!(html.contains(r#"<pre class="u-pre-wrap">"#));
    }

    #[test]
    fn troubleshooting_guide_page_renders_the_whole_document_unrendered() {
        let html = doc_page_html(
            "Troubleshooting Guide",
            ctx("light"),
            "Troubleshooting Guide",
            TROUBLESHOOTING_GUIDE_MD,
        );
        assert!(
            html.contains(r#"<h1 class="page-title">"#)
                && html.contains("Troubleshooting Guide</h1>")
        );
        let first = TROUBLESHOOTING_GUIDE_MD.lines().next().unwrap_or_default();
        assert!(html.contains(&html_escape(first)));
        assert!(html.contains(r#"<pre class="u-pre-wrap">"#));
    }

    #[test]
    fn doc_page_html_escapes_markdown_source() {
        // The raw Markdown is shown as escaped preformatted text, not
        // rendered HTML -- a `<script>` payload in the source must never
        // survive unescaped into the page. `wrap_page` itself legitimately
        // emits `<script>` tags (the page script), so check for the exact
        // payload rather than the bare tag.
        let payload = "<script>alert(1)</script>";
        let html = doc_page_html("Test", ctx("light"), "Test", payload);
        assert!(!html.contains(payload));
        assert!(html.contains("&lt;script&gt;alert(1)&lt;/script&gt;"));
    }

    #[test]
    fn info_dropdown_links_all_six_doc_pages() {
        let html = wrap_page("Test", ctx("light"), Nav::Info, "");
        for href in [
            "/changelog",
            "/readme",
            "/administrator",
            "/user",
            "/developer",
            "/troubleshooting",
        ] {
            assert!(
                html.contains(&format!(r#"href="{href}""#)),
                "navbar Info dropdown missing link to {href}"
            );
        }
        // Divider must separate the pre-existing info pages from the new
        // document links.
        assert!(html.contains("dropdown-divider"));
    }

    /// Position of the first `href="<route>"` in `html`.
    fn href_pos(html: &str, route: &str) -> usize {
        html.find(&format!(r#"href="{route}""#))
            .unwrap_or_else(|| panic!("no link to {route}"))
    }

    #[test]
    fn info_menu_follows_the_ndaal_design_order_and_ends_with_troubleshooting() {
        // skills/ndaal-design patterns.md 8.1: ... Changelog, README,
        // Administrator Guide, User Guide, Developer Guide, Troubleshooting
        // Guide, and nothing after the Troubleshooting Guide.
        let html = wrap_page("Test", ctx("light"), Nav::Info, "");
        let order = [
            "/changelog",
            "/readme",
            "/administrator",
            "/user",
            "/developer",
            "/troubleshooting",
        ];
        for pair in order.windows(2) {
            assert!(
                href_pos(&html, pair[0]) < href_pos(&html, pair[1]),
                "{} must come before {} in the Info menu",
                pair[0],
                pair[1]
            );
        }
        let last = href_pos(&html, "/troubleshooting");
        let menu_end = html[last..]
            .find("</details>")
            .expect("the Info menu closes");
        // The Troubleshooting Guide's own anchor carries the one `menu-link`
        // class left between its href and the end of the menu.
        assert_eq!(
            html[last..last + menu_end].matches("menu-link").count(),
            1,
            "nothing may follow the Troubleshooting Guide in the Info menu"
        );
    }

    #[test]
    fn info_sub_nav_lists_both_new_guides_after_the_user_guide() {
        let html = info_sub_nav(Lang::En);
        assert!(
            href_pos(&html, "/user") < href_pos(&html, "/developer")
                && href_pos(&html, "/developer") < href_pos(&html, "/troubleshooting"),
            "sub-navigation order: User, Developer, Troubleshooting"
        );
    }

    #[test]
    fn system_info_is_labelled_system_information() {
        // ndaal-design 8.1 names item 2 "System Information"; the shortened
        // "System info" was the divergence the skill calls out.
        for key in [
            "nav.info_system",
            "info.subnav_system",
            "info.system_heading",
        ] {
            assert_eq!(t(Lang::En, key), "System Information", "{key}");
        }
    }

    #[test]
    fn the_new_guides_have_english_labels_and_headings() {
        for (key, want) in [
            ("nav.info_developer", "Developer Guide"),
            ("nav.info_troubleshooting", "Troubleshooting Guide"),
            ("info.subnav_developer", "Developer Guide"),
            ("info.subnav_troubleshooting", "Troubleshooting Guide"),
            ("info.developer_heading", "Developer Guide"),
            ("info.troubleshooting_heading", "Troubleshooting Guide"),
        ] {
            assert_eq!(t(Lang::En, key), want, "{key}");
        }
    }

    #[test]
    fn info_menu_lists_imprint_after_security_and_before_the_divider() {
        // skills/rust-info-imprint: Imprint closes the legal group (Privacy,
        // Security, License, Imprint) and the second divider follows it.
        let html = wrap_page("Test", ctx("light"), Nav::Info, "");
        let security = href_pos(&html, "/info/security");
        let imprint = href_pos(&html, "/imprint");
        assert!(security < imprint, "Imprint must follow Security");
        let after = &html[imprint..];
        let divider = after.find("dropdown-divider").expect("a divider follows");
        let changelog = after
            .find(r#"href="/changelog""#)
            .expect("the Changelog follows");
        assert!(
            divider < changelog,
            "the divider sits between Imprint and the Changelog"
        );
    }

    #[test]
    fn info_sub_nav_lists_imprint_after_security() {
        let html = info_sub_nav(Lang::En);
        assert!(
            href_pos(&html, "/info/security") < href_pos(&html, "/imprint")
                && href_pos(&html, "/imprint") < href_pos(&html, "/changelog"),
            "sub-navigation order: Security, Imprint, Changelog"
        );
    }

    #[test]
    fn imprint_has_an_english_menu_label_and_a_german_heading() {
        // The label is translated; the notice itself is German in every
        // language, so the heading is the fixed word "Impressum".
        assert_eq!(t(Lang::En, "nav.info_imprint"), "Imprint");
        assert_eq!(t(Lang::En, "info.subnav_imprint"), "Imprint");
    }

    /// A config with the given TCP port and `quic_port` setting.
    fn config_with(port: u16, quic: csaf_core::config::QuicPort) -> AppConfig {
        AppConfig {
            listen_port: csaf_core::listen_port::ListenPort::try_new(port).expect("a valid port"),
            quic_port: quic,
            ..AppConfig::default()
        }
    }

    #[test]
    fn http3_row_shows_the_udp_address_that_follows_listen_port() {
        let config = config_with(8180, csaf_core::config::QuicPort::Derived);
        assert_eq!(http3_row(&config, Lang::En), "127.0.0.1:8181");
    }

    #[test]
    fn http3_row_shows_the_explicit_quic_port() {
        let port = csaf_core::listen_port::ListenPort::try_new(9000).expect("a valid port");
        let config = config_with(8180, csaf_core::config::QuicPort::Port(port));
        assert_eq!(http3_row(&config, Lang::En), "127.0.0.1:9000");
    }

    #[test]
    fn http3_row_says_off_when_quic_port_is_off() {
        let config = config_with(8180, csaf_core::config::QuicPort::Off);
        assert_eq!(http3_row(&config, Lang::En), "off");
    }

    #[test]
    fn http3_row_says_off_at_listen_port_65535_where_no_udp_port_follows() {
        let config = config_with(65535, csaf_core::config::QuicPort::Derived);
        assert_eq!(http3_row(&config, Lang::En), "off");
    }

    #[test]
    fn http3_row_escapes_the_address() {
        let mut config = config_with(8180, csaf_core::config::QuicPort::Derived);
        config.listen_addr = "<b>&".to_owned();
        let row = http3_row(&config, Lang::En);
        assert!(row.contains("&lt;b&gt;&amp;"), "{row}");
        assert!(!row.contains("<b>"), "{row}");
    }

    #[test]
    fn the_http3_row_has_english_labels() {
        assert_eq!(
            t(Lang::En, "info.system_http3_label"),
            "HTTP/3 Address (UDP)"
        );
        assert_eq!(t(Lang::En, "info.system_http3_off"), "off");
    }

    #[test]
    fn imprint_page_is_the_german_notice_inside_the_info_section() {
        let html = imprint_page_html(ctx("light"));
        assert!(html.contains("<title>Impressum"), "title is Impressum");
        assert!(html.contains(r#"<div lang="de">"#), "marked as German");
        assert!(html.contains("Impressum</h1>"), "heading");
        assert!(
            html.contains(r#"class="card subnav""#),
            "the Info sub-navigation is part of the page"
        );
        assert!(html.contains("xing.com"), "the notice reaches the page");
    }
}