koan_server/ui/

mod.rs

//! The web UI: sign in, browse the library and play it in the browser.
//!
//! Server-rendered HTML, with Datastar for the parts that change in place
//! (search as you type, the share button) and a small script of
//! its own that swaps only the page content on navigation, so the player keeps
//! playing. Playback happens in the browser, streaming from `/ui/stream`: a
//! headless server has no speakers.
//!
//! Sign-in is koan's own session: the same `HttpOnly` access and refresh
//! cookies the JSON login sets, so tokens never reach page script. The gate
//! accepts a valid access cookie; a page load without one goes through
//! `/auth/resume`, which spends the refresh cookie (scoped to `/auth`, so only
//! that route sees it) for fresh cookies, or on to the sign-in form.

mod account;
mod browse;
mod caches;
mod connect;
mod favourite;
mod history;
mod oauth;
mod pages;
mod pair;
mod properties;
mod scan;
mod scrobbling;
mod session;
mod setup;
#[cfg(test)]
mod tests;
mod users;

pub use oauth::RESOURCE_METADATA;
pub use session::ProxyAuth;

use std::path::PathBuf;
use std::sync::Arc;

use axum::extract::{Path, RawQuery, Request, State};
use axum::http::{Extensions, HeaderMap, HeaderValue, Method, StatusCode, Version, header};
use axum::middleware::{Next, from_fn, from_fn_with_state};
use axum::response::sse::{Event, Sse};
use axum::response::{IntoResponse, Response};
use axum::routing::{get, post};
use koan_core::auth;
use koan_core::db::pool::{Handle, Pool};
use koan_core::db::queries;
use tower_http::compression::CompressionLayer;
use tower_http::compression::predicate::{DefaultPredicate, Predicate};

use crate::auth::AuthUser;
use crate::auth::routes::{AuthRouteState, RateLimiter, login_rate_limit, rate_limit};
use crate::covers::Covers;
use crate::share::{asset, blocking, not_found};

/// `'unsafe-eval'` because Datastar compiles its attribute expressions.
/// Everything else is this server's own, and nothing is inline but the import
/// map naming the player, allowed by its hash.
static PAGE_CSP: std::sync::LazyLock<String> = std::sync::LazyLock::new(|| {
    format!(
        "default-src 'none'; script-src 'self' 'unsafe-eval' {}; style-src 'self'; font-src 'self'; \
         img-src 'self'; media-src 'self' blob:; connect-src 'self'; base-uri 'self'; form-action 'self'; \
         frame-ancestors 'none'",
        ASSETS.imports.csp
    )
});
/// `PAGE_CSP` as the header every page sends; OAuth's consent page widens the
/// text instead.
static PAGE_CSP_HEADER: std::sync::LazyLock<HeaderValue> =
    std::sync::LazyLock::new(|| HeaderValue::from_str(&PAGE_CSP).expect("the CSP is ASCII"));

/// Sent by the UI's own navigation, which wants the page content without the shell.
const PARTIAL: &str = "x-koan-partial";

const UI_CSS: &str = include_str!("../../assets/ui.css");
const UI_JS: &str = include_str!(concat!(env!("OUT_DIR"), "/ui.js"));
const DATASTAR_JS: &str = include_str!("../../assets/datastar.js");
const NO_COVER_SVG: &str = include_str!("../../assets/no-cover.svg");

/// The page's stylesheet and scripts, each URL carrying a hash of its asset.
pub(super) struct AssetUrls {
    pub css: String,
    pub css_hash: String,
    pub ui_js: String,
    pub player_js: String,
    pub imports: crate::share::ImportMap,
    pub datastar_js: String,
}

pub(super) static ASSETS: std::sync::LazyLock<AssetUrls> = std::sync::LazyLock::new(|| {
    use crate::share::versioned;
    let player_js = versioned("./ui/assets/player.js", crate::share::ENGINE_JS);
    AssetUrls {
        css: versioned("./ui/assets/ui.css", UI_CSS),
        css_hash: crate::share::content_hash(UI_CSS),
        ui_js: versioned("./ui/assets/ui.js", UI_JS),
        imports: crate::share::ImportMap::player(&player_js),
        player_js,
        datastar_js: versioned("./ui/assets/datastar.js", DATASTAR_JS),
    }
});

#[derive(Clone)]
pub struct UiState {
    pool: Arc<Pool>,
    covers: Arc<Covers>,
    /// The codecs and genres the filters offer, with the `library_stamp` they
    /// were read at.
    options: Arc<std::sync::Mutex<Option<(u64, pages::Options)>>>,
    auth: AuthRouteState,
    auth_enabled: bool,
    /// `graphql.setup_wizard`: whether `/setup` may make the first admin.
    setup_wizard: bool,
    /// `server.url`, the address invites point clients at.
    server_url: Option<String>,
    /// OAuth codes awaiting their token request.
    codes: oauth::Codes,
    /// `mcp.redirect_hosts`.
    redirect_hosts: Arc<Vec<String>>,
    /// `graphql.proxy_auth_header`, when an authenticating proxy is trusted.
    proxy_auth: Option<ProxyAuth>,
    /// GraphQL's background jobs, which a rescan started here joins.
    jobs: crate::graphql::jobs::JobRegistry,
}

impl UiState {
    /// What pages name as `<base href>`; see `crate::base`.
    fn base(&self) -> String {
        crate::base::href(self.server_url.as_deref())
    }
}

#[allow(clippy::too_many_arguments)]
pub(crate) fn router(
    pool: Arc<Pool>,
    auth: AuthRouteState,
    auth_enabled: bool,
    setup_wizard: bool,
    covers: Arc<Covers>,
    server_url: Option<String>,
    redirect_hosts: Vec<String>,
    proxy_auth: Option<ProxyAuth>,
    jobs: crate::graphql::jobs::JobRegistry,
) -> axum::Router {
    let state = UiState {
        pool,
        covers,
        options: Arc::default(),
        auth,
        auth_enabled,
        setup_wizard,
        server_url,
        codes: oauth::Codes::default(),
        redirect_hosts: Arc::new(redirect_hosts),
        proxy_auth,
        jobs,
    };
    let base = crate::base::path_of(state.server_url.as_deref());
    let gated = axum::Router::new()
        .route("/", get(pages::albums))
        .route("/albums", get(pages::albums))
        .route("/album/{id}", get(pages::album))
        .route("/album/{id}/share", post(pages::share_album))
        .route("/artist/{id}/share", post(pages::share_artist))
        .route("/artists", get(pages::artists))
        .route("/artist/{id}", get(pages::artist))
        .route("/tracks", get(pages::tracks))
        .route("/track/{id}/properties", get(properties::page))
        .route("/playlists", get(pages::playlists))
        .route("/playlist/{id}", get(pages::playlist))
        .route("/search", get(pages::search))
        .route("/search/results", get(pages::search_results))
        .route("/queue", get(pages::queue))
        .route("/library", get(pages::library))
        .route("/library/scan", get(scan::watch).post(scan::start))
        .route("/library/caches", get(caches::watch))
        .route("/library/caches/clear", post(caches::clear))
        .route("/library/caches/warm", post(caches::warm))
        .route("/favourites", get(pages::favourites))
        .route("/recent", get(pages::recent))
        .route("/history", get(history::page))
        .route("/favourite/{kind}/{id}", post(favourite::toggle))
        .route("/history/forget", post(history::forget))
        .route("/connect", get(connect::page))
        .route("/account", get(account::page))
        .route("/account/keys", post(account::create_key))
        .route("/account/keys/{id}/revoke", post(account::revoke_key))
        .route("/account/app-passwords", post(account::create_app_password))
        .route(
            "/account/app-passwords/{id}/revoke",
            post(account::revoke_app_password),
        )
        // Where the keys page was.
        .route("/keys", get(|| async { see_other("/account") }))
        .route("/scrobbling", get(scrobbling::page))
        .route(
            "/scrobbling/lastfm/connect",
            get(scrobbling::lastfm_connect),
        )
        .route(
            "/scrobbling/lastfm/return/{state}",
            get(scrobbling::lastfm_return),
        )
        .route(
            "/scrobbling/lastfm/disconnect",
            post(scrobbling::lastfm_disconnect),
        )
        .route("/scrobbling/listenbrainz", post(scrobbling::connect))
        .route(
            "/scrobbling/listenbrainz/disconnect",
            post(scrobbling::disconnect),
        )
        .route("/users", get(users::page).post(users::create))
        .route("/users/{id}/invite", post(users::invite))
        .route("/users/{id}/password", post(users::set_password))
        .route("/users/{id}/password/form", post(users::password_form))
        .route("/users/{id}/role", post(users::set_role))
        .route("/users/{id}/delete", post(users::delete))
        .route("/ui/stream/{id}", get(stream))
        .route("/ui/cover/{id}", get(cover))
        .layer(from_fn(require_datastar_on_post))
        .layer(from_fn_with_state(state.clone(), gate))
        .layer(axum::middleware::map_response(stamp_stylesheet));
    // A plain form, since it answers with a redirect to the client: it proves
    // its origin the way the sign-in form does.
    let consent = axum::Router::new()
        .route(
            "/oauth/authorize",
            get(oauth::authorize).post(oauth::approve),
        )
        .layer(from_fn_with_state(state.clone(), gate));
    // Approving a device waiting to sign in: plain forms too, reached from a
    // phone that may never have opened the UI. See `crate::pair`.
    let pairing = axum::Router::new()
        .route("/pair", get(pair::form))
        .route("/pair/{pair}", get(pair::confirm))
        .route("/pair/{pair}/approve", post(pair::approve))
        .route("/pair/{pair}/decline", post(pair::decline))
        .layer(from_fn_with_state(state.clone(), gate));
    // Checking a password is deliberately expensive, so the form shares the
    // JSON login's per-IP window.
    let sign_in = get(session::login_form).merge(
        post(session::login).layer(from_fn_with_state(state.auth.clone(), login_rate_limit)),
    );
    // Making the first admin hashes a password, so it shares sign-in's window.
    let setup = get(setup::form)
        .merge(post(setup::create).layer(from_fn_with_state(state.auth.clone(), login_rate_limit)));
    axum::Router::new()
        .merge(gated)
        .merge(consent)
        .merge(pairing)
        .route(
            "/.well-known/oauth-protected-resource",
            get(oauth::protected_resource),
        )
        .route(oauth::RESOURCE_METADATA, get(oauth::protected_resource))
        .route(
            "/.well-known/oauth-authorization-server",
            get(oauth::authorization_server),
        )
        // Unauthenticated, so capped per IP: registering stores nothing, but
        // signs a client id each time.
        .route(
            "/oauth/register",
            post(oauth::register)
                .layer(axum::extract::DefaultBodyLimit::max(
                    oauth::MAX_REGISTRATION_BODY,
                ))
                .layer(from_fn_with_state(
                    Arc::new(RateLimiter::new(3600, 10)),
                    rate_limit,
                )),
        )
        .route(
            "/oauth/token",
            post(oauth::token).layer(from_fn_with_state(
                Arc::new(RateLimiter::new(60, 60)),
                rate_limit,
            )),
        )
        .route("/login", sign_in)
        .route("/setup", setup)
        .route("/auth/resume", get(session::resume))
        .route(session::PROXY_RESUME, get(session::proxy_resume))
        .route("/ui/renew", post(session::proxy_renew))
        .route("/auth/renew", post(session::renew))
        .route("/auth/signout", post(session::signout))
        .route("/ui/assets/{name}", get(ui_asset))
        // Where anything that wants an icon for this host looks first, before
        // reading a page: without it, a favicon service settles for the parent
        // domain's.
        .route(
            "/favicon.ico",
            get(|| ui_asset(Path("icon-192.png".into()), RawQuery(None))),
        )
        .route(
            "/apple-touch-icon.png",
            get(|| ui_asset(Path("apple-touch-icon.png".into()), RawQuery(None))),
        )
        .merge(path_inserted_discovery(&base))
        // The default predicate skips `text/event-stream`, since an encoder
        // buffers a live stream, and images. A body served by byte range is
        // left alone too: a range of a compressed body is not the range asked for.
        .layer(
            CompressionLayer::new().compress_when(DefaultPredicate::new().and(
                |_: StatusCode, _: Version, headers: &HeaderMap, _: &Extensions| {
                    !headers.contains_key(header::ACCEPT_RANGES)
                },
            )),
        )
        .with_state(state)
}

/// Under a path, where RFC 8414 and RFC 9728 put the metadata: between the
/// host and the path (`/.well-known/oauth-authorization-server/koan`), outside
/// what a proxy forwards for the path. It reaches here when the proxy forwards
/// that too; see `crate::base`.
fn path_inserted_discovery(base: &str) -> axum::Router<UiState> {
    if base.is_empty() || crate::base::problem(base).is_some() {
        return axum::Router::new();
    }
    axum::Router::new()
        .route(
            &format!("/.well-known/oauth-authorization-server{base}"),
            get(oauth::authorization_server),
        )
        .route(
            &format!("/.well-known/oauth-protected-resource{base}/mcp"),
            get(oauth::protected_resource),
        )
}

/// Which stylesheet the markup was written for. A tab open across an upgrade
/// keeps the old one while navigation and patches bring new markup; ui.js
/// swaps the stylesheet when this names another.
async fn stamp_stylesheet(mut res: Response) -> Response {
    if let Ok(v) = HeaderValue::from_str(&ASSETS.css_hash) {
        res.headers_mut().insert("x-koan-css", v);
    }
    res
}

async fn ui_asset(Path(name): Path<String>, query: RawQuery) -> Response {
    const JS: &str = "text/javascript; charset=utf-8";
    match name.as_str() {
        "ui.css" => asset(UI_CSS, "text/css; charset=utf-8", query),
        "ui.js" => asset(UI_JS, JS, query),
        "player.js" => asset(crate::share::ENGINE_JS, JS, query),
        "datastar.js" => asset(DATASTAR_JS, JS, query),
        other => crate::share::binary_asset(other).unwrap_or_else(not_found),
    }
}

fn cookie<'a>(headers: &'a HeaderMap, name: &str) -> Option<&'a str> {
    headers
        .get_all(header::COOKIE)
        .iter()
        .filter_map(|v| v.to_str().ok())
        .flat_map(|v| v.split(';'))
        .find_map(|c| c.trim().strip_prefix(name)?.strip_prefix('='))
}

/// A request the UI's script makes rather than a page the browser navigates to.
/// Such a request cannot follow a redirect to a sign-in page usefully, so it
/// is refused outright and the script reloads.
fn is_navigation(req: &Request) -> bool {
    req.method() == Method::GET
        && !req.headers().contains_key(PARTIAL)
        && !req.headers().contains_key("datastar-request")
        && !req.uri().path().starts_with("/ui/")
}

/// Let a signed-in user through; send a page load to resume its session, and
/// refuse anything else. Behind an authenticating proxy a session is good only
/// for the account the proxy names, so a browser whose proxy sign-in changed
/// hands over to the new account, and a header from the proxy that names no
/// one account lets no session through.
async fn gate(State(s): State<UiState>, mut req: Request, next: Next) -> Response {
    let user = if s.auth_enabled {
        let vouched = session::vouched(&s, req.headers(), req.extensions());
        if vouched == session::Vouch::Unusable {
            return session::unusable_header(&s);
        }
        let claims = cookie(req.headers(), "koan_access")
            .and_then(|t| auth::validate_access_token(&s.auth.public_pem, t).ok());
        match (claims, vouched) {
            (Some(claims), session::Vouch::Absent) => {
                crate::auth::current_user(&s.pool, claims).await
            }
            (Some(claims), session::Vouch::Named(name)) if name == claims.username => {
                crate::auth::current_user(&s.pool, claims).await
            }
            _ => None,
        }
    } else {
        Some(AuthUser::anonymous_admin())
    };
    match user {
        Some(user) => {
            req.extensions_mut().insert(user);
            next.run(req).await
        }
        None if is_navigation(&req) => {
            let here = req
                .uri()
                .path_and_query()
                .map_or("/", |p| p.as_str())
                .to_owned();
            let resume = if s.proxy_auth.is_some() {
                session::PROXY_RESUME
            } else {
                "/auth/resume"
            };
            see_other(&format!("{resume}?next={}", encode(&here)))
        }
        None => (
            StatusCode::UNAUTHORIZED,
            [(header::CACHE_CONTROL, "no-store")],
            "signed out",
        )
            .into_response(),
    }
}

/// Datastar sends this header on every request it makes, and a cross-site form
/// or a CORS-safelisted fetch cannot set it: a state-changing POST without it
/// did not come from this UI.
async fn require_datastar_on_post(req: Request, next: Next) -> Response {
    if req.method() == Method::POST && !req.headers().contains_key("datastar-request") {
        return StatusCode::FORBIDDEN.into_response();
    }
    next.run(req).await
}

fn encode(s: &str) -> String {
    form_urlencoded::byte_serialize(s.as_bytes()).collect()
}

fn see_other(location: &str) -> Response {
    (
        StatusCode::SEE_OTHER,
        [
            (header::LOCATION, location),
            (header::CACHE_CONTROL, "no-store"),
        ],
    )
        .into_response()
}

/// An HTML page with the UI's security headers.
fn html(status: StatusCode, body: impl Into<String>) -> Response {
    let mut resp = (status, body.into()).into_response();
    let h = resp.headers_mut();
    h.insert(
        header::CONTENT_TYPE,
        HeaderValue::from_static("text/html; charset=utf-8"),
    );
    h.insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
    h.insert(header::VARY, HeaderValue::from_static("x-koan-partial"));
    h.insert(header::CONTENT_SECURITY_POLICY, PAGE_CSP_HEADER.clone());
    h.insert(
        header::REFERRER_POLICY,
        HeaderValue::from_static("same-origin"),
    );
    h.insert(
        header::X_CONTENT_TYPE_OPTIONS,
        HeaderValue::from_static("nosniff"),
    );
    h.insert(
        "x-robots-tag",
        HeaderValue::from_static("noindex, nofollow"),
    );
    resp
}

/// A Datastar `patch-elements` event. Without a selector the element replaces
/// the one with its id; with one, `mode` says where it goes.
fn patch(html: &str, target: Option<(&str, &str)>) -> Event {
    let mut lines = Vec::new();
    if let Some((selector, mode)) = target {
        lines.push(format!("selector {selector}"));
        lines.push(format!("mode {mode}"));
    }
    lines.extend(html.lines().map(|l| format!("elements {l}")));
    Event::default()
        .event("datastar-patch-elements")
        .data(lines.join("\n"))
}

fn events(events: Vec<Event>) -> Response {
    let stream = tokio_stream::iter(events.into_iter().map(Ok::<_, std::convert::Infallible>));
    let mut resp = Sse::new(stream).into_response();
    resp.headers_mut()
        .insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
    resp
}

fn open(pool: &Pool) -> Option<Handle<'_>> {
    pool.get()
        .inspect_err(|e| log::error!("web UI: cannot open the database: {e}"))
        .ok()
}

/// A failed read as the page's empty or not-found state, logged where it
/// happened so that a broken database is not mistaken for a missing row.
pub(crate) trait Logged<T> {
    fn logged(self) -> Option<T>;
}

impl<T, E: std::fmt::Display> Logged<T> for Result<T, E> {
    #[track_caller]
    fn logged(self) -> Option<T> {
        let at = std::panic::Location::caller();
        self.inspect_err(|e| {
            log::error!("web UI: a read failed at {}:{}: {e}", at.file(), at.line())
        })
        .ok()
    }
}

/// A track's audio, from a local file; Range requests are honoured, so the
/// browser can seek a stream.
async fn stream(State(s): State<UiState>, Path(id): Path<i64>, headers: HeaderMap) -> Response {
    let path = blocking(move || {
        let db = open(&s.pool)?;
        let t = queries::tracks_by_ids(&db.conn, &[id]).logged()?.pop()?;
        crate::subsonic::track_file_path(&t).map(PathBuf::from)
    })
    .await;
    let Some(path) = path else {
        return not_found();
    };
    match crate::subsonic::serve_local_file(&path, &headers).await {
        Ok(mut resp) => {
            resp.headers_mut().insert(
                header::CACHE_CONTROL,
                HeaderValue::from_static("private, max-age=3600"),
            );
            resp
        }
        Err(_) => not_found(),
    }
}

/// Query parameters for `cover`.
#[derive(serde::Deserialize, Default)]
#[serde(default)]
struct CoverQuery {
    size: Option<u32>,
    /// The album's cover version, from `pages::cover_url`. With it the URL
    /// names these exact bytes, so the browser may keep them for good.
    v: Option<String>,
}

/// An album's cover at one of `covers::SIZES`, from the art embedded in the
/// first of its tracks that has any.
async fn cover(
    State(s): State<UiState>,
    Path(id): Path<i64>,
    axum::extract::Query(q): axum::extract::Query<CoverQuery>,
) -> Response {
    let size = crate::covers::snap(q.size);
    let found = blocking(move || {
        let tracks = queries::tracks_for_album(&open(&s.pool)?.conn, id).logged()?;
        (!tracks.is_empty()).then(|| s.covers.cover(&tracks, size))
    })
    .await;
    match found {
        Some(Some(art)) => crate::share::jpeg(Some(art), q.v.is_some()),
        // A record with no artwork draws what the apps draw, not a broken
        // image. Not kept for good: art added beside the files changes no
        // track's mtime, so the URL stays the same when it arrives.
        Some(None) => (
            [
                (header::CONTENT_TYPE, "image/svg+xml"),
                (header::CACHE_CONTROL, "private, max-age=3600"),
            ],
            NO_COVER_SVG,
        )
            .into_response(),
        None => not_found(),
    }
}