Improved release editor

Cargo.lock

@@ -1418,7 +1418,7 @@ checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c"
 
 [[package]]
 name = "furumusic"
-version = "0.2.15"
+version = "0.4.3"
 dependencies = [
  "anyhow",
  "async-trait",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "furumusic"
-version = "0.3.1"
+version = "0.4.4"
 edition = "2024"
 description = "Reusable web-app boilerplate: auth, OIDC/SSO, admin panel, user management, i18n, PostgreSQL"
 

src/admin/mod.rs

@@ -555,6 +555,32 @@ impl App for AdminApp {
                 },
                 "admin_v2_library_item_detail",
             ),
+            Route::with_handler_and_name(
+                "/v2/api/library/tracks/search",
+                {
+                    let pool = Arc::clone(&pool);
+                    let pool_config = Arc::clone(&pool_config);
+                    get(move |session: Session,
+                              db: Database,
+                              query: UrlQuery<v2::TrackSearchQuery>| {
+                        let pool = Arc::clone(&pool);
+                        let pool_config = Arc::clone(&pool_config);
+                        async move {
+                            let pg_pool = pool
+                                .get_or_init(|| async {
+                                    sqlx::postgres::PgPoolOptions::new()
+                                        .max_connections(5)
+                                        .connect(&pool_config.database_url)
+                                        .await
+                                        .expect("admin pool")
+                                })
+                                .await;
+                            v2::track_search(session, db, pg_pool, query.0).await
+                        }
+                    })
+                },
+                "admin_v2_library_tracks_search",
+            ),
             Route::with_handler_and_name(
                 "/v2/api/library/item/image",
                 {
@@ -1324,6 +1350,9 @@ impl App for AdminApp {
         all.extend(cot::db::migrations::wrap_migrations(
             crate::scheduler::db_migrations::MIGRATIONS,
         ));
+        all.extend(cot::db::migrations::wrap_migrations(
+            crate::auth::db_migrations::MIGRATIONS,
+        ));
         all
     }
 }

src/admin/v2.rs

@@ -110,6 +110,7 @@ pub(super) struct UpdateLibraryItemRequest {
     #[serde(default, deserialize_with = "deserialize_optional_stringish")]
     disc_number: Option<String>,
     artist_ids: Option<Vec<i64>>,
+    release_tracks: Option<Vec<ReleaseTrackUpdateRequest>>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -118,6 +119,21 @@ pub(super) struct LibraryItemDetailQuery {
     id: i64,
 }
 
+#[derive(Debug, Deserialize)]
+pub(super) struct TrackSearchQuery {
+    search: Option<String>,
+    limit: Option<i64>,
+}
+
+#[derive(Debug, Deserialize)]
+struct ReleaseTrackUpdateRequest {
+    id: i64,
+    #[serde(default, deserialize_with = "deserialize_optional_stringish")]
+    track_number: Option<String>,
+    #[serde(default, deserialize_with = "deserialize_optional_stringish")]
+    disc_number: Option<String>,
+}
+
 #[derive(Debug, Deserialize)]
 pub(super) struct SetLibraryImageRequest {
     kind: String,
@@ -538,6 +554,7 @@ struct LibraryItemDetailDto {
     selected_artist_ids: Vec<i64>,
     artists: Vec<ArtistOptionDto>,
     releases: Vec<ReleaseOptionDto>,
+    release_tracks: Vec<ReleaseTrackDto>,
     available_covers: Vec<AvailableCoverDto>,
     metadata_tags: Vec<MetadataTagDto>,
 }
@@ -555,6 +572,19 @@ struct ReleaseOptionDto {
     subtitle: String,
 }
 
+#[derive(Debug, Serialize, JsonSchema)]
+struct ReleaseTrackDto {
+    id: i64,
+    title: String,
+    artists: String,
+    release_id: Option<i64>,
+    release_title: Option<String>,
+    track_number: Option<i32>,
+    disc_number: Option<i32>,
+    duration_seconds: f64,
+    is_hidden: bool,
+}
+
 #[derive(Debug, Serialize, JsonSchema)]
 struct AvailableCoverDto {
     media_file_id: i64,
@@ -651,6 +681,19 @@ struct LibraryItemRow {
     updated_at: Option<String>,
 }
 
+#[derive(Debug, sqlx::FromRow)]
+struct ReleaseTrackRow {
+    id: i64,
+    title: String,
+    artists: String,
+    release_id: Option<i64>,
+    release_title: Option<String>,
+    track_number: Option<i32>,
+    disc_number: Option<i32>,
+    duration_seconds: f64,
+    is_hidden: bool,
+}
+
 pub async fn page(admin: AuthenticatedUser, i18n: I18n) -> cot::Result<Html> {
     let template = AdminV2Template {
         t: i18n.t,
@@ -1289,6 +1332,21 @@ pub async fn library_item_detail(
         return Ok(response);
     }
     let kind = normalize_library_kind(Some(query.kind.as_str()));
+    if kind == "releases" && query.id == 0 {
+        let item = LibraryItemDto {
+            id: 0,
+            kind: kind.clone(),
+            title: String::new(),
+            subtitle: String::new(),
+            is_hidden: Some(false),
+            tags: Vec::new(),
+            updated_at: None,
+        };
+        let detail = load_library_item_detail(pool, &kind, item)
+            .await
+            .map_err(|e| cot::Error::internal(e.to_string()))?;
+        return Json(detail).into_response();
+    }
     let Some(item) = fetch_library_item(pool, &kind, query.id)
         .await
         .map_err(|e| cot::Error::internal(e.to_string()))?
@@ -1301,6 +1359,25 @@ pub async fn library_item_detail(
     Json(detail).into_response()
 }
 
+pub async fn track_search(
+    session: Session,
+    db: Database,
+    pool: &PgPool,
+    query: TrackSearchQuery,
+) -> cot::Result<cot::response::Response> {
+    if let Err(response) = require_admin_json(&session, &db).await {
+        return Ok(response);
+    }
+
+    let Some(search) = clean_search(query.search.as_deref()) else {
+        return Json(Vec::<ReleaseTrackDto>::new()).into_response();
+    };
+    let tracks = search_tracks(pool, &search, query.limit.unwrap_or(16).clamp(1, 40))
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    Json(tracks).into_response()
+}
+
 pub async fn update_library_item(
     session: Session,
     db: Database,
@@ -1318,6 +1395,19 @@ pub async fn update_library_item(
     }
 
     let now = now_string();
+    if kind == "releases" && body.id == 0 {
+        let release_id = create_release_library_item(pool, &body, title, &now)
+            .await
+            .map_err(|e| cot::Error::internal(e.to_string()))?;
+        let Some(item) = fetch_library_item(pool, &kind, release_id)
+            .await
+            .map_err(|e| cot::Error::internal(e.to_string()))?
+        else {
+            return Ok(json_error(StatusCode::NOT_FOUND, "library item not found"));
+        };
+        return Json(item).into_response();
+    }
+
     let affected = match kind.as_str() {
         "artists" => {
             sqlx::query(
@@ -1421,22 +1511,9 @@ pub async fn update_library_item(
             let mut seen_artist_ids = HashSet::new();
             artist_ids.retain(|id| *id > 0 && seen_artist_ids.insert(*id));
             if kind == "releases" {
-                sqlx::query("DELETE FROM furumusic__release_artist WHERE release_id = $1")
-                    .bind(body.id)
-                    .execute(pool)
+                set_release_artists(pool, body.id, &artist_ids)
                     .await
                     .map_err(|e| cot::Error::internal(e.to_string()))?;
-                for (position, artist_id) in artist_ids.iter().enumerate() {
-                    sqlx::query(
-                        "INSERT INTO furumusic__release_artist (release_id, artist_id, position) VALUES ($1, $2, $3)",
-                    )
-                    .bind(body.id)
-                    .bind(*artist_id)
-                    .bind(position as i32)
-                    .execute(pool)
-                    .await
-                    .map_err(|e| cot::Error::internal(e.to_string()))?;
-                }
             } else {
                 sqlx::query(
                     "DELETE FROM furumusic__track_artist WHERE track_id = $1 AND role = 'main'",
@@ -1460,6 +1537,14 @@ pub async fn update_library_item(
         }
     }
 
+    if kind == "releases" {
+        if let Some(release_tracks) = body.release_tracks.as_deref() {
+            update_release_tracks(pool, body.id, release_tracks, &now)
+                .await
+                .map_err(|e| cot::Error::internal(e.to_string()))?;
+        }
+    }
+
     let Some(item) = fetch_library_item(pool, &kind, body.id)
         .await
         .map_err(|e| cot::Error::internal(e.to_string()))?
@@ -2647,13 +2732,13 @@ async fn fetch_library_item(
         "tracks" => {
             sqlx::query_as::<_, LibraryItemRow>(
                 "SELECT t.id, t.title::text AS title, \
-                        CONCAT(r.title::text, COALESCE(' / #' || t.track_number::text, '')) AS subtitle, \
+                        CONCAT(COALESCE(r.title::text, 'No release'), COALESCE(' / #' || t.track_number::text, '')) AS subtitle, \
                         t.is_hidden, COUNT(DISTINCT ta.artist_id)::bigint AS primary_count, \
                         COUNT(DISTINCT ph.id)::bigint AS secondary_count, \
                         COUNT(DISTINCT pt.playlist_id)::bigint AS tertiary_count, \
                         t.updated_at::text AS updated_at \
                  FROM furumusic__track t \
-                 JOIN furumusic__release r ON r.id = t.release_id \
+                 LEFT JOIN furumusic__release r ON r.id = t.release_id \
                  LEFT JOIN furumusic__track_artist ta ON ta.track_id = t.id \
                  LEFT JOIN furumusic__play_history ph ON ph.track_id = t.id \
                  LEFT JOIN furumusic__playlist_track pt ON pt.track_id = t.id \
@@ -2704,6 +2789,7 @@ async fn load_library_item_detail(
         selected_artist_ids: Vec::new(),
         artists: Vec::new(),
         releases: Vec::new(),
+        release_tracks: Vec::new(),
         available_covers: Vec::new(),
         metadata_tags: load_metadata_tags(pool, kind, item.id).await?,
         item,
@@ -2744,16 +2830,22 @@ async fn load_library_item_detail(
             .map(|row| row.id)
             .collect();
             detail.artists = load_artist_options(pool).await?;
+            if detail.item.id > 0 {
+                detail.release_tracks = load_release_tracks(pool, detail.item.id).await?;
+            }
         }
         "tracks" => {
-            let row: Option<(i64, Option<i32>, Option<i32>, Option<i32>)> = sqlx::query_as(
-                "SELECT release_id, track_number, disc_number, year FROM furumusic__track WHERE id = $1",
+            let row: Option<(Option<i64>, Option<i32>, Option<i32>, Option<i32>)> = sqlx::query_as(
+                "SELECT r.id AS release_id, t.track_number, t.disc_number, t.year \
+                 FROM furumusic__track t \
+                 LEFT JOIN furumusic__release r ON r.id = t.release_id \
+                 WHERE t.id = $1",
             )
             .bind(detail.item.id)
             .fetch_optional(pool)
             .await?;
             if let Some((release_id, track_number, disc_number, year)) = row {
-                detail.release_id = Some(release_id);
+                detail.release_id = release_id;
                 detail.track_number = track_number;
                 detail.disc_number = disc_number;
                 detail.year = year;
@@ -2901,6 +2993,210 @@ async fn load_release_options(pool: &PgPool) -> anyhow::Result<Vec<ReleaseOption
         .collect())
 }
 
+async fn create_release_library_item(
+    pool: &PgPool,
+    body: &UpdateLibraryItemRequest,
+    title: &str,
+    now: &str,
+) -> anyhow::Result<i64> {
+    let release_type = body
+        .release_type
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .unwrap_or("album");
+    let year = body
+        .year
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .and_then(|value| value.parse::<i32>().ok());
+    let release_id: i64 = sqlx::query_scalar(
+        "INSERT INTO furumusic__release \
+           (title, title_sort, release_type, year, cover_file_id, total_tracks, total_discs, is_hidden, model_name, created_at, updated_at) \
+         VALUES ($1, $2, $3, $4, NULL, NULL, NULL, $5, NULL, $6, $6) \
+         RETURNING id",
+    )
+    .bind(title)
+    .bind(normalize_name(title))
+    .bind(release_type)
+    .bind(year)
+    .bind(body.hidden)
+    .bind(now)
+    .fetch_one(pool)
+    .await?;
+
+    if let Some(artist_ids) = body.artist_ids.as_deref() {
+        set_release_artists(pool, release_id, artist_ids).await?;
+    }
+    if let Some(release_tracks) = body.release_tracks.as_deref() {
+        update_release_tracks(pool, release_id, release_tracks, now).await?;
+    }
+
+    Ok(release_id)
+}
+
+async fn set_release_artists(
+    pool: &PgPool,
+    release_id: i64,
+    artist_ids: &[i64],
+) -> anyhow::Result<()> {
+    sqlx::query("DELETE FROM furumusic__release_artist WHERE release_id = $1")
+        .bind(release_id)
+        .execute(pool)
+        .await?;
+
+    let mut seen_artist_ids = HashSet::new();
+    let unique_artist_ids = artist_ids
+        .iter()
+        .copied()
+        .filter(|id| *id > 0 && seen_artist_ids.insert(*id))
+        .collect::<Vec<_>>();
+
+    for (position, artist_id) in unique_artist_ids.iter().enumerate() {
+        sqlx::query(
+            "INSERT INTO furumusic__release_artist (release_id, artist_id, position) VALUES ($1, $2, $3)",
+        )
+        .bind(release_id)
+        .bind(*artist_id)
+        .bind(position as i32)
+        .execute(pool)
+        .await?;
+    }
+
+    Ok(())
+}
+
+async fn load_release_tracks(
+    pool: &PgPool,
+    release_id: i64,
+) -> anyhow::Result<Vec<ReleaseTrackDto>> {
+    let rows = sqlx::query_as::<_, ReleaseTrackRow>(
+        "SELECT t.id, t.title::text AS title, \
+                COALESCE(NULLIF(STRING_AGG(DISTINCT a.name::text, ', '), ''), 'Unknown artist') AS artists, \
+                NULLIF(t.release_id, 0) AS release_id, r.title::text AS release_title, \
+                t.track_number, t.disc_number, t.duration_seconds, t.is_hidden \
+         FROM furumusic__track t \
+         LEFT JOIN furumusic__release r ON r.id = t.release_id \
+         LEFT JOIN furumusic__track_artist ta ON ta.track_id = t.id AND ta.role = 'main' \
+         LEFT JOIN furumusic__artist a ON a.id = ta.artist_id \
+         WHERE t.release_id = $1 \
+         GROUP BY t.id, r.id, r.title \
+         ORDER BY t.disc_number NULLS FIRST, t.track_number NULLS LAST, t.title ASC, t.id ASC",
+    )
+    .bind(release_id)
+    .fetch_all(pool)
+    .await?;
+    Ok(rows.into_iter().map(release_track_dto).collect())
+}
+
+async fn search_tracks(
+    pool: &PgPool,
+    search: &str,
+    limit: i64,
+) -> anyhow::Result<Vec<ReleaseTrackDto>> {
+    let pattern = format!("%{search}%");
+    let starts_with = format!("{search}%");
+    let rows = sqlx::query_as::<_, ReleaseTrackRow>(
+        "SELECT t.id, t.title::text AS title, \
+                COALESCE(NULLIF(STRING_AGG(DISTINCT a.name::text, ', '), ''), 'Unknown artist') AS artists, \
+                NULLIF(t.release_id, 0) AS release_id, r.title::text AS release_title, \
+                t.track_number, t.disc_number, t.duration_seconds, t.is_hidden \
+         FROM furumusic__track t \
+         LEFT JOIN furumusic__release r ON r.id = t.release_id \
+         LEFT JOIN furumusic__track_artist ta ON ta.track_id = t.id AND ta.role = 'main' \
+         LEFT JOIN furumusic__artist a ON a.id = ta.artist_id \
+         WHERE t.title ILIKE $1 OR COALESCE(r.title::text, '') ILIKE $1 OR COALESCE(a.name::text, '') ILIKE $1 \
+         GROUP BY t.id, r.id, r.title \
+         ORDER BY CASE \
+                    WHEN LOWER(t.title::text) = LOWER($2) THEN 0 \
+                    WHEN t.title ILIKE $3 THEN 1 \
+                    ELSE 2 \
+                  END, \
+                  t.title_sort ASC, t.id ASC \
+         LIMIT $4",
+    )
+    .bind(pattern)
+    .bind(search)
+    .bind(starts_with)
+    .bind(limit)
+    .fetch_all(pool)
+    .await?;
+    Ok(rows.into_iter().map(release_track_dto).collect())
+}
+
+async fn update_release_tracks(
+    pool: &PgPool,
+    release_id: i64,
+    tracks: &[ReleaseTrackUpdateRequest],
+    now: &str,
+) -> anyhow::Result<()> {
+    let mut seen_ids = HashSet::new();
+    let selected = tracks
+        .iter()
+        .filter(|track| track.id > 0 && seen_ids.insert(track.id))
+        .collect::<Vec<_>>();
+    let selected_ids = selected.iter().map(|track| track.id).collect::<Vec<_>>();
+
+    let mut tx = pool.begin().await?;
+    if selected_ids.is_empty() {
+        sqlx::query(
+            "UPDATE furumusic__track \
+             SET release_id = 0, updated_at = $2 \
+             WHERE release_id = $1",
+        )
+        .bind(release_id)
+        .bind(now)
+        .execute(&mut *tx)
+        .await?;
+    } else {
+        sqlx::query(
+            "UPDATE furumusic__track \
+             SET release_id = 0, updated_at = $2 \
+             WHERE release_id = $1 AND id <> ALL($3)",
+        )
+        .bind(release_id)
+        .bind(now)
+        .bind(&selected_ids)
+        .execute(&mut *tx)
+        .await?;
+    }
+
+    for track in selected {
+        let track_number = parse_optional_admin_i32(track.track_number.as_deref(), 1, 9999);
+        let disc_number = parse_optional_admin_i32(track.disc_number.as_deref(), 1, 999);
+        sqlx::query(
+            "UPDATE furumusic__track \
+             SET release_id = $1, track_number = $2, disc_number = $3, updated_at = $4 \
+             WHERE id = $5",
+        )
+        .bind(release_id)
+        .bind(track_number)
+        .bind(disc_number)
+        .bind(now)
+        .bind(track.id)
+        .execute(&mut *tx)
+        .await?;
+    }
+
+    tx.commit().await?;
+    Ok(())
+}
+
+fn release_track_dto(row: ReleaseTrackRow) -> ReleaseTrackDto {
+    ReleaseTrackDto {
+        id: row.id,
+        title: row.title,
+        artists: row.artists,
+        release_id: row.release_id,
+        release_title: row.release_title,
+        track_number: row.track_number,
+        disc_number: row.disc_number,
+        duration_seconds: row.duration_seconds,
+        is_hidden: row.is_hidden,
+    }
+}
+
 async fn artist_available_covers(
     pool: &PgPool,
     artist_id: i64,
@@ -2943,7 +3239,7 @@ async fn library_ids_by_filter(
         "tracks" => QueryBuilder::<Postgres>::new(
             "SELECT DISTINCT t.id \
              FROM furumusic__track t \
-             JOIN furumusic__release r ON r.id = t.release_id \
+             LEFT JOIN furumusic__release r ON r.id = t.release_id \
              LEFT JOIN furumusic__track_artist ta ON ta.track_id = t.id \
              LEFT JOIN furumusic__artist a ON a.id = ta.artist_id WHERE 1=1",
         ),
@@ -3182,7 +3478,7 @@ async fn count_library(
         "tracks" => QueryBuilder::<Postgres>::new(
             "SELECT COUNT(DISTINCT t.id) AS count \
              FROM furumusic__track t \
-             JOIN furumusic__release r ON r.id = t.release_id \
+             LEFT JOIN furumusic__release r ON r.id = t.release_id \
              LEFT JOIN furumusic__track_artist ta ON ta.track_id = t.id \
              LEFT JOIN furumusic__artist a ON a.id = ta.artist_id WHERE 1=1",
         ),
@@ -3319,13 +3615,13 @@ async fn load_track_items(
 ) -> anyhow::Result<Vec<LibraryItemRow>> {
     let mut qb = QueryBuilder::<Postgres>::new(
         "SELECT t.id, t.title::text AS title, \
-                CONCAT(r.title::text, COALESCE(' / #' || t.track_number::text, '')) AS subtitle, \
+                CONCAT(COALESCE(r.title::text, 'No release'), COALESCE(' / #' || t.track_number::text, '')) AS subtitle, \
                 t.is_hidden, COUNT(DISTINCT ta.artist_id)::bigint AS primary_count, \
                 COUNT(DISTINCT ph.id)::bigint AS secondary_count, \
                 COUNT(DISTINCT pt.playlist_id)::bigint AS tertiary_count, \
                 t.updated_at::text AS updated_at \
          FROM furumusic__track t \
-         JOIN furumusic__release r ON r.id = t.release_id \
+         LEFT JOIN furumusic__release r ON r.id = t.release_id \
          LEFT JOIN furumusic__track_artist ta ON ta.track_id = t.id \
          LEFT JOIN furumusic__artist a ON a.id = ta.artist_id \
          LEFT JOIN furumusic__play_history ph ON ph.track_id = t.id \
@@ -3341,7 +3637,7 @@ async fn load_track_items(
         qb.push_bind(pattern);
         qb.push(")");
     }
-    qb.push(" GROUP BY t.id, r.title ORDER BY r.title ASC, t.disc_number NULLS FIRST, t.track_number NULLS FIRST, t.title ASC LIMIT ");
+    qb.push(" GROUP BY t.id, r.title ORDER BY COALESCE(r.title::text, '') ASC, t.disc_number NULLS FIRST, t.track_number NULLS FIRST, t.title ASC LIMIT ");
     qb.push_bind(limit);
     qb.push(" OFFSET ");
     qb.push_bind(offset);

src/agent/cover_variants.rs

@@ -96,17 +96,11 @@ fn generate_missing_variants_sync(
             image::ExtendedColorType::Rgb8,
         );
         match result {
-            Ok(()) => crate::metrics::record_agent_cover_variant(
-                variant.name,
-                "ok",
-                start.elapsed(),
-            ),
+            Ok(()) => {
+                crate::metrics::record_agent_cover_variant(variant.name, "ok", start.elapsed())
+            }
             Err(err) => {
-                crate::metrics::record_agent_cover_variant(
-                    variant.name,
-                    "error",
-                    start.elapsed(),
-                );
+                crate::metrics::record_agent_cover_variant(variant.name, "error", start.elapsed());
                 return Err(err.into());
             }
         }

src/api/mod.rs

@@ -1,14 +1,27 @@
+use std::marker::PhantomData;
+
+use cot::aide::openapi::{
+    MediaType, Operation, ReferenceOr, RequestBody, Response as OpenApiResponse, SchemaObject,
+    StatusCode as OpenApiStatusCode,
+};
+use cot::auth::PasswordVerificationResult;
+use cot::common_types::Password;
 use cot::db::Database;
+use cot::http::StatusCode;
+use cot::http::header::CONTENT_TYPE;
 use cot::json::Json;
+use cot::openapi::{AsApiOperation, RouteContext};
 use cot::response::IntoResponse;
-use cot::router::method::openapi::api_get;
+use cot::router::method::openapi::{api_get, api_post};
 use cot::router::{Route, Router};
 use cot::session::Session;
-use cot::{App, Body};
-use schemars::JsonSchema;
-use serde::Serialize;
+use cot::{App, Body, RequestHandler};
+use schemars::{JsonSchema, SchemaGenerator};
+use serde::{Deserialize, Serialize};
 
 use crate::auth;
+use crate::config::AppConfig;
+use crate::user::User;
 
 // ---------------------------------------------------------------------------
 // JSON error helper
@@ -23,6 +36,199 @@ fn json_error(status: cot::http::StatusCode, message: &str) -> cot::response::Re
         .expect("valid response")
 }
 
+#[derive(Clone, Copy)]
+struct DocumentedJsonHandler<H, Req, Res> {
+    handler: H,
+    summary: &'static str,
+    _marker: PhantomData<fn(Req) -> Res>,
+}
+
+#[derive(Clone, Copy)]
+struct DocumentedResponseHandler<H, Res> {
+    handler: H,
+    summary: &'static str,
+    _marker: PhantomData<fn() -> Res>,
+}
+
+fn documented_json_handler<Req, Res, H>(
+    handler: H,
+    summary: &'static str,
+) -> DocumentedJsonHandler<H, Req, Res> {
+    DocumentedJsonHandler {
+        handler,
+        summary,
+        _marker: PhantomData,
+    }
+}
+
+fn documented_response_handler<Res, H>(
+    handler: H,
+    summary: &'static str,
+) -> DocumentedResponseHandler<H, Res> {
+    DocumentedResponseHandler {
+        handler,
+        summary,
+        _marker: PhantomData,
+    }
+}
+
+impl<HandlerParams, H, Req, Res> RequestHandler<HandlerParams>
+    for DocumentedJsonHandler<H, Req, Res>
+where
+    H: RequestHandler<HandlerParams> + Clone + Send + Sync + 'static,
+{
+    async fn handle(&self, request: cot::request::Request) -> cot::Result<cot::response::Response> {
+        self.handler.handle(request).await
+    }
+}
+
+impl<HandlerParams, H, Res> RequestHandler<HandlerParams> for DocumentedResponseHandler<H, Res>
+where
+    H: RequestHandler<HandlerParams> + Clone + Send + Sync + 'static,
+{
+    async fn handle(&self, request: cot::request::Request) -> cot::Result<cot::response::Response> {
+        self.handler.handle(request).await
+    }
+}
+
+impl<H, Req, Res> AsApiOperation for DocumentedJsonHandler<H, Req, Res>
+where
+    Req: JsonSchema,
+    Res: JsonSchema,
+{
+    fn as_api_operation(
+        &self,
+        _route_context: &RouteContext<'_>,
+        schema_generator: &mut SchemaGenerator,
+    ) -> Option<Operation> {
+        let mut operation = Operation {
+            summary: Some(self.summary.to_owned()),
+            ..Default::default()
+        };
+
+        let mut request_body = RequestBody {
+            required: true,
+            ..Default::default()
+        };
+        request_body.content.insert(
+            "application/json".to_owned(),
+            MediaType {
+                schema: Some(SchemaObject {
+                    json_schema: Req::json_schema(schema_generator),
+                    external_docs: None,
+                    example: None,
+                }),
+                ..Default::default()
+            },
+        );
+        operation.request_body = Some(ReferenceOr::Item(request_body));
+
+        let responses = operation.responses.get_or_insert_default();
+        let mut ok = OpenApiResponse {
+            description: "OK".to_owned(),
+            ..Default::default()
+        };
+        ok.content.insert(
+            "application/json".to_owned(),
+            MediaType {
+                schema: Some(SchemaObject {
+                    json_schema: Res::json_schema(schema_generator),
+                    external_docs: None,
+                    example: None,
+                }),
+                ..Default::default()
+            },
+        );
+        responses
+            .responses
+            .insert(OpenApiStatusCode::Code(200), ReferenceOr::Item(ok));
+
+        Some(operation)
+    }
+}
+
+impl<H, Res> AsApiOperation for DocumentedResponseHandler<H, Res>
+where
+    Res: JsonSchema,
+{
+    fn as_api_operation(
+        &self,
+        _route_context: &RouteContext<'_>,
+        schema_generator: &mut SchemaGenerator,
+    ) -> Option<Operation> {
+        let mut operation = Operation {
+            summary: Some(self.summary.to_owned()),
+            ..Default::default()
+        };
+        add_json_response::<Res>(&mut operation, schema_generator);
+        Some(operation)
+    }
+}
+
+fn add_json_response<Res: JsonSchema>(
+    operation: &mut Operation,
+    schema_generator: &mut SchemaGenerator,
+) {
+    let responses = operation.responses.get_or_insert_default();
+    let mut ok = OpenApiResponse {
+        description: "OK".to_owned(),
+        ..Default::default()
+    };
+    ok.content.insert(
+        "application/json".to_owned(),
+        MediaType {
+            schema: Some(SchemaObject {
+                json_schema: Res::json_schema(schema_generator),
+                external_docs: None,
+                example: None,
+            }),
+            ..Default::default()
+        },
+    );
+    responses
+        .responses
+        .insert(OpenApiStatusCode::Code(200), ReferenceOr::Item(ok));
+}
+
+fn is_json_content_type(value: &str) -> bool {
+    value
+        .split(';')
+        .next()
+        .map(str::trim)
+        .is_some_and(|media_type| media_type.eq_ignore_ascii_case("application/json"))
+}
+
+async fn parse_json_request<T>(
+    request: cot::request::Request,
+) -> cot::Result<Result<T, cot::response::Response>>
+where
+    T: for<'de> Deserialize<'de>,
+{
+    let content_type = request
+        .headers()
+        .get(CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .unwrap_or_default();
+    if !is_json_content_type(content_type) {
+        return Ok(Err(json_error(
+            StatusCode::UNSUPPORTED_MEDIA_TYPE,
+            "expected application/json",
+        )));
+    }
+
+    let bytes = request.into_body().into_bytes().await?;
+    let body = match serde_json::from_slice::<T>(&bytes) {
+        Ok(body) => body,
+        Err(_) => {
+            return Ok(Err(json_error(
+                StatusCode::BAD_REQUEST,
+                "invalid JSON body",
+            )));
+        }
+    };
+    Ok(Ok(body))
+}
+
 // ---------------------------------------------------------------------------
 // GET /api/me
 // ---------------------------------------------------------------------------
@@ -34,8 +240,85 @@ struct MeResponse {
     role: String,
 }
 
-async fn me_handler(session: Session, db: Database) -> cot::Result<cot::response::Response> {
-    let Some(user) = auth::get_session_user(&session, &db).await else {
+#[derive(Debug, Serialize, JsonSchema)]
+struct AuthUserResponse {
+    id: i64,
+    name: String,
+    role: String,
+}
+
+#[derive(Debug, Serialize, JsonSchema)]
+struct AuthTokenResponse {
+    access_token: String,
+    refresh_token: String,
+    token_type: String,
+    expires_in_seconds: i64,
+}
+
+#[derive(Debug, Serialize, JsonSchema)]
+struct AuthLoginResponse {
+    user: AuthUserResponse,
+    tokens: AuthTokenResponse,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+struct PasswordLoginRequest {
+    username: String,
+    password: String,
+    device_name: Option<String>,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+struct RefreshRequest {
+    refresh_token: String,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+struct SsoExchangeRequest {
+    code: String,
+    device_name: Option<String>,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+struct LogoutRequest {
+    refresh_token: Option<String>,
+}
+
+#[derive(Debug, Serialize, JsonSchema)]
+struct LogoutResponse {
+    revoked: bool,
+}
+
+fn user_response(user: auth::AuthenticatedUser) -> AuthUserResponse {
+    AuthUserResponse {
+        id: user.id,
+        name: user.name,
+        role: user.role.code().to_owned(),
+    }
+}
+
+fn token_response(tokens: auth::ApiTokenPair) -> AuthTokenResponse {
+    AuthTokenResponse {
+        access_token: tokens.access_token,
+        refresh_token: tokens.refresh_token,
+        token_type: tokens.token_type.to_owned(),
+        expires_in_seconds: tokens.expires_in_seconds,
+    }
+}
+
+fn login_response(user: auth::AuthenticatedUser, tokens: auth::ApiTokenPair) -> AuthLoginResponse {
+    AuthLoginResponse {
+        user: user_response(user),
+        tokens: token_response(tokens),
+    }
+}
+
+async fn me_handler(
+    auth_ctx: auth::AuthContext,
+    session: Session,
+    db: Database,
+) -> cot::Result<cot::response::Response> {
+    let Some(user) = auth::get_request_user(&auth_ctx, &session, &db).await else {
         return Ok(json_error(
             cot::http::StatusCode::UNAUTHORIZED,
             "not authenticated",
@@ -50,6 +333,146 @@ async fn me_handler(session: Session, db: Database) -> cot::Result<cot::response
     .into_response()
 }
 
+async fn password_login_handler(
+    db: Database,
+    raw_request: cot::request::Request,
+) -> cot::Result<cot::response::Response> {
+    let request = match parse_json_request::<PasswordLoginRequest>(raw_request).await? {
+        Ok(request) => request,
+        Err(response) => return Ok(response),
+    };
+
+    let (config, _) = AppConfig::load_with_db(&db).await;
+    if !config.auth_password_enabled {
+        crate::metrics::record_auth_attempt("api_password", "failure", "disabled");
+        return Ok(json_error(
+            StatusCode::FORBIDDEN,
+            "password login is disabled",
+        ));
+    }
+
+    let user = match User::get_by_username(&db, request.username.trim()).await {
+        Ok(Some(user)) if user.is_active() => user,
+        _ => {
+            crate::metrics::record_auth_attempt("api_password", "failure", "bad_credentials");
+            return Ok(json_error(
+                StatusCode::UNAUTHORIZED,
+                "invalid username or password",
+            ));
+        }
+    };
+
+    let Some(hash) = user.password_ref() else {
+        crate::metrics::record_auth_attempt("api_password", "failure", "bad_credentials");
+        return Ok(json_error(
+            StatusCode::UNAUTHORIZED,
+            "invalid username or password",
+        ));
+    };
+
+    match hash.verify(&Password::new(&request.password)) {
+        PasswordVerificationResult::Ok | PasswordVerificationResult::OkObsolete(_) => {
+            let auth_user = auth::AuthenticatedUser {
+                id: user.id_val(),
+                name: {
+                    let display = user.display_name_str();
+                    if display.is_empty() {
+                        user.username_str().to_owned()
+                    } else {
+                        display
+                    }
+                },
+                role: user.role(),
+            };
+            let tokens =
+                auth::create_api_session(&db, user.id_val(), request.device_name.as_deref())
+                    .await
+                    .map_err(|e| cot::Error::internal(e.to_string()))?;
+            crate::metrics::record_auth_attempt("api_password", "success", "ok");
+            crate::metrics::record_session_created("api_password");
+            Json(login_response(auth_user, tokens)).into_response()
+        }
+        PasswordVerificationResult::Invalid => {
+            crate::metrics::record_auth_attempt("api_password", "failure", "bad_credentials");
+            Ok(json_error(
+                StatusCode::UNAUTHORIZED,
+                "invalid username or password",
+            ))
+        }
+    }
+}
+
+async fn refresh_handler(
+    db: Database,
+    raw_request: cot::request::Request,
+) -> cot::Result<cot::response::Response> {
+    let request = match parse_json_request::<RefreshRequest>(raw_request).await? {
+        Ok(request) => request,
+        Err(response) => return Ok(response),
+    };
+
+    match auth::refresh_api_session(&db, request.refresh_token.trim()).await {
+        Ok(Some(tokens)) => Json(token_response(tokens)).into_response(),
+        Ok(None) => Ok(json_error(
+            StatusCode::UNAUTHORIZED,
+            "invalid refresh token",
+        )),
+        Err(err) => Err(cot::Error::internal(err.to_string())),
+    }
+}
+
+async fn sso_exchange_handler(
+    db: Database,
+    raw_request: cot::request::Request,
+) -> cot::Result<cot::response::Response> {
+    let request = match parse_json_request::<SsoExchangeRequest>(raw_request).await? {
+        Ok(request) => request,
+        Err(response) => return Ok(response),
+    };
+
+    match auth::exchange_mobile_code_for_api_session(
+        &db,
+        request.code.trim(),
+        request.device_name.as_deref(),
+    )
+    .await
+    {
+        Ok(Some((user, tokens))) => {
+            crate::metrics::record_auth_attempt("api_sso_exchange", "success", "ok");
+            crate::metrics::record_session_created("api_sso_exchange");
+            Json(login_response(user, tokens)).into_response()
+        }
+        Ok(None) => {
+            crate::metrics::record_auth_attempt("api_sso_exchange", "failure", "bad_code");
+            Ok(json_error(
+                StatusCode::UNAUTHORIZED,
+                "invalid SSO exchange code",
+            ))
+        }
+        Err(err) => Err(cot::Error::internal(err.to_string())),
+    }
+}
+
+async fn logout_handler(
+    auth_ctx: auth::AuthContext,
+    db: Database,
+    raw_request: cot::request::Request,
+) -> cot::Result<cot::response::Response> {
+    let request = match parse_json_request::<LogoutRequest>(raw_request).await? {
+        Ok(request) => request,
+        Err(response) => return Ok(response),
+    };
+
+    let revoked = auth::revoke_api_session(
+        &db,
+        auth_ctx.bearer_token(),
+        request.refresh_token.as_deref().map(str::trim),
+    )
+    .await
+    .map_err(|e| cot::Error::internal(e.to_string()))?;
+    Json(LogoutResponse { revoked }).into_response()
+}
+
 // ---------------------------------------------------------------------------
 // App
 // ---------------------------------------------------------------------------
@@ -62,10 +485,101 @@ impl App for ApiApp {
     }
 
     fn router(&self) -> Router {
-        Router::with_urls([Route::with_api_handler_and_name(
-            "/me",
-            api_get(me_handler),
-            "api_me",
-        )])
+        Router::with_urls([
+            Route::with_api_handler_and_name(
+                "/me",
+                api_get(documented_response_handler::<MeResponse, _>(
+                    me_handler,
+                    "Get the current authenticated user",
+                )),
+                "api_me",
+            ),
+            Route::with_api_handler_and_name(
+                "/auth/password",
+                api_post(documented_json_handler::<
+                    PasswordLoginRequest,
+                    AuthLoginResponse,
+                    _,
+                >(
+                    password_login_handler,
+                    "Log in with username and password",
+                )),
+                "api_auth_password",
+            ),
+            Route::with_api_handler_and_name(
+                "/auth/refresh",
+                api_post(documented_json_handler::<
+                    RefreshRequest,
+                    AuthTokenResponse,
+                    _,
+                >(
+                    refresh_handler, "Refresh an API token pair"
+                )),
+                "api_auth_refresh",
+            ),
+            Route::with_api_handler_and_name(
+                "/auth/sso/exchange",
+                api_post(documented_json_handler::<
+                    SsoExchangeRequest,
+                    AuthLoginResponse,
+                    _,
+                >(
+                    sso_exchange_handler,
+                    "Exchange a mobile SSO code for API tokens",
+                )),
+                "api_auth_sso_exchange",
+            ),
+            Route::with_api_handler_and_name(
+                "/auth/logout",
+                api_post(documented_json_handler::<LogoutRequest, LogoutResponse, _>(
+                    logout_handler,
+                    "Revoke an API session",
+                )),
+                "api_auth_logout",
+            ),
+        ])
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use cot::aide::openapi::{PathItem, ReferenceOr};
+
+    use super::*;
+
+    fn assert_get_path(paths: &cot::aide::openapi::Paths, path: &str) {
+        assert!(matches!(
+            paths.paths.get(path),
+            Some(ReferenceOr::Item(PathItem { get: Some(_), .. }))
+        ));
+    }
+
+    fn assert_post_path(paths: &cot::aide::openapi::Paths, path: &str) {
+        assert!(matches!(
+            paths.paths.get(path),
+            Some(ReferenceOr::Item(PathItem { post: Some(_), .. }))
+        ));
+    }
+
+    #[test]
+    fn openapi_includes_auth_routes() {
+        let openapi = ApiApp.router().as_api();
+        let paths = openapi.paths.expect("OpenAPI paths");
+
+        assert_get_path(&paths, "/me");
+        assert_post_path(&paths, "/auth/password");
+        assert_post_path(&paths, "/auth/refresh");
+        assert_post_path(&paths, "/auth/sso/exchange");
+        assert_post_path(&paths, "/auth/logout");
+
+        let Some(ReferenceOr::Item(PathItem {
+            post: Some(operation),
+            ..
+        })) = paths.paths.get("/auth/password")
+        else {
+            panic!("password auth path should be documented as POST");
+        };
+        assert!(operation.request_body.is_some());
+        assert!(operation.responses.is_some());
     }
 }

src/auth.rs

@@ -1,7 +1,13 @@
+use chrono::{Duration, Utc};
 use cot::Body;
-use cot::db::Database;
+use cot::db::{Auto, Database, LimitedString, Model};
+use cot::http::header::AUTHORIZATION;
+use cot::request::RequestHead;
+use cot::request::extractors::FromRequestHead;
 use cot::response::IntoResponse;
 use cot::session::Session;
+use serde::Serialize;
+use sha2::{Digest, Sha256};
 
 use crate::user::User;
 
@@ -46,11 +52,7 @@ pub struct AuthenticatedUser {
     pub role: Role,
 }
 
-/// Read `user_id` from the session, fetch the `User` from DB, return
-/// `AuthenticatedUser` if the user exists and is active.
-pub async fn get_session_user(session: &Session, db: &Database) -> Option<AuthenticatedUser> {
-    let user_id: i64 = session.get(SESSION_USER_ID).await.ok()??;
-    let user = User::get_by_id(db, user_id).await.ok()??;
+fn authenticated_user_from_user(user: User) -> Option<AuthenticatedUser> {
     if !user.is_active() {
         return None;
     }
@@ -70,6 +72,362 @@ pub async fn get_session_user(session: &Session, db: &Database) -> Option<Authen
     })
 }
 
+/// Read `user_id` from the session, fetch the `User` from DB, return
+/// `AuthenticatedUser` if the user exists and is active.
+pub async fn get_session_user(session: &Session, db: &Database) -> Option<AuthenticatedUser> {
+    let user_id: i64 = session.get(SESSION_USER_ID).await.ok()??;
+    let user = User::get_by_id(db, user_id).await.ok()??;
+    authenticated_user_from_user(user)
+}
+
+// ---------------------------------------------------------------------------
+// API bearer-token auth
+// ---------------------------------------------------------------------------
+
+const ACCESS_TOKEN_PREFIX: &str = "furu_at_";
+const REFRESH_TOKEN_PREFIX: &str = "furu_rt_";
+const MOBILE_EXCHANGE_CODE_PREFIX: &str = "furu_mx_";
+const ACCESS_TOKEN_TTL_MINUTES: i64 = 15;
+const REFRESH_TOKEN_TTL_DAYS: i64 = 60;
+const MOBILE_EXCHANGE_CODE_TTL_MINUTES: i64 = 3;
+
+#[derive(Debug, Clone, Default)]
+pub struct AuthContext {
+    bearer_token: Option<String>,
+}
+
+impl AuthContext {
+    pub fn bearer_token(&self) -> Option<&str> {
+        self.bearer_token.as_deref()
+    }
+}
+
+impl FromRequestHead for AuthContext {
+    async fn from_request_head(head: &RequestHead) -> cot::Result<Self> {
+        let bearer_token = head
+            .headers
+            .get(AUTHORIZATION)
+            .and_then(|value| value.to_str().ok())
+            .and_then(parse_bearer_token)
+            .map(str::to_owned);
+        Ok(Self { bearer_token })
+    }
+}
+
+fn parse_bearer_token(header: &str) -> Option<&str> {
+    let header = header.trim();
+    let (scheme, token) = header.split_once(' ')?;
+    if !scheme.eq_ignore_ascii_case("Bearer") {
+        return None;
+    }
+    let token = token.trim();
+    if token.is_empty() || token.len() > 512 {
+        return None;
+    }
+    Some(token)
+}
+
+#[derive(Debug, Serialize)]
+pub struct ApiTokenPair {
+    pub access_token: String,
+    pub refresh_token: String,
+    pub token_type: &'static str,
+    pub expires_in_seconds: i64,
+}
+
+#[derive(Debug, Clone)]
+#[cot::db::model]
+pub struct ApiSession {
+    #[model(primary_key)]
+    id: Auto<i64>,
+    user_id: i64,
+    device_name: Option<String>,
+    access_token_hash: LimitedString<128>,
+    refresh_token_hash: LimitedString<128>,
+    access_expires_at: String,
+    refresh_expires_at: String,
+    created_at: String,
+    last_used_at: Option<String>,
+    revoked_at: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+#[cot::db::model]
+pub struct MobileExchangeCode {
+    #[model(primary_key)]
+    id: Auto<i64>,
+    code_hash: LimitedString<128>,
+    user_id: i64,
+    created_at: String,
+    expires_at: String,
+    consumed_at: Option<String>,
+}
+
+impl ApiSession {
+    pub async fn create_for_user(
+        db: &Database,
+        user_id: i64,
+        device_name: Option<&str>,
+    ) -> cot::db::Result<ApiTokenPair> {
+        let tokens = fresh_token_pair();
+        let now = now_iso();
+        let mut session = Self {
+            id: Auto::auto(),
+            user_id,
+            device_name: device_name.and_then(normalize_device_name),
+            access_token_hash: LimitedString::new(&token_hash(&tokens.access_token)).unwrap(),
+            refresh_token_hash: LimitedString::new(&token_hash(&tokens.refresh_token)).unwrap(),
+            access_expires_at: access_expires_at(),
+            refresh_expires_at: refresh_expires_at(),
+            created_at: now.clone(),
+            last_used_at: Some(now),
+            revoked_at: None,
+        };
+        session.insert(db).await?;
+        Ok(tokens)
+    }
+
+    async fn find_by_access_token(db: &Database, token: &str) -> cot::db::Result<Option<Self>> {
+        let Ok(hash) = LimitedString::<128>::new(&token_hash(token)) else {
+            return Ok(None);
+        };
+        cot::db::query!(ApiSession, $access_token_hash == hash)
+            .get(db)
+            .await
+    }
+
+    async fn find_by_refresh_token(db: &Database, token: &str) -> cot::db::Result<Option<Self>> {
+        let Ok(hash) = LimitedString::<128>::new(&token_hash(token)) else {
+            return Ok(None);
+        };
+        cot::db::query!(ApiSession, $refresh_token_hash == hash)
+            .get(db)
+            .await
+    }
+
+    fn is_revoked(&self) -> bool {
+        self.revoked_at.is_some()
+    }
+
+    fn access_token_valid(&self) -> bool {
+        !self.is_revoked() && self.access_expires_at > now_iso()
+    }
+
+    fn refresh_token_valid(&self) -> bool {
+        !self.is_revoked() && self.refresh_expires_at > now_iso()
+    }
+
+    async fn rotate(&mut self, db: &Database) -> cot::db::Result<ApiTokenPair> {
+        let tokens = fresh_token_pair();
+        self.access_token_hash = LimitedString::new(&token_hash(&tokens.access_token)).unwrap();
+        self.refresh_token_hash = LimitedString::new(&token_hash(&tokens.refresh_token)).unwrap();
+        self.access_expires_at = access_expires_at();
+        self.refresh_expires_at = refresh_expires_at();
+        self.last_used_at = Some(now_iso());
+        self.save(db).await?;
+        Ok(tokens)
+    }
+
+    async fn revoke(&mut self, db: &Database) -> cot::db::Result<()> {
+        if self.revoked_at.is_none() {
+            self.revoked_at = Some(now_iso());
+            self.save(db).await?;
+        }
+        Ok(())
+    }
+}
+
+pub async fn create_api_session(
+    db: &Database,
+    user_id: i64,
+    device_name: Option<&str>,
+) -> cot::db::Result<ApiTokenPair> {
+    ApiSession::create_for_user(db, user_id, device_name).await
+}
+
+pub async fn get_bearer_user(db: &Database, token: &str) -> Option<AuthenticatedUser> {
+    let session = ApiSession::find_by_access_token(db, token).await.ok()??;
+    if !session.access_token_valid() {
+        return None;
+    }
+    let user = User::get_by_id(db, session.user_id).await.ok()??;
+    authenticated_user_from_user(user)
+}
+
+pub async fn get_request_user(
+    auth: &AuthContext,
+    session: &Session,
+    db: &Database,
+) -> Option<AuthenticatedUser> {
+    if let Some(token) = auth.bearer_token() {
+        return get_bearer_user(db, token).await;
+    }
+    get_session_user(session, db).await
+}
+
+pub async fn refresh_api_session(
+    db: &Database,
+    refresh_token: &str,
+) -> cot::db::Result<Option<ApiTokenPair>> {
+    let Some(mut session) = ApiSession::find_by_refresh_token(db, refresh_token).await? else {
+        return Ok(None);
+    };
+    if !session.refresh_token_valid() {
+        session.revoke(db).await?;
+        return Ok(None);
+    }
+    let Some(user) = User::get_by_id(db, session.user_id).await? else {
+        session.revoke(db).await?;
+        return Ok(None);
+    };
+    if !user.is_active() {
+        session.revoke(db).await?;
+        return Ok(None);
+    }
+    Ok(Some(session.rotate(db).await?))
+}
+
+pub async fn revoke_api_session(
+    db: &Database,
+    access_token: Option<&str>,
+    refresh_token: Option<&str>,
+) -> cot::db::Result<bool> {
+    let mut session = if let Some(token) = access_token {
+        ApiSession::find_by_access_token(db, token).await?
+    } else {
+        None
+    };
+    if session.is_none() {
+        if let Some(token) = refresh_token {
+            session = ApiSession::find_by_refresh_token(db, token).await?;
+        }
+    }
+    let Some(mut session) = session else {
+        return Ok(false);
+    };
+    session.revoke(db).await?;
+    Ok(true)
+}
+
+impl MobileExchangeCode {
+    pub async fn create_for_user(db: &Database, user_id: i64) -> cot::db::Result<String> {
+        let code = random_token(MOBILE_EXCHANGE_CODE_PREFIX);
+        let now = now_iso();
+        let mut row = Self {
+            id: Auto::auto(),
+            code_hash: LimitedString::new(&token_hash(&code)).unwrap(),
+            user_id,
+            created_at: now,
+            expires_at: mobile_exchange_code_expires_at(),
+            consumed_at: None,
+        };
+        row.insert(db).await?;
+        Ok(code)
+    }
+
+    async fn find_by_code(db: &Database, code: &str) -> cot::db::Result<Option<Self>> {
+        let Ok(hash) = LimitedString::<128>::new(&token_hash(code)) else {
+            return Ok(None);
+        };
+        cot::db::query!(MobileExchangeCode, $code_hash == hash)
+            .get(db)
+            .await
+    }
+
+    fn is_valid(&self) -> bool {
+        self.consumed_at.is_none() && self.expires_at > now_iso()
+    }
+
+    async fn consume(&mut self, db: &Database) -> cot::db::Result<()> {
+        self.consumed_at = Some(now_iso());
+        self.save(db).await
+    }
+}
+
+pub async fn create_mobile_exchange_code(db: &Database, user_id: i64) -> cot::db::Result<String> {
+    MobileExchangeCode::create_for_user(db, user_id).await
+}
+
+pub async fn exchange_mobile_code_for_api_session(
+    db: &Database,
+    code: &str,
+    device_name: Option<&str>,
+) -> cot::db::Result<Option<(AuthenticatedUser, ApiTokenPair)>> {
+    let Some(mut exchange_code) = MobileExchangeCode::find_by_code(db, code).await? else {
+        return Ok(None);
+    };
+    if !exchange_code.is_valid() {
+        return Ok(None);
+    }
+    let Some(user) = User::get_by_id(db, exchange_code.user_id).await? else {
+        exchange_code.consume(db).await?;
+        return Ok(None);
+    };
+    let Some(auth_user) = authenticated_user_from_user(user) else {
+        exchange_code.consume(db).await?;
+        return Ok(None);
+    };
+    exchange_code.consume(db).await?;
+    let tokens = ApiSession::create_for_user(db, auth_user.id, device_name).await?;
+    Ok(Some((auth_user, tokens)))
+}
+
+fn fresh_token_pair() -> ApiTokenPair {
+    ApiTokenPair {
+        access_token: random_token(ACCESS_TOKEN_PREFIX),
+        refresh_token: random_token(REFRESH_TOKEN_PREFIX),
+        token_type: "Bearer",
+        expires_in_seconds: ACCESS_TOKEN_TTL_MINUTES * 60,
+    }
+}
+
+fn random_token(prefix: &str) -> String {
+    format!(
+        "{prefix}{}{}",
+        uuid::Uuid::new_v4().simple(),
+        uuid::Uuid::new_v4().simple()
+    )
+}
+
+fn token_hash(token: &str) -> String {
+    let digest = Sha256::digest(token.as_bytes());
+    let mut out = String::with_capacity(digest.len() * 2);
+    for byte in digest {
+        out.push_str(&format!("{byte:02x}"));
+    }
+    out
+}
+
+fn normalize_device_name(name: &str) -> Option<String> {
+    let trimmed = name.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    Some(trimmed.chars().take(255).collect())
+}
+
+fn now_iso() -> String {
+    Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string()
+}
+
+fn access_expires_at() -> String {
+    (Utc::now() + Duration::minutes(ACCESS_TOKEN_TTL_MINUTES))
+        .format("%Y-%m-%dT%H:%M:%SZ")
+        .to_string()
+}
+
+fn refresh_expires_at() -> String {
+    (Utc::now() + Duration::days(REFRESH_TOKEN_TTL_DAYS))
+        .format("%Y-%m-%dT%H:%M:%SZ")
+        .to_string()
+}
+
+fn mobile_exchange_code_expires_at() -> String {
+    (Utc::now() + Duration::minutes(MOBILE_EXCHANGE_CODE_TTL_MINUTES))
+        .format("%Y-%m-%dT%H:%M:%SZ")
+        .to_string()
+}
+
 /// Return `Ok(user)` if the session belongs to an active admin, otherwise
 /// `Err(response)` — a redirect to `/login` or a 403.
 pub async fn require_admin_or_redirect(
@@ -159,6 +517,192 @@ pub fn redirect(location: &str) -> cot::response::Response {
         .expect("valid response")
 }
 
+// ---------------------------------------------------------------------------
+// Migrations
+// ---------------------------------------------------------------------------
+
+pub mod db_migrations {
+    use cot::db::migrations::{self, Field, Operation, SyncDynMigration};
+    use cot::db::{DatabaseField, Identifier, LimitedString};
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0038CreateApiSession;
+
+    impl migrations::Migration for M0038CreateApiSession {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0038_create_api_session";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0003_create_user",
+            )];
+        const OPERATIONS: &'static [Operation] = &[Operation::create_model()
+            .table_name(Identifier::new("furumusic__api_session"))
+            .fields(&[
+                Field::new(Identifier::new("id"), <i64 as DatabaseField>::TYPE)
+                    .primary_key()
+                    .auto(),
+                Field::new(Identifier::new("user_id"), <i64 as DatabaseField>::TYPE),
+                Field::new(
+                    Identifier::new("device_name"),
+                    <String as DatabaseField>::TYPE,
+                )
+                .set_null(true),
+                Field::new(
+                    Identifier::new("access_token_hash"),
+                    <LimitedString<128> as DatabaseField>::TYPE,
+                ),
+                Field::new(
+                    Identifier::new("refresh_token_hash"),
+                    <LimitedString<128> as DatabaseField>::TYPE,
+                ),
+                Field::new(
+                    Identifier::new("access_expires_at"),
+                    <String as DatabaseField>::TYPE,
+                ),
+                Field::new(
+                    Identifier::new("refresh_expires_at"),
+                    <String as DatabaseField>::TYPE,
+                ),
+                Field::new(
+                    Identifier::new("created_at"),
+                    <String as DatabaseField>::TYPE,
+                ),
+                Field::new(
+                    Identifier::new("last_used_at"),
+                    <String as DatabaseField>::TYPE,
+                )
+                .set_null(true),
+                Field::new(
+                    Identifier::new("revoked_at"),
+                    <String as DatabaseField>::TYPE,
+                )
+                .set_null(true),
+            ])
+            .build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn create_api_session_indexes(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE UNIQUE INDEX idx_api_session_access_token_hash \
+                     ON furumusic__api_session (access_token_hash)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE UNIQUE INDEX idx_api_session_refresh_token_hash \
+                     ON furumusic__api_session (refresh_token_hash)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX idx_api_session_user_id \
+                     ON furumusic__api_session (user_id)",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0039CreateApiSessionIndexes;
+
+    impl migrations::Migration for M0039CreateApiSessionIndexes {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0039_create_api_session_indexes";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0038_create_api_session",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_api_session_indexes).build()];
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0040CreateMobileExchangeCode;
+
+    impl migrations::Migration for M0040CreateMobileExchangeCode {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0040_create_mobile_exchange_code";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0039_create_api_session_indexes",
+            )];
+        const OPERATIONS: &'static [Operation] = &[Operation::create_model()
+            .table_name(Identifier::new("furumusic__mobile_exchange_code"))
+            .fields(&[
+                Field::new(Identifier::new("id"), <i64 as DatabaseField>::TYPE)
+                    .primary_key()
+                    .auto(),
+                Field::new(
+                    Identifier::new("code_hash"),
+                    <LimitedString<128> as DatabaseField>::TYPE,
+                ),
+                Field::new(Identifier::new("user_id"), <i64 as DatabaseField>::TYPE),
+                Field::new(
+                    Identifier::new("created_at"),
+                    <String as DatabaseField>::TYPE,
+                ),
+                Field::new(
+                    Identifier::new("expires_at"),
+                    <String as DatabaseField>::TYPE,
+                ),
+                Field::new(
+                    Identifier::new("consumed_at"),
+                    <String as DatabaseField>::TYPE,
+                )
+                .set_null(true),
+            ])
+            .build()];
+    }
+
+    #[cot::db::migrations::migration_op]
+    async fn create_mobile_exchange_code_indexes(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE UNIQUE INDEX idx_mobile_exchange_code_hash \
+                     ON furumusic__mobile_exchange_code (code_hash)",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX idx_mobile_exchange_code_user_id \
+                     ON furumusic__mobile_exchange_code (user_id)",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0041CreateMobileExchangeCodeIndexes;
+
+    impl migrations::Migration for M0041CreateMobileExchangeCodeIndexes {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0041_create_mobile_exchange_code_indexes";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0040_create_mobile_exchange_code",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_mobile_exchange_code_indexes).build()];
+    }
+
+    pub const MIGRATIONS: &[&SyncDynMigration] = &[
+        &M0038CreateApiSession,
+        &M0039CreateApiSessionIndexes,
+        &M0040CreateMobileExchangeCode,
+        &M0041CreateMobileExchangeCodeIndexes,
+    ];
+}
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------

src/config.rs

@@ -338,10 +338,52 @@ impl AppConfig {
     pub fn load() -> Self {
         let mut cfg = Self::default();
         cfg.apply_env_overrides();
+        cfg.apply_startup_db_overrides();
+        cfg.apply_env_overrides();
         cfg.normalize_host_paths();
         cfg
     }
 
+    fn apply_startup_db_overrides(&mut self) {
+        if self.database_url.is_empty() {
+            return;
+        }
+        if tokio::runtime::Handle::try_current().is_ok() {
+            tracing::warn!("skipping startup DB config load from inside an existing Tokio runtime");
+            return;
+        }
+
+        let database_url = self.database_url.clone();
+        let Ok(runtime) = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+        else {
+            tracing::warn!("failed to create runtime for startup DB config load");
+            return;
+        };
+
+        let result = runtime.block_on(async move {
+            let pool = sqlx::postgres::PgPoolOptions::new()
+                .max_connections(1)
+                .connect(&database_url)
+                .await?;
+            sqlx::query_scalar::<_, String>(
+                "SELECT value FROM furumusic__config_entry WHERE key = 'swagger_enabled'",
+            )
+            .fetch_optional(&pool)
+            .await
+        });
+
+        match result {
+            Ok(Some(value)) => match value.parse::<bool>() {
+                Ok(value) => self.swagger_enabled = value,
+                Err(_) => tracing::warn!("ignoring invalid DB config value for swagger_enabled"),
+            },
+            Ok(None) => {}
+            Err(err) => tracing::warn!("failed to read startup DB config overrides: {err}"),
+        }
+    }
+
     /// Build config with full 3-layer resolution (default → DB → env) and
     /// track the source of each field.
     pub async fn load_with_db(db: &Database) -> (Self, ConfigSources) {

src/jobs/archive_cleanup.rs

@@ -0,0 +1,431 @@
+use std::collections::BTreeSet;
+use std::io::ErrorKind;
+
+use sqlx::PgPool;
+
+use crate::scheduler::{Job, JobContext, JobLog};
+
+const SAMPLE_LOG_LIMIT: usize = 50;
+
+pub struct ArchiveCleanupJob;
+
+#[derive(Debug, sqlx::FromRow)]
+struct TrackFileRow {
+    track_id: i64,
+    track_title: String,
+    release_id: i64,
+    release_title: Option<String>,
+    media_file_id: Option<i64>,
+    file_type: Option<String>,
+    file_path: Option<String>,
+}
+
+#[derive(Debug)]
+struct MissingTrack {
+    track_id: i64,
+    track_title: String,
+    release_id: i64,
+    release_title: Option<String>,
+    media_file_id: Option<i64>,
+    file_path: Option<String>,
+    reason: MissingReason,
+}
+
+#[derive(Debug)]
+enum MissingReason {
+    MissingMediaRow,
+    InvalidMediaType(String),
+    EmptyPath,
+    MissingFile,
+    NotRegularFile,
+}
+
+#[derive(Debug, Default)]
+struct DeleteStats {
+    playback_states_cleared: u64,
+    playlist_entries_deleted: u64,
+    likes_deleted: u64,
+    play_history_deleted: u64,
+    popularity_history_deleted: u64,
+    scrobble_outbox_deleted: u64,
+    track_genres_deleted: u64,
+    entity_tags_deleted: u64,
+    external_ids_deleted: u64,
+    track_artists_deleted: u64,
+    tracks_deleted: u64,
+    media_files_deleted: u64,
+}
+
+#[async_trait::async_trait]
+impl Job for ArchiveCleanupJob {
+    fn name(&self) -> &'static str {
+        "archive_cleanup"
+    }
+
+    fn description(&self) -> &'static str {
+        "Clean stale archive records, starting with tracks whose audio files are missing"
+    }
+
+    fn default_cron(&self) -> &'static str {
+        // Daily at 04:45.
+        "0 45 4 * * *"
+    }
+
+    async fn run(&self, ctx: &JobContext, log: &mut JobLog) -> anyhow::Result<()> {
+        run_missing_audio_cleanup(ctx, log).await
+    }
+}
+
+async fn run_missing_audio_cleanup(ctx: &JobContext, log: &mut JobLog) -> anyhow::Result<()> {
+    let storage_dir = ctx.config.agent_storage_dir.trim();
+    if storage_dir.is_empty() {
+        log.warn("Archive cleanup: agent_storage_dir is not configured, skipping file checks");
+        return Ok(());
+    }
+
+    let rows = sqlx::query_as::<_, TrackFileRow>(
+        r#"SELECT t.id AS track_id,
+                  t.title::text AS track_title,
+                  t.release_id,
+                  r.title::text AS release_title,
+                  mf.id AS media_file_id,
+                  mf.file_type::text AS file_type,
+                  mf.file_path::text AS file_path
+             FROM furumusic__track t
+             LEFT JOIN furumusic__release r ON r.id = t.release_id
+             LEFT JOIN furumusic__media_file mf ON mf.id = t.audio_file_id
+            ORDER BY t.id"#,
+    )
+    .fetch_all(&ctx.pool)
+    .await?;
+
+    if rows.is_empty() {
+        log.info("Archive cleanup: no tracks found");
+        return Ok(());
+    }
+
+    log.info(&format!(
+        "Archive cleanup: checking {} track audio reference(s)",
+        rows.len()
+    ));
+
+    let mut missing_tracks = Vec::new();
+    let mut skipped_io_errors = 0u64;
+
+    for row in rows {
+        let Some(media_file_id) = row.media_file_id else {
+            missing_tracks.push(MissingTrack::from_row(row, MissingReason::MissingMediaRow));
+            continue;
+        };
+
+        let file_type = row.file_type.clone();
+        match file_type.as_deref() {
+            Some("audio") => {}
+            Some(file_type) => {
+                missing_tracks.push(MissingTrack::from_row(
+                    row,
+                    MissingReason::InvalidMediaType(file_type.to_owned()),
+                ));
+                continue;
+            }
+            None => {
+                missing_tracks.push(MissingTrack::from_row(row, MissingReason::MissingMediaRow));
+                continue;
+            }
+        }
+
+        let Some(file_path) = row
+            .file_path
+            .as_deref()
+            .map(str::trim)
+            .filter(|path| !path.is_empty())
+        else {
+            missing_tracks.push(MissingTrack::from_row(row, MissingReason::EmptyPath));
+            continue;
+        };
+
+        let absolute_path = crate::media_paths::resolve_media_file_path(storage_dir, file_path);
+        match tokio::fs::metadata(&absolute_path).await {
+            Ok(meta) if meta.is_file() => {}
+            Ok(_) => {
+                missing_tracks.push(MissingTrack::from_row(row, MissingReason::NotRegularFile));
+            }
+            Err(err) if err.kind() == ErrorKind::NotFound => {
+                missing_tracks.push(MissingTrack::from_row(row, MissingReason::MissingFile));
+            }
+            Err(err) => {
+                skipped_io_errors += 1;
+                log.warn(&format!(
+                    "Archive cleanup: skipping track {} media_file_id={media_file_id}; cannot inspect {}: {err}",
+                    row.track_id,
+                    absolute_path.display()
+                ));
+            }
+        }
+    }
+
+    if missing_tracks.is_empty() {
+        log.info(&format!(
+            "Archive cleanup: all checked tracks have readable audio files; skipped_io_errors={skipped_io_errors}"
+        ));
+        return Ok(());
+    }
+
+    for (index, track) in missing_tracks.iter().take(SAMPLE_LOG_LIMIT).enumerate() {
+        log.warn(&format!(
+            "Archive cleanup: deleting stale track {} \"{}\"{}{} ({})",
+            track.track_id,
+            track.track_title,
+            track
+                .release_title
+                .as_deref()
+                .map(|title| format!(" from \"{title}\""))
+                .unwrap_or_default(),
+            track
+                .file_path
+                .as_deref()
+                .map(|path| format!(", path={path}"))
+                .unwrap_or_default(),
+            track.reason
+        ));
+        if index + 1 == SAMPLE_LOG_LIMIT && missing_tracks.len() > SAMPLE_LOG_LIMIT {
+            log.warn(&format!(
+                "Archive cleanup: suppressing per-track logs for remaining {} stale track(s)",
+                missing_tracks.len() - SAMPLE_LOG_LIMIT
+            ));
+        }
+    }
+
+    let track_ids = unique_sorted(
+        missing_tracks
+            .iter()
+            .map(|track| track.track_id)
+            .collect::<Vec<_>>(),
+    );
+    let media_file_ids = unique_sorted(
+        missing_tracks
+            .iter()
+            .filter_map(|track| track.media_file_id)
+            .collect::<Vec<_>>(),
+    );
+    let release_ids = unique_sorted(
+        missing_tracks
+            .iter()
+            .map(|track| track.release_id)
+            .collect::<Vec<_>>(),
+    );
+
+    let stats =
+        delete_tracks_and_unreferenced_audio_media(&ctx.pool, &track_ids, &media_file_ids).await?;
+    let empty_release_count = count_empty_releases(&ctx.pool, &release_ids).await?;
+
+    log.info(&format!(
+        "Archive cleanup: deleted {} track(s), {} unreferenced audio media_file row(s); cleared playback_states={}, playlist_entries={}, likes={}, play_history={}, popularity_history={}, scrobble_outbox={}, track_genres={}, entity_tags={}, external_ids={}, track_artists={}; skipped_io_errors={skipped_io_errors}; empty_releases_left={empty_release_count}",
+        stats.tracks_deleted,
+        stats.media_files_deleted,
+        stats.playback_states_cleared,
+        stats.playlist_entries_deleted,
+        stats.likes_deleted,
+        stats.play_history_deleted,
+        stats.popularity_history_deleted,
+        stats.scrobble_outbox_deleted,
+        stats.track_genres_deleted,
+        stats.entity_tags_deleted,
+        stats.external_ids_deleted,
+        stats.track_artists_deleted,
+    ));
+
+    Ok(())
+}
+
+impl MissingTrack {
+    fn from_row(row: TrackFileRow, reason: MissingReason) -> Self {
+        Self {
+            track_id: row.track_id,
+            track_title: row.track_title,
+            release_id: row.release_id,
+            release_title: row.release_title,
+            media_file_id: row.media_file_id,
+            file_path: row.file_path,
+            reason,
+        }
+    }
+}
+
+impl std::fmt::Display for MissingReason {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::MissingMediaRow => f.write_str("missing media_file row"),
+            Self::InvalidMediaType(file_type) => write!(f, "invalid media_file type {file_type:?}"),
+            Self::EmptyPath => f.write_str("empty media file path"),
+            Self::MissingFile => f.write_str("audio file not found on disk"),
+            Self::NotRegularFile => f.write_str("audio path is not a regular file"),
+        }
+    }
+}
+
+fn unique_sorted(values: Vec<i64>) -> Vec<i64> {
+    values
+        .into_iter()
+        .collect::<BTreeSet<_>>()
+        .into_iter()
+        .collect()
+}
+
+async fn delete_tracks_and_unreferenced_audio_media(
+    pool: &PgPool,
+    track_ids: &[i64],
+    media_file_ids: &[i64],
+) -> anyhow::Result<DeleteStats> {
+    if track_ids.is_empty() {
+        return Ok(DeleteStats::default());
+    }
+
+    let mut tx = pool.begin().await?;
+    let mut stats = DeleteStats::default();
+
+    stats.playback_states_cleared = sqlx::query(
+        r#"UPDATE furumusic__playback_state
+              SET current_track_id = NULL
+            WHERE current_track_id = ANY($1)"#,
+    )
+    .bind(track_ids)
+    .execute(&mut *tx)
+    .await?
+    .rows_affected();
+
+    stats.playlist_entries_deleted =
+        delete_track_rows(&mut tx, "furumusic__playlist_track", track_ids).await?;
+    stats.likes_deleted =
+        delete_track_rows(&mut tx, "furumusic__user_liked_track", track_ids).await?;
+    stats.play_history_deleted =
+        delete_track_rows(&mut tx, "furumusic__play_history", track_ids).await?;
+    stats.popularity_history_deleted =
+        delete_track_rows(&mut tx, "furumusic__track_popularity_history", track_ids).await?;
+    stats.scrobble_outbox_deleted =
+        delete_track_rows(&mut tx, "furumusic__lastfm_scrobble_outbox", track_ids).await?;
+    stats.track_genres_deleted =
+        delete_track_rows(&mut tx, "furumusic__track_genre", track_ids).await?;
+
+    stats.entity_tags_deleted = sqlx::query(
+        r#"DELETE FROM furumusic__entity_genre_tag
+            WHERE entity_kind = 'track'
+              AND entity_id = ANY($1)"#,
+    )
+    .bind(track_ids)
+    .execute(&mut *tx)
+    .await?
+    .rows_affected();
+
+    stats.external_ids_deleted = sqlx::query(
+        r#"DELETE FROM furumusic__external_metadata_id
+            WHERE entity_kind = 'track'
+              AND entity_id = ANY($1)"#,
+    )
+    .bind(track_ids)
+    .execute(&mut *tx)
+    .await?
+    .rows_affected();
+
+    stats.track_artists_deleted =
+        delete_track_rows(&mut tx, "furumusic__track_artist", track_ids).await?;
+
+    stats.tracks_deleted = sqlx::query("DELETE FROM furumusic__track WHERE id = ANY($1)")
+        .bind(track_ids)
+        .execute(&mut *tx)
+        .await?
+        .rows_affected();
+
+    if !media_file_ids.is_empty() {
+        stats.media_files_deleted = sqlx::query(
+            r#"DELETE FROM furumusic__media_file mf
+                WHERE mf.id = ANY($1)
+                  AND mf.file_type = 'audio'
+                  AND NOT EXISTS (
+                        SELECT 1
+                          FROM furumusic__track t
+                         WHERE t.audio_file_id = mf.id
+                            OR t.cover_file_id = mf.id
+                  )
+                  AND NOT EXISTS (
+                        SELECT 1
+                          FROM furumusic__release r
+                         WHERE r.cover_file_id = mf.id
+                  )
+                  AND NOT EXISTS (
+                        SELECT 1
+                          FROM furumusic__artist a
+                         WHERE a.image_file_id = mf.id
+                  )
+                  AND NOT EXISTS (
+                        SELECT 1
+                          FROM furumusic__playlist p
+                         WHERE p.cover_file_id = mf.id
+                  )"#,
+        )
+        .bind(media_file_ids)
+        .execute(&mut *tx)
+        .await?
+        .rows_affected();
+    }
+
+    tx.commit().await?;
+    Ok(stats)
+}
+
+async fn delete_track_rows(
+    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
+    table: &str,
+    track_ids: &[i64],
+) -> anyhow::Result<u64> {
+    let sql = format!("DELETE FROM {table} WHERE track_id = ANY($1)");
+    Ok(sqlx::query(&sql)
+        .bind(track_ids)
+        .execute(&mut **tx)
+        .await?
+        .rows_affected())
+}
+
+async fn count_empty_releases(pool: &PgPool, release_ids: &[i64]) -> anyhow::Result<i64> {
+    if release_ids.is_empty() {
+        return Ok(0);
+    }
+
+    let count = sqlx::query_scalar::<_, i64>(
+        r#"SELECT COUNT(*)
+             FROM furumusic__release r
+            WHERE r.id = ANY($1)
+              AND NOT EXISTS (
+                    SELECT 1
+                      FROM furumusic__track t
+                     WHERE t.release_id = r.id
+              )"#,
+    )
+    .bind(release_ids)
+    .fetch_one(pool)
+    .await?;
+
+    Ok(count)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn unique_sorted_deduplicates_ids() {
+        assert_eq!(unique_sorted(vec![3, 1, 3, 2, 1]), vec![1, 2, 3]);
+    }
+
+    #[test]
+    fn missing_reason_display_is_stable() {
+        assert_eq!(
+            MissingReason::InvalidMediaType("cover_art".to_owned()).to_string(),
+            "invalid media_file type \"cover_art\""
+        );
+        assert_eq!(
+            MissingReason::MissingFile.to_string(),
+            "audio file not found on disk"
+        );
+    }
+}

src/jobs/inbox_discover.rs

@@ -128,7 +128,11 @@ impl Job for InboxDiscoverJob {
                             v
                         }
                         Err(e) => {
-                            crate::metrics::record_agent_file_hash(hash_start.elapsed(), 0, "error");
+                            crate::metrics::record_agent_file_hash(
+                                hash_start.elapsed(),
+                                0,
+                                "error",
+                            );
                             log.warn(&format!("Failed to hash {}: {e}", file_path.display()));
                             continue;
                         }

src/jobs/inbox_process.rs

@@ -494,7 +494,12 @@ async fn process_folder_batch(
         .await
         {
             Ok(Ok(results)) => {
-                crate::metrics::record_agent_rag("artist", "ok", rag_start.elapsed(), results.len());
+                crate::metrics::record_agent_rag(
+                    "artist",
+                    "ok",
+                    rag_start.elapsed(),
+                    results.len(),
+                );
                 for a in results {
                     if !all_similar_artists
                         .iter()
@@ -525,7 +530,12 @@ async fn process_folder_batch(
         .await
         {
             Ok(Ok(results)) => {
-                crate::metrics::record_agent_rag("release", "ok", rag_start.elapsed(), results.len());
+                crate::metrics::record_agent_rag(
+                    "release",
+                    "ok",
+                    rag_start.elapsed(),
+                    results.len(),
+                );
                 for r in results {
                     if !all_similar_releases
                         .iter()

src/jobs/mod.rs

@@ -1,3 +1,4 @@
+pub mod archive_cleanup;
 pub mod artwork_backfill;
 pub mod inbox_discover;
 pub mod inbox_process;

src/main.rs

@@ -52,6 +52,7 @@ fn build_registry() -> Arc<JobRegistry> {
     registry.register(jobs::inbox_discover::InboxDiscoverJob);
     registry.register(jobs::inbox_process::InboxProcessJob);
     registry.register(jobs::inbox_process::FileProcessJob);
+    registry.register(jobs::archive_cleanup::ArchiveCleanupJob);
     registry.register(jobs::artwork_backfill::ArtworkBackfillJob);
     registry.register(jobs::metadata_backfill::MetadataBackfillJob);
     registry.register(jobs::lastfm_popularity::LastfmPopularityJob);
@@ -378,6 +379,15 @@ impl App for FuruApp {
                                 }
                             };
 
+                            let (live_config, _) = AppConfig::load_with_db(&db).await;
+                            if !live_config.auth_password_enabled {
+                                metrics::record_auth_attempt("password", "failure", "disabled");
+                                let msg = i18n.t.login_disabled.to_owned();
+                                return login_page_handler(i18n, &config, db, msg)
+                                    .await?
+                                    .into_response();
+                            }
+
                             // Try to authenticate
                             if let Ok(Some(user)) = User::get_by_username(&db, &data.username).await
                             {
@@ -425,6 +435,16 @@ impl App for FuruApp {
                 get(oidc::oidc_callback_handler),
                 "oidc_callback",
             ),
+            Route::with_handler_and_name(
+                "/auth/mobile/oidc/start",
+                get(oidc::oidc_mobile_start_handler),
+                "mobile_oidc_start",
+            ),
+            Route::with_handler_and_name(
+                "/auth/mobile/oidc/callback",
+                get(oidc::oidc_mobile_callback_handler),
+                "mobile_oidc_callback",
+            ),
         ])
     }
 }

src/oidc.rs

@@ -4,6 +4,7 @@ use std::sync::LazyLock;
 use std::time::Instant;
 
 use cot::db::Database;
+use cot::request::extractors::UrlQuery;
 use cot::session::Session;
 use openidconnect::core::{CoreClient, CoreProviderMetadata};
 use openidconnect::{
@@ -54,6 +55,13 @@ const SESSION_NONCE: &str = "oidc_nonce";
 const SESSION_PKCE_VERIFIER: &str = "oidc_pkce_verifier";
 const SESSION_REDIRECT_URI: &str = "oidc_redirect_uri";
 
+const SESSION_MOBILE_CSRF_STATE: &str = "mobile_oidc_csrf_state";
+const SESSION_MOBILE_NONCE: &str = "mobile_oidc_nonce";
+const SESSION_MOBILE_PKCE_VERIFIER: &str = "mobile_oidc_pkce_verifier";
+const SESSION_MOBILE_PROVIDER_REDIRECT_URI: &str = "mobile_oidc_provider_redirect_uri";
+const SESSION_MOBILE_APP_REDIRECT_URI: &str = "mobile_oidc_app_redirect_uri";
+const DEFAULT_MOBILE_REDIRECT_URI: &str = "furumi://auth/callback";
+
 // ---------------------------------------------------------------------------
 // Provider cache
 // ---------------------------------------------------------------------------
@@ -247,13 +255,23 @@ pub struct OidcCallbackQuery {
     state: String,
 }
 
+#[derive(Deserialize)]
+pub struct MobileOidcStartQuery {
+    redirect_uri: Option<String>,
+}
+
+#[derive(Deserialize)]
+pub struct MobileOidcCallbackQuery {
+    code: Option<String>,
+    state: Option<String>,
+    error: Option<String>,
+}
+
 pub async fn oidc_callback_handler(
     i18n: I18n,
     db: Database,
     session: Session,
-    cot::request::extractors::UrlQuery(query): cot::request::extractors::UrlQuery<
-        OidcCallbackQuery,
-    >,
+    UrlQuery(query): UrlQuery<OidcCallbackQuery>,
 ) -> cot::Result<cot::response::Response> {
     let (config, _) = AppConfig::load_with_db(&db).await;
 
@@ -461,6 +479,296 @@ pub async fn oidc_callback_handler(
     Ok(auth::redirect(&redirect_to))
 }
 
+// ---------------------------------------------------------------------------
+// Mobile OIDC flow
+// ---------------------------------------------------------------------------
+
+pub async fn oidc_mobile_start_handler(
+    origin: RequestOrigin,
+    db: Database,
+    session: Session,
+    UrlQuery(query): UrlQuery<MobileOidcStartQuery>,
+) -> cot::Result<cot::response::Response> {
+    let Some(app_redirect_uri) = safe_mobile_redirect_uri(query.redirect_uri.as_deref()) else {
+        crate::metrics::record_auth_attempt("mobile_oidc", "failure", "bad_redirect_uri");
+        return Ok(text_response(
+            cot::http::StatusCode::BAD_REQUEST,
+            "invalid mobile redirect_uri",
+        ));
+    };
+
+    let (config, _) = AppConfig::load_with_db(&db).await;
+
+    if !config.auth_sso_enabled
+        || config.oidc_issuer.is_empty()
+        || config.oidc_client_id.is_empty()
+        || config.oidc_client_secret.is_empty()
+    {
+        tracing::warn!("Mobile OIDC start requested but SSO is not configured");
+        crate::metrics::record_auth_attempt("mobile_oidc", "failure", "not_configured");
+        return Ok(mobile_redirect_error(
+            &app_redirect_uri,
+            "sso_not_configured",
+        ));
+    }
+
+    let http = oidc_http_client();
+    let client = match get_or_refresh_provider(&config, &http).await {
+        Ok(c) => c,
+        Err(e) => {
+            tracing::error!("Mobile OIDC provider error: {e}");
+            crate::metrics::record_auth_attempt("mobile_oidc", "failure", "provider_error");
+            return Ok(mobile_redirect_error(&app_redirect_uri, "provider_error"));
+        }
+    };
+
+    let provider_redirect_uri = format!("{}/auth/mobile/oidc/callback", origin.0);
+    let redirect_url = RedirectUrl::new(provider_redirect_uri.clone())
+        .map_err(|e| cot::Error::internal(format!("bad mobile redirect URI: {e}")))?;
+    let client = client.set_redirect_uri(redirect_url);
+
+    let (pkce_challenge, pkce_verifier) = PkceCodeChallenge::new_random_sha256();
+    let (auth_url, csrf_state, nonce) = client
+        .authorize_url(
+            openidconnect::AuthenticationFlow::<openidconnect::core::CoreResponseType>::AuthorizationCode,
+            CsrfToken::new_random,
+            Nonce::new_random,
+        )
+        .add_scope(Scope::new("email".to_string()))
+        .add_scope(Scope::new("profile".to_string()))
+        .set_pkce_challenge(pkce_challenge)
+        .url();
+
+    session
+        .insert(SESSION_MOBILE_CSRF_STATE, csrf_state.secret().clone())
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    session
+        .insert(SESSION_MOBILE_NONCE, nonce.secret().clone())
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    session
+        .insert(SESSION_MOBILE_PKCE_VERIFIER, pkce_verifier.secret().clone())
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    session
+        .insert(
+            SESSION_MOBILE_PROVIDER_REDIRECT_URI,
+            provider_redirect_uri.clone(),
+        )
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    session
+        .insert(SESSION_MOBILE_APP_REDIRECT_URI, app_redirect_uri)
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+
+    tracing::info!(
+        auth_url = %auth_url,
+        provider_redirect_uri = %provider_redirect_uri,
+        "Mobile OIDC start: redirecting to provider",
+    );
+
+    Ok(auth::redirect(auth_url.as_str()))
+}
+
+pub async fn oidc_mobile_callback_handler(
+    db: Database,
+    session: Session,
+    UrlQuery(query): UrlQuery<MobileOidcCallbackQuery>,
+) -> cot::Result<cot::response::Response> {
+    let app_redirect_uri = mobile_app_redirect_uri_from_session(&session).await?;
+
+    if query.error.is_some() {
+        tracing::warn!("Mobile OIDC callback returned provider error");
+        crate::metrics::record_auth_attempt("mobile_oidc", "failure", "provider_denied");
+        clear_mobile_oidc_session(&session).await?;
+        return Ok(mobile_redirect_error(&app_redirect_uri, "provider_denied"));
+    }
+
+    let Some(code) = query.code else {
+        crate::metrics::record_auth_attempt("mobile_oidc", "failure", "missing_code");
+        clear_mobile_oidc_session(&session).await?;
+        return Ok(mobile_redirect_error(&app_redirect_uri, "missing_code"));
+    };
+    let Some(state) = query.state else {
+        crate::metrics::record_auth_attempt("mobile_oidc", "failure", "missing_state");
+        clear_mobile_oidc_session(&session).await?;
+        return Ok(mobile_redirect_error(&app_redirect_uri, "missing_state"));
+    };
+
+    let saved_csrf: Option<String> = session
+        .get(SESSION_MOBILE_CSRF_STATE)
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    let saved_nonce: Option<String> = session
+        .get(SESSION_MOBILE_NONCE)
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    let saved_pkce: Option<String> = session
+        .get(SESSION_MOBILE_PKCE_VERIFIER)
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    let provider_redirect_uri: Option<String> = session
+        .get(SESSION_MOBILE_PROVIDER_REDIRECT_URI)
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+
+    let Some(saved_csrf) = saved_csrf else {
+        tracing::warn!("Mobile OIDC callback: no CSRF state in session");
+        crate::metrics::record_auth_attempt("mobile_oidc", "failure", "missing_state");
+        clear_mobile_oidc_session(&session).await?;
+        return Ok(mobile_redirect_error(&app_redirect_uri, "missing_state"));
+    };
+    if state != saved_csrf {
+        tracing::warn!("Mobile OIDC callback: CSRF state mismatch");
+        crate::metrics::record_auth_attempt("mobile_oidc", "failure", "csrf");
+        clear_mobile_oidc_session(&session).await?;
+        return Ok(mobile_redirect_error(&app_redirect_uri, "csrf"));
+    }
+
+    let Some(nonce_str) = saved_nonce else {
+        crate::metrics::record_auth_attempt("mobile_oidc", "failure", "missing_nonce");
+        clear_mobile_oidc_session(&session).await?;
+        return Ok(mobile_redirect_error(&app_redirect_uri, "missing_nonce"));
+    };
+    let Some(pkce_str) = saved_pkce else {
+        crate::metrics::record_auth_attempt("mobile_oidc", "failure", "missing_pkce");
+        clear_mobile_oidc_session(&session).await?;
+        return Ok(mobile_redirect_error(&app_redirect_uri, "missing_pkce"));
+    };
+    let Some(provider_redirect_uri) = provider_redirect_uri else {
+        crate::metrics::record_auth_attempt("mobile_oidc", "failure", "missing_redirect_uri");
+        clear_mobile_oidc_session(&session).await?;
+        return Ok(mobile_redirect_error(
+            &app_redirect_uri,
+            "missing_redirect_uri",
+        ));
+    };
+
+    let (config, _) = AppConfig::load_with_db(&db).await;
+    if !config.auth_sso_enabled
+        || config.oidc_issuer.is_empty()
+        || config.oidc_client_id.is_empty()
+        || config.oidc_client_secret.is_empty()
+    {
+        crate::metrics::record_auth_attempt("mobile_oidc", "failure", "not_configured");
+        clear_mobile_oidc_session(&session).await?;
+        return Ok(mobile_redirect_error(
+            &app_redirect_uri,
+            "sso_not_configured",
+        ));
+    }
+
+    let http = oidc_http_client();
+    let client = match get_or_refresh_provider(&config, &http).await {
+        Ok(c) => c,
+        Err(e) => {
+            tracing::error!("Mobile OIDC provider error during callback: {e}");
+            crate::metrics::record_auth_attempt("mobile_oidc", "failure", "provider_error");
+            clear_mobile_oidc_session(&session).await?;
+            return Ok(mobile_redirect_error(&app_redirect_uri, "provider_error"));
+        }
+    };
+    let redirect_url = RedirectUrl::new(provider_redirect_uri)
+        .map_err(|e| cot::Error::internal(format!("bad mobile redirect URI from session: {e}")))?;
+    let client = client.set_redirect_uri(redirect_url);
+
+    let token_request = match client.exchange_code(AuthorizationCode::new(code)) {
+        Ok(req) => req,
+        Err(e) => {
+            tracing::error!("Mobile OIDC token endpoint not configured: {e}");
+            crate::metrics::record_auth_attempt("mobile_oidc", "failure", "token_config");
+            clear_mobile_oidc_session(&session).await?;
+            return Ok(mobile_redirect_error(&app_redirect_uri, "oidc_error"));
+        }
+    };
+    let token_response = token_request
+        .set_pkce_verifier(PkceCodeVerifier::new(pkce_str))
+        .request_async(&http)
+        .await;
+    let token_response = match token_response {
+        Ok(t) => t,
+        Err(e) => {
+            tracing::error!("Mobile OIDC token exchange failed: {e}");
+            crate::metrics::record_auth_attempt("mobile_oidc", "failure", "token_exchange");
+            clear_mobile_oidc_session(&session).await?;
+            return Ok(mobile_redirect_error(&app_redirect_uri, "oidc_error"));
+        }
+    };
+
+    use openidconnect::TokenResponse;
+    let id_token = match token_response.id_token() {
+        Some(t) => t,
+        None => {
+            tracing::error!("Mobile OIDC response missing ID token");
+            crate::metrics::record_auth_attempt("mobile_oidc", "failure", "missing_id_token");
+            clear_mobile_oidc_session(&session).await?;
+            return Ok(mobile_redirect_error(&app_redirect_uri, "oidc_error"));
+        }
+    };
+
+    let nonce = Nonce::new(nonce_str);
+    let claims = match id_token.claims(&client.id_token_verifier(), &nonce) {
+        Ok(c) => c,
+        Err(e) => {
+            tracing::error!("Mobile OIDC ID token verification failed: {e}");
+            crate::metrics::record_auth_attempt("mobile_oidc", "failure", "id_token_verify");
+            clear_mobile_oidc_session(&session).await?;
+            return Ok(mobile_redirect_error(&app_redirect_uri, "oidc_error"));
+        }
+    };
+
+    let sub = claims.subject().to_string();
+    let issuer = claims.issuer().to_string();
+    let email = claims.email().map(|e| e.to_string());
+    let name = claims
+        .name()
+        .and_then(|n| n.get(None))
+        .map(|n| n.to_string());
+    let groups = extract_groups_from_jwt(&id_token.to_string());
+
+    if !is_allowed_by_groups(&groups, &config.oidc_user_groups, &config.oidc_admin_groups) {
+        tracing::warn!(
+            "Mobile OIDC login denied by group allowlist: sub={sub}, groups={groups:?}, user_groups={:?}, admin_groups={:?}",
+            config.oidc_user_groups,
+            config.oidc_admin_groups,
+        );
+        crate::metrics::record_auth_attempt("mobile_oidc", "failure", "not_in_group");
+        clear_mobile_oidc_session(&session).await?;
+        return Ok(mobile_redirect_error(&app_redirect_uri, "access_denied"));
+    }
+
+    let user = match provision_user(
+        &db,
+        &issuer,
+        &sub,
+        email.as_deref(),
+        name.as_deref(),
+        &groups,
+        &config.oidc_admin_groups,
+    )
+    .await
+    {
+        Ok(u) => u,
+        Err(e) => {
+            tracing::error!("Mobile OIDC user provisioning failed: {e}");
+            crate::metrics::record_auth_attempt("mobile_oidc", "failure", "provisioning");
+            clear_mobile_oidc_session(&session).await?;
+            return Ok(mobile_redirect_error(&app_redirect_uri, "oidc_error"));
+        }
+    };
+
+    let exchange_code = auth::create_mobile_exchange_code(&db, user.id_val())
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    clear_mobile_oidc_session(&session).await?;
+
+    crate::metrics::record_auth_attempt("mobile_oidc", "success", "ok");
+    crate::metrics::record_session_created("mobile_oidc");
+    Ok(mobile_redirect_success(&app_redirect_uri, &exchange_code))
+}
+
 // ---------------------------------------------------------------------------
 // User provisioning
 // ---------------------------------------------------------------------------
@@ -616,6 +924,259 @@ fn redirect_login_with_error(message: &str) -> cot::Result<cot::response::Respon
     Ok(auth::redirect(&format!("/login?error={encoded}")))
 }
 
+fn text_response(status: cot::http::StatusCode, message: &str) -> cot::response::Response {
+    cot::http::Response::builder()
+        .status(status)
+        .body(cot::Body::fixed(message.to_owned()))
+        .expect("valid response")
+}
+
+async fn mobile_app_redirect_uri_from_session(session: &Session) -> cot::Result<String> {
+    let saved: Option<String> = session
+        .get(SESSION_MOBILE_APP_REDIRECT_URI)
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    Ok(safe_mobile_redirect_uri(saved.as_deref())
+        .unwrap_or_else(|| DEFAULT_MOBILE_REDIRECT_URI.to_owned()))
+}
+
+async fn clear_mobile_oidc_session(session: &Session) -> cot::Result<()> {
+    let _: Option<String> = session
+        .remove(SESSION_MOBILE_CSRF_STATE)
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    let _: Option<String> = session
+        .remove(SESSION_MOBILE_NONCE)
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    let _: Option<String> = session
+        .remove(SESSION_MOBILE_PKCE_VERIFIER)
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    let _: Option<String> = session
+        .remove(SESSION_MOBILE_PROVIDER_REDIRECT_URI)
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    let _: Option<String> = session
+        .remove(SESSION_MOBILE_APP_REDIRECT_URI)
+        .await
+        .map_err(|e| cot::Error::internal(e.to_string()))?;
+    Ok(())
+}
+
+fn safe_mobile_redirect_uri(raw: Option<&str>) -> Option<String> {
+    let value = raw
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .unwrap_or(DEFAULT_MOBILE_REDIRECT_URI);
+    if value.len() > 2048 || value.bytes().any(|b| matches!(b, b'\r' | b'\n')) {
+        return None;
+    }
+
+    let lower = value.to_ascii_lowercase();
+    if lower.starts_with("furumi://") || lower.starts_with("furumusic://") {
+        return Some(value.to_owned());
+    }
+    None
+}
+
+fn mobile_redirect_success(app_redirect_uri: &str, code: &str) -> cot::response::Response {
+    let deep_link = append_query_param(app_redirect_uri, "code", code);
+    mobile_deep_link_page(
+        "success",
+        "Sign-in complete",
+        "Furumi should open automatically. You can close this window after the app opens.",
+        None,
+        &deep_link,
+    )
+}
+
+fn mobile_redirect_error(app_redirect_uri: &str, error: &str) -> cot::response::Response {
+    let deep_link = append_query_param(app_redirect_uri, "error", error);
+    mobile_deep_link_page(
+        "error",
+        "Sign-in failed",
+        "Furumi should open automatically and show the sign-in error. You can close this window after the app opens.",
+        Some(error),
+        &deep_link,
+    )
+}
+
+fn mobile_deep_link_page(
+    state: &str,
+    title: &str,
+    message: &str,
+    detail: Option<&str>,
+    deep_link: &str,
+) -> cot::response::Response {
+    let state_class = html_escape(state);
+    let title_html = html_escape(title);
+    let message_html = html_escape(message);
+    let detail_html = detail
+        .map(|value| format!(r#"<p class="detail">Reason: {}</p>"#, html_escape(value)))
+        .unwrap_or_default();
+    let deep_link_html = html_escape(deep_link);
+    let deep_link_js =
+        serde_json::to_string(deep_link).expect("serializing URL string cannot fail");
+
+    let html = format!(
+        r#"<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{title_html}</title>
+  <style>
+    :root {{
+      color-scheme: light dark;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: #101114;
+      color: #f5f2ea;
+    }}
+    body {{
+      min-height: 100vh;
+      margin: 0;
+      display: grid;
+      place-items: center;
+      padding: 24px;
+      box-sizing: border-box;
+    }}
+    main {{
+      width: min(420px, 100%);
+      text-align: center;
+    }}
+    .mark {{
+      width: 54px;
+      height: 54px;
+      margin: 0 auto 18px;
+      border-radius: 999px;
+      display: grid;
+      place-items: center;
+      font-size: 18px;
+      font-weight: 700;
+      background: #2f7d52;
+      color: white;
+    }}
+    .mark.error {{
+      background: #9d3d42;
+    }}
+    h1 {{
+      margin: 0 0 10px;
+      font-size: 26px;
+      line-height: 1.15;
+      letter-spacing: 0;
+    }}
+    p {{
+      margin: 0;
+      color: #c9c2b7;
+      font-size: 15px;
+      line-height: 1.55;
+    }}
+    .detail {{
+      margin-top: 12px;
+      color: #f1b3b7;
+      overflow-wrap: anywhere;
+    }}
+    a {{
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 44px;
+      margin-top: 24px;
+      padding: 0 18px;
+      border-radius: 8px;
+      background: #e8d8a8;
+      color: #17150f;
+      font-weight: 700;
+      text-decoration: none;
+    }}
+    .hint {{
+      margin-top: 14px;
+      font-size: 13px;
+      color: #89847c;
+    }}
+  </style>
+</head>
+<body>
+  <main>
+    <div class="mark {state_class}" aria-hidden="true">{mark}</div>
+    <h1>{title_html}</h1>
+    <p>{message_html}</p>
+    {detail_html}
+    <a href="{deep_link_html}">Open Furumi</a>
+    <p class="hint">If nothing happens, use the button above.</p>
+  </main>
+  <script>
+    const deepLink = {deep_link_js};
+    window.setTimeout(() => {{
+      window.location.href = deepLink;
+    }}, 100);
+    window.setTimeout(() => {{
+      window.close();
+    }}, 1800);
+  </script>
+</body>
+</html>"#,
+        mark = if state == "error" { "!" } else { "OK" }
+    );
+
+    cot::http::Response::builder()
+        .status(cot::http::StatusCode::OK)
+        .header(cot::http::header::CONTENT_TYPE, "text/html; charset=utf-8")
+        .header(cot::http::header::CACHE_CONTROL, "no-store")
+        .body(cot::Body::fixed(html))
+        .expect("valid response")
+}
+
+fn append_query_param(uri: &str, key: &str, value: &str) -> String {
+    let (base, fragment) = uri.split_once('#').unwrap_or((uri, ""));
+    let separator = if base.contains('?') { '&' } else { '?' };
+    let mut out = format!("{base}{separator}{key}={}", urlencoded(value));
+    if !fragment.is_empty() {
+        out.push('#');
+        out.push_str(fragment);
+    }
+    out
+}
+
+fn html_escape(value: &str) -> String {
+    let mut out = String::with_capacity(value.len());
+    for ch in value.chars() {
+        match ch {
+            '&' => out.push_str("&amp;"),
+            '<' => out.push_str("&lt;"),
+            '>' => out.push_str("&gt;"),
+            '"' => out.push_str("&quot;"),
+            '\'' => out.push_str("&#39;"),
+            _ => out.push(ch),
+        }
+    }
+    out
+}
+
+fn extract_groups_from_jwt(token: &str) -> Vec<String> {
+    use base64::Engine;
+
+    let Some(payload_b64) = token.split('.').nth(1) else {
+        return Vec::new();
+    };
+    let Ok(payload_bytes) = base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .decode(payload_b64)
+        .or_else(|_| base64::engine::general_purpose::URL_SAFE.decode(payload_b64))
+    else {
+        return Vec::new();
+    };
+    let Ok(value) = serde_json::from_slice::<serde_json::Value>(&payload_bytes) else {
+        return Vec::new();
+    };
+    let Some(arr) = value.get("groups").and_then(|value| value.as_array()) else {
+        return Vec::new();
+    };
+    arr.iter()
+        .filter_map(|value| value.as_str().map(String::from))
+        .collect()
+}
+
 /// Minimal percent-encoding for query parameter values.
 fn urlencoded(s: &str) -> String {
     let mut out = String::with_capacity(s.len() * 2);
@@ -632,3 +1193,41 @@ fn urlencoded(s: &str) -> String {
     }
     out
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn mobile_oidc_append_query_param_preserves_fragment() {
+        assert_eq!(
+            append_query_param("furumi://auth/callback#done", "code", "a b"),
+            "furumi://auth/callback?code=a%20b#done"
+        );
+        assert_eq!(
+            append_query_param("furumi://auth/callback?desktop=1", "error", "oidc_error"),
+            "furumi://auth/callback?desktop=1&error=oidc_error"
+        );
+    }
+
+    #[test]
+    fn mobile_oidc_html_escape_escapes_page_values() {
+        assert_eq!(
+            html_escape(r#"<tag attr="x&y">'text'</tag>"#),
+            "&lt;tag attr=&quot;x&amp;y&quot;&gt;&#39;text&#39;&lt;/tag&gt;"
+        );
+    }
+
+    #[test]
+    fn mobile_oidc_redirect_uri_allows_only_furumi_schemes() {
+        assert_eq!(
+            safe_mobile_redirect_uri(Some("furumi://auth/callback")).as_deref(),
+            Some("furumi://auth/callback")
+        );
+        assert_eq!(
+            safe_mobile_redirect_uri(Some("furumusic://auth/callback")).as_deref(),
+            Some("furumusic://auth/callback")
+        );
+        assert!(safe_mobile_redirect_uri(Some("https://example.com/callback")).is_none());
+    }
+}

src/scheduler/mod.rs

@@ -1372,6 +1372,7 @@ async fn run_scheduled_job(
     if !live_config.agent_enabled
         && job_name != "lastfm_popularity"
         && job_name != "lastfm_scrobble"
+        && job_name != "archive_cleanup"
         && job_name != "artwork_backfill"
     {
         tracing::warn!(job = job_name, "Skipping: agent_enabled=false");

templates/admin/v2.html

@@ -1193,6 +1193,77 @@ tbody tr:hover {
     gap: 12px;
 }
 
+.release-track-search-row {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
+    gap: 8px;
+    margin-bottom: 10px;
+}
+
+.release-track-list {
+    border: 1px solid var(--border-color);
+    border-radius: 8px;
+    background: var(--bg-primary);
+    overflow: hidden;
+}
+
+.release-track-head,
+.release-track-row {
+    display: grid;
+    grid-template-columns: 72px 82px minmax(0, 1.4fr) minmax(0, 1fr) minmax(0, .9fr) 70px 36px;
+    gap: 8px;
+    align-items: center;
+    padding: 8px;
+}
+
+.release-track-head {
+    min-height: 34px;
+    border-bottom: 1px solid var(--border-color);
+    color: var(--text-subdued);
+    font-size: 10px;
+    font-weight: 850;
+    text-transform: uppercase;
+}
+
+.release-track-row {
+    min-height: 48px;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.055);
+}
+
+.release-track-row:last-child {
+    border-bottom: 0;
+}
+
+.release-track-row:hover {
+    background: rgba(255, 255, 255, 0.03);
+}
+
+.release-track-row input {
+    width: 100%;
+    height: 30px;
+    min-height: 30px;
+    padding: 0 8px;
+}
+
+.release-track-title,
+.release-track-meta {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.release-track-title {
+    color: var(--text-primary);
+    font-size: 12px;
+    font-weight: 750;
+}
+
+.release-track-meta {
+    color: var(--text-subdued);
+    font-size: 11px;
+}
+
 .image-actions {
     display: flex;
     align-items: center;
@@ -1836,6 +1907,10 @@ tbody tr:hover {
                                 <i data-lucide="square-pen"></i>
                                 Edit
                             </button>
+                            <button class="btn primary" x-show="libraryKind === 'releases'" @click="openReleaseCreator()">
+                                <i data-lucide="plus"></i>
+                                New release
+                            </button>
                             <button class="btn warn" @click="mockAction('Merge wizard will open from this action slot')">
                                 <i data-lucide="git-merge"></i>
                                 Merge
@@ -2419,8 +2494,8 @@ tbody tr:hover {
         <section class="modal">
             <div class="modal-head">
                 <div class="panel-title">
-                    <strong x-text="activeLibraryItem?.title || 'Editor'"></strong>
-                    <span x-text="activeLibraryItem?.kind || 'Library entity'"></span>
+                    <strong x-text="editorTitle()"></strong>
+                    <span x-text="editorSubtitle()"></span>
                 </div>
                 <button class="icon-btn" @click="editorOpen = false">
                     <i data-lucide="x"></i>
@@ -2454,6 +2529,54 @@ tbody tr:hover {
                         </div>
                     </div>
 
+                    <div class="field" x-show="isReleaseEditor()">
+                        <label>Release tracks</label>
+                        <div class="release-track-search-row">
+                            <div class="artist-picker">
+                                <input class="search" placeholder="Search track" x-model="releaseTrackSearch" @input.debounce.300ms="searchReleaseTracks()" @keydown.enter.prevent="addBestReleaseTrack()" @keydown.escape="clearReleaseTrackSearch()" />
+                                <div class="artist-results" x-show="releaseTrackSearchOpen()" x-transition>
+                                    <template x-for="track in availableReleaseTrackResults()" :key="track.id">
+                                        <button class="artist-result" type="button" @click="addReleaseTrack(track)">
+                                            <span x-text="track.title"></span>
+                                            <small x-text="releaseTrackSearchMeta(track)"></small>
+                                        </button>
+                                    </template>
+                                    <div class="artist-result muted" x-show="releaseTrackSearchLoading">Searching...</div>
+                                    <div class="artist-result muted" x-show="!releaseTrackSearchLoading && availableReleaseTrackResults().length === 0">No matching tracks</div>
+                                </div>
+                            </div>
+                            <button class="btn" type="button" @click="addBestReleaseTrack()" :disabled="!releaseTrackSearch.trim()">
+                                <i data-lucide="plus"></i>
+                                Add
+                            </button>
+                        </div>
+                        <div class="release-track-list" x-show="releaseTracks().length">
+                            <div class="release-track-head">
+                                <span>Disc</span>
+                                <span>Track #</span>
+                                <span>Title</span>
+                                <span>Artists</span>
+                                <span>Current release</span>
+                                <span>Time</span>
+                                <span></span>
+                            </div>
+                            <template x-for="track in releaseTracks()" :key="track.id">
+                                <div class="release-track-row">
+                                    <input type="number" min="1" max="999" x-model="track.disc_number" />
+                                    <input type="number" min="1" max="9999" x-model="track.track_number" />
+                                    <div class="release-track-title" x-text="track.title"></div>
+                                    <div class="release-track-meta" x-text="track.artists || 'Unknown artist'"></div>
+                                    <div class="release-track-meta" x-text="releaseTrackOrigin(track)"></div>
+                                    <div class="release-track-meta" x-text="trackDuration(track.duration_seconds)"></div>
+                                    <button class="icon-btn" type="button" @click="removeReleaseTrack(track.id)" title="Remove from release">
+                                        <i data-lucide="x"></i>
+                                    </button>
+                                </div>
+                            </template>
+                        </div>
+                        <div class="empty" x-show="!releaseTracks().length">No tracks attached</div>
+                    </div>
+
                     <div class="editor-grid" x-show="isTrackEditor()">
                         <div class="field">
                             <label>Track #</label>
@@ -2585,9 +2708,9 @@ tbody tr:hover {
                     <div class="toolbar">
                         <button class="btn primary" @click="saveLibraryItem()" :disabled="!editorCanSave()">
                             <i :data-lucide="editorSaving ? 'loader-circle' : 'save'"></i>
-                            <span x-text="editorSaving ? 'Saving...' : 'Save'"></span>
+                            <span x-text="editorSaving ? 'Saving...' : (editorIsNewRelease() ? 'Create' : 'Save')"></span>
                         </button>
-                        <button class="btn danger" @click="deleteLibraryItem(activeLibraryItem)" :disabled="editorSaving || editorImageUploading">
+                        <button class="btn danger" x-show="!editorIsNewRelease()" @click="deleteLibraryItem(activeLibraryItem)" :disabled="editorSaving || editorImageUploading">
                             <i data-lucide="trash-2"></i>
                             Delete
                         </button>
@@ -2682,8 +2805,12 @@ function adminV2() {
         editorImageFile: null,
         editorArtistToAdd: '',
         editorReleaseToAdd: '',
+        releaseTrackSearch: '',
+        releaseTrackSearchResults: [],
+        releaseTrackSearchLoading: false,
+        releaseTrackSearchToken: 0,
         editorDetail: null,
-        editorDraft: { title: '', hidden: 'false', release_type: 'album', year: '', release_id: null, track_number: '', disc_number: '', artist_ids: [] },
+        editorDraft: { title: '', hidden: 'false', release_type: 'album', year: '', release_id: null, track_number: '', disc_number: '', artist_ids: [], release_tracks: [] },
         settings: { values: {}, sources: {}, lastfm_api_key_configured: false, lastfm_shared_secret_configured: false, lastfm_scrobbling_configured: false },
         settingsDraft: {
             auth_password_enabled: false,
@@ -3396,16 +3523,30 @@ function adminV2() {
                 release_id: null,
                 track_number: '',
                 disc_number: '',
-                artist_ids: []
+                artist_ids: [],
+                release_tracks: []
             };
             this.editorDetail = null;
             this.editorImageFile = null;
             this.editorArtistToAdd = '';
             this.editorReleaseToAdd = '';
+            this.clearReleaseTrackSearch();
             this.editorOpen = true;
             this.loadEditorDetail(item);
         },
 
+        openReleaseCreator() {
+            this.libraryKind = 'releases';
+            this.openEditor({
+                id: 0,
+                kind: 'releases',
+                title: '',
+                subtitle: 'New release',
+                is_hidden: false,
+                tags: []
+            });
+        },
+
         async loadEditorDetail(item) {
             const key = `${item.kind}:${item.id}`;
             this.editorLoading = true;
@@ -3422,11 +3563,13 @@ function adminV2() {
                     release_id: detail.release_id || null,
                     track_number: detail.track_number || '',
                     disc_number: detail.disc_number || '',
-                    artist_ids: Array.isArray(detail.selected_artist_ids) ? detail.selected_artist_ids.slice() : []
+                    artist_ids: Array.isArray(detail.selected_artist_ids) ? detail.selected_artist_ids.slice() : [],
+                    release_tracks: Array.isArray(detail.release_tracks) ? detail.release_tracks.map(track => this.normalizeReleaseTrack(track)) : []
                 };
                 this.editorImageFile = null;
                 this.editorArtistToAdd = '';
                 this.editorReleaseToAdd = '';
+                this.clearReleaseTrackSearch();
             } catch (error) {
                 this.showToast(error.message);
             } finally {
@@ -3449,8 +3592,22 @@ function adminV2() {
             return this.activeLibraryItem && this.activeLibraryItem.kind === 'tracks';
         },
 
+        editorIsNewRelease() {
+            return this.isReleaseEditor() && Number(this.activeLibraryItem.id || 0) === 0;
+        },
+
+        editorTitle() {
+            if (this.editorIsNewRelease()) return 'New release';
+            return this.activeLibraryItem?.title || 'Editor';
+        },
+
+        editorSubtitle() {
+            if (this.editorIsNewRelease()) return 'Create release and attach tracks';
+            return this.activeLibraryItem?.kind || 'Library entity';
+        },
+
         canEditLibraryImage() {
-            return this.isArtistEditor() || this.isReleaseEditor();
+            return this.isArtistEditor() || (this.isReleaseEditor() && !this.editorIsNewRelease());
         },
 
         canShowMetadataTags() {
@@ -3497,6 +3654,7 @@ function adminV2() {
 
         editorCanSave() {
             if (!this.activeLibraryItem || !this.editorDetail || this.editorLoading || this.editorSaving) return false;
+            if (!String(this.editorDraft.title || '').trim()) return false;
             if (this.isTrackEditor() && !this.editorDraft.release_id) return false;
             return true;
         },
@@ -3605,6 +3763,146 @@ function adminV2() {
             return true;
         },
 
+        normalizeReleaseTrack(track = {}) {
+            const trackNumber = track.track_number;
+            const discNumber = track.disc_number;
+            return {
+                id: Number(track.id),
+                title: track.title || `Track #${track.id}`,
+                artists: track.artists || '',
+                release_id: track.release_id == null ? null : Number(track.release_id),
+                release_title: track.release_title || '',
+                track_number: trackNumber == null ? '' : String(trackNumber),
+                disc_number: discNumber == null ? '' : String(discNumber),
+                duration_seconds: Number(track.duration_seconds || 0),
+                is_hidden: Boolean(track.is_hidden)
+            };
+        },
+
+        releaseTracks() {
+            if (!Array.isArray(this.editorDraft.release_tracks)) {
+                this.editorDraft.release_tracks = [];
+            }
+            return this.editorDraft.release_tracks;
+        },
+
+        releaseTrackPayload() {
+            return this.releaseTracks().map(track => ({
+                id: Number(track.id),
+                track_number: track.track_number || '',
+                disc_number: track.disc_number || ''
+            }));
+        },
+
+        releaseTrackIds() {
+            return new Set(this.releaseTracks().map(track => Number(track.id)));
+        },
+
+        releaseTrackSearchOpen() {
+            return this.isReleaseEditor() && String(this.releaseTrackSearch || '').trim().length > 0;
+        },
+
+        availableReleaseTrackResults() {
+            const selected = this.releaseTrackIds();
+            return (this.releaseTrackSearchResults || []).filter(track => !selected.has(Number(track.id)));
+        },
+
+        clearReleaseTrackSearch() {
+            this.releaseTrackSearch = '';
+            this.releaseTrackSearchResults = [];
+            this.releaseTrackSearchLoading = false;
+            this.releaseTrackSearchToken += 1;
+        },
+
+        async searchReleaseTracks() {
+            const query = String(this.releaseTrackSearch || '').trim();
+            if (!query) {
+                this.releaseTrackSearchResults = [];
+                this.releaseTrackSearchLoading = false;
+                return;
+            }
+            const token = this.releaseTrackSearchToken + 1;
+            this.releaseTrackSearchToken = token;
+            this.releaseTrackSearchLoading = true;
+            try {
+                const params = new URLSearchParams({ search: query, limit: '16' });
+                const rows = await this.request(`${this.apiBase}/library/tracks/search?${params.toString()}`);
+                if (this.releaseTrackSearchToken !== token) return;
+                this.releaseTrackSearchResults = Array.isArray(rows) ? rows.map(track => this.normalizeReleaseTrack(track)) : [];
+            } catch (error) {
+                if (this.releaseTrackSearchToken === token) this.showToast(error.message);
+            } finally {
+                if (this.releaseTrackSearchToken === token) {
+                    this.releaseTrackSearchLoading = false;
+                    this.icons();
+                }
+            }
+        },
+
+        async addBestReleaseTrack() {
+            if (!String(this.releaseTrackSearch || '').trim()) return;
+            if (!this.availableReleaseTrackResults().length && !this.releaseTrackSearchLoading) {
+                await this.searchReleaseTracks();
+            }
+            const track = this.availableReleaseTrackResults()[0];
+            if (!track) {
+                this.showToast('Choose a track from search results');
+                return;
+            }
+            this.addReleaseTrack(track);
+        },
+
+        addReleaseTrack(track) {
+            if (!track) return;
+            const normalized = this.normalizeReleaseTrack(track);
+            if (this.releaseTrackIds().has(Number(normalized.id))) {
+                this.showToast('Track already in release');
+                return;
+            }
+            this.editorDraft.release_tracks = this.releaseTracks().concat([normalized]);
+            this.clearReleaseTrackSearch();
+            this.$nextTick(() => this.icons());
+        },
+
+        removeReleaseTrack(id) {
+            this.editorDraft.release_tracks = this.releaseTracks().filter(track => Number(track.id) !== Number(id));
+        },
+
+        releaseTrackOrigin(track) {
+            const releaseId = Number(track && track.release_id ? track.release_id : 0);
+            const currentId = Number(this.activeLibraryItem && this.activeLibraryItem.id ? this.activeLibraryItem.id : 0);
+            if (releaseId && releaseId === currentId) return this.editorDraft.title || track.release_title || 'This release';
+            if (track && track.release_title) return track.release_title;
+            if (releaseId) return `Missing release #${releaseId}`;
+            return 'No release';
+        },
+
+        releaseTrackSearchMeta(track) {
+            const parts = [];
+            if (track.artists) parts.push(track.artists);
+            parts.push(this.releaseTrackOrigin(track));
+            const number = this.releaseTrackNumberLabel(track);
+            if (number) parts.push(number);
+            return parts.join(' / ');
+        },
+
+        releaseTrackNumberLabel(track) {
+            const disc = String((track && track.disc_number) || '').trim();
+            const number = String((track && track.track_number) || '').trim();
+            if (disc && number) return `D${disc} #${number}`;
+            if (number) return `#${number}`;
+            if (disc) return `D${disc}`;
+            return '';
+        },
+
+        trackDuration(seconds) {
+            const total = Math.round(Number(seconds || 0));
+            if (!total) return '-';
+            const minutes = Math.floor(total / 60);
+            const rest = String(total % 60).padStart(2, '0');
+            return `${minutes}:${rest}`;
+        },
+
         setEditorImageFile(event) {
             this.editorImageFile = event.target.files && event.target.files.length ? event.target.files[0] : null;
         },
@@ -3729,6 +4027,7 @@ function adminV2() {
             if (!this.editorCanSave()) return;
             this.editorSaving = true;
             try {
+                const wasNewRelease = this.editorIsNewRelease();
                 const updated = await this.request(`${this.apiBase}/library/item`, {
                     method: 'POST',
                     body: JSON.stringify({
@@ -3741,13 +4040,15 @@ function adminV2() {
                         release_id: this.editorDraft.release_id ? Number(this.editorDraft.release_id) : null,
                         track_number: this.editorDraft.track_number || '',
                         disc_number: this.editorDraft.disc_number || '',
-                        artist_ids: this.editorDraft.artist_ids || []
+                        artist_ids: this.editorDraft.artist_ids || [],
+                        release_tracks: this.isReleaseEditor() ? this.releaseTrackPayload() : null
                     })
                 });
                 this.replaceLibraryItem(updated);
                 this.activeLibraryItem = updated;
                 if (this.editorDetail) this.editorDetail.item = updated;
-                this.showToast('Saved');
+                if (this.isReleaseEditor()) await this.loadEditorDetail(updated);
+                this.showToast(wasNewRelease ? 'Release created' : 'Saved');
                 await this.refreshCountsOnly();
             } catch (error) {
                 this.showToast(error.message);
@@ -3768,9 +4069,18 @@ function adminV2() {
         },
 
         replaceLibraryItem(updated) {
-            this.library.items = this.library.items.map(item =>
-                item.kind === updated.kind && item.id === updated.id ? updated : item
-            );
+            let replaced = false;
+            this.library.items = this.library.items.map(item => {
+                if (item.kind === updated.kind && Number(item.id) === Number(updated.id)) {
+                    replaced = true;
+                    return updated;
+                }
+                return item;
+            });
+            if (!replaced && updated.kind === this.libraryKind) {
+                this.library.items = [updated].concat(this.library.items || []);
+                this.library.total = Number(this.library.total || 0) + 1;
+            }
         },
 
         async refreshCountsOnly() {

templates/player/scripts.html

@@ -822,6 +822,7 @@ document.addEventListener('alpine:init', () => {
 
         _playLocal(track, options = {}) {
             this.currentTrack = track;
+            Alpine.store('queue')?.syncCurrentIndexToTrack(track);
             this._localSourceTrackId = track.id;
             this._historyRecorded = false;
             this._resetPlaybackTracking();
@@ -1138,6 +1139,7 @@ document.addEventListener('alpine:init', () => {
         _mirrorRemoteTrack(track, playing, positionSeconds = null) {
             if (!track) return;
             this.currentTrack = track;
+            Alpine.store('queue')?.syncCurrentIndexToTrack(track);
             this.isPlaying = !!playing;
             if (positionSeconds !== null) this.currentTime = Math.max(0, Number(positionSeconds || 0));
             this.duration = Number(track.duration_seconds || this.duration || 0);
@@ -1158,6 +1160,7 @@ document.addEventListener('alpine:init', () => {
             const track = state.track || queue?.tracks?.[queue.currentIndex] || null;
             if (track) {
                 this.currentTrack = track;
+                queue?.syncCurrentIndexToTrack(track);
             }
             this.shuffle = !!state.shuffle;
             this.repeatMode = state.repeat_mode || 'off';
@@ -1359,6 +1362,7 @@ document.addEventListener('alpine:init', () => {
                                     : tracks[idx];
                                 if (currentTrack) {
                                     this.currentTrack = currentTrack;
+                                    queue.syncCurrentIndexToTrack(currentTrack);
                                     this._localSourceTrackId = currentTrack.id;
                                     this._historyRecorded = false;
                                     this._resetPlaybackTracking();
@@ -1976,6 +1980,56 @@ document.addEventListener('alpine:init', () => {
             return this.tracks.slice(start, start + limit);
         },
 
+        effectiveCurrentIndex() {
+            const currentTrack = Alpine.store('player')?.currentTrack || null;
+            if (currentTrack?.id) {
+                return this.tracks.findIndex(track => Number(track?.id) === Number(currentTrack.id));
+            }
+            if (!this.tracks.length) return -1;
+            return Math.max(0, Math.min(Number(this.currentIndex || 0), this.tracks.length - 1));
+        },
+
+        queueItemState(index) {
+            const current = this.effectiveCurrentIndex();
+            if (current < 0) return 'upcoming';
+            if (index < current) return 'played';
+            if (index === current) return 'current';
+            return 'upcoming';
+        },
+
+        displayItems() {
+            const current = this.effectiveCurrentIndex();
+            const playerTrack = Alpine.store('player')?.currentTrack || null;
+            const items = this.tracks.map((track, index) => ({
+                track,
+                index,
+                key: `${index}-${track?.id || 'track'}`,
+                state: current >= 0
+                    ? (index < current ? 'played' : (index === current ? 'current' : 'upcoming'))
+                    : 'upcoming',
+                synthetic: false,
+            }));
+
+            if (playerTrack?.id && current < 0) {
+                items.unshift({
+                    track: playerTrack,
+                    index: -1,
+                    key: `current-${playerTrack.id}`,
+                    state: 'current',
+                    synthetic: true,
+                });
+            }
+
+            return items;
+        },
+
+        syncCurrentIndexToTrack(track) {
+            if (!track?.id || !this.tracks.length) return -1;
+            const index = this.tracks.findIndex(item => Number(item?.id) === Number(track.id));
+            if (index >= 0) this.currentIndex = index;
+            return index;
+        },
+
         addToEnd(tracks) {
             const items = this._tracksForQueueAdd(tracks);
             if (!items.length) return;

templates/player/shell.html

@@ -959,42 +959,43 @@
                 </div>
             </div>
             <div class="queue-tracks">
-                <template x-if="$store.queue.tracks.length === 0">
+                <template x-if="$store.queue.displayItems().length === 0">
                     <div class="empty-state">
                         <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M9 18V5l12-2v13"/><circle cx="6" cy="18" r="3"/><circle cx="18" cy="16" r="3"/></svg>
                         <p>{{ t.player_queue_empty }}</p>
                     </div>
                 </template>
-                <template x-for="(track, idx) in $store.queue.tracks" :key="idx + '-' + track.id">
+                <template x-for="item in $store.queue.displayItems()" :key="item.key">
                     <div class="queue-track"
-                         :data-queue-index="idx"
-                         :class="{ active: idx === $store.queue.currentIndex, dragging: $store.queue._dragIdx === idx, 'foreign-jam-track': $store.queue.isForeignJamTrack(track) }"
-                         :style="$store.queue.isForeignJamTrack(track) ? $store.queue.contributorStyle(track) : ''"
-                         @click="$store.queue.playFromIndex(idx)"
-                         draggable="true"
-                         @dragstart="$store.queue._dragIdx = idx; $event.dataTransfer.effectAllowed = 'move'"
+                         :data-queue-index="item.index"
+                         :class="{ active: item.state === 'current', current: item.state === 'current', played: item.state === 'played', dragging: $store.queue._dragIdx === item.index, synthetic: item.synthetic, 'foreign-jam-track': $store.queue.isForeignJamTrack(item.track) }"
+                         :style="$store.queue.isForeignJamTrack(item.track) ? $store.queue.contributorStyle(item.track) : ''"
+                         @click="item.index >= 0 ? $store.queue.playFromIndex(item.index) : $store.player.play(item.track)"
+                         :draggable="!item.synthetic"
+                         @dragstart="if (item.synthetic) { $event.preventDefault(); } else { $store.queue._dragIdx = item.index; $event.dataTransfer.effectAllowed = 'move'; }"
                          @dragend="$store.queue._dragIdx = null; document.querySelectorAll('.drag-over').forEach(el => el.classList.remove('drag-over'))"
                          @dragover.prevent="$event.dataTransfer.dropEffect = 'move'; $event.currentTarget.classList.add('drag-over')"
                          @dragleave="$event.currentTarget.classList.remove('drag-over')"
-                         @drop.prevent="$event.currentTarget.classList.remove('drag-over'); if ($store.queue._dragIdx !== null) { $store.queue.moveTrack($store.queue._dragIdx, idx); $store.queue._dragIdx = null; }">
+                         @drop.prevent="$event.currentTarget.classList.remove('drag-over'); if (!item.synthetic && $store.queue._dragIdx !== null) { $store.queue.moveTrack($store.queue._dragIdx, item.index); $store.queue._dragIdx = null; }">
                         <div class="queue-drag-handle"
+                             x-show="!item.synthetic"
                              @mousedown.stop
                              @click.stop
-                             @pointerdown.stop="$store.queue.startPointerReorder($event, idx)">
+                             @pointerdown.stop="$store.queue.startPointerReorder($event, item.index)">
                             <svg viewBox="0 0 24 24" fill="currentColor"><circle cx="9" cy="6" r="1.5"/><circle cx="15" cy="6" r="1.5"/><circle cx="9" cy="12" r="1.5"/><circle cx="15" cy="12" r="1.5"/><circle cx="9" cy="18" r="1.5"/><circle cx="15" cy="18" r="1.5"/></svg>
                         </div>
                         <div class="queue-track-cover">
-                            <template x-if="track.cover_url">
-                                <img :src="track.cover_url" :alt="track.title" loading="lazy">
+                            <template x-if="item.track.cover_url">
+                                <img :src="item.track.cover_url" :alt="item.track.title" loading="lazy">
                             </template>
-                            <template x-if="!track.cover_url">
+                            <template x-if="!item.track.cover_url">
                                 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M9 18V5l12-2v13"/><circle cx="6" cy="18" r="3"/><circle cx="18" cy="16" r="3"/></svg>
                             </template>
                         </div>
                         <div class="queue-track-info">
-                            <div class="queue-track-title" x-text="track.title"></div>
+                            <div class="queue-track-title" x-text="item.track.title"></div>
                             <div class="queue-track-artist">
-                                <template x-for="(artist, artistIdx) in $store.library.trackArtistLinks(track)" :key="artist.label + '-' + artist.id + '-' + artistIdx">
+                                <template x-for="(artist, artistIdx) in $store.library.trackArtistLinks(item.track)" :key="artist.label + '-' + artist.id + '-' + artistIdx">
                                     <span>
                                         <template x-if="artistIdx > 0"><span>, </span></template>
                                         <a class="artist-link" @click.stop="$store.library.openArtist(artist.id)" x-text="artist.label"></a>
@@ -1004,15 +1005,15 @@
                         </div>
                         <div class="queue-track-actions">
                             <button class="queue-track-remove info-btn popularity-info-btn"
-                                    :class="{ 'has-popularity': $store.library.hasPopularity(track), 'no-popularity': !$store.library.hasPopularity(track) }"
-                                    :style="$store.library.popularityStyle(track)"
-                                    @click.stop="$store.library.openTrackInfo(track)"
-                                    :title="$store.library.trackInfoTitle(track)"
+                                    :class="{ 'has-popularity': $store.library.hasPopularity(item.track), 'no-popularity': !$store.library.hasPopularity(item.track) }"
+                                    :style="$store.library.popularityStyle(item.track)"
+                                    @click.stop="$store.library.openTrackInfo(item.track)"
+                                    :title="$store.library.trackInfoTitle(item.track)"
                                     aria-label="{{ t.player_track_info }}">
-                                <span x-show="$store.library.hasPopularity(track)" x-text="$store.library.popularityLabel(track)"></span>
-                                <span x-show="!$store.library.hasPopularity(track)" class="info-letter">i</span>
+                                <span x-show="$store.library.hasPopularity(item.track)" x-text="$store.library.popularityLabel(item.track)"></span>
+                                <span x-show="!$store.library.hasPopularity(item.track)" class="info-letter">i</span>
                             </button>
-                            <button class="queue-track-remove" @click.stop="$store.queue.remove(idx)" title="{{ t.player_remove }}">
+                            <button class="queue-track-remove" x-show="!item.synthetic" @click.stop="$store.queue.remove(item.index)" title="{{ t.player_remove }}">
                                 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="14" height="14"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
                             </button>
                         </div>
@@ -1292,27 +1293,27 @@
             </div>
             <div class="mobile-expanded-queue">
             <div class="mobile-expanded-queue-title">{{ t.player_queue }}</div>
-            <template x-if="$store.queue.upcoming().length === 0">
+            <template x-if="$store.queue.displayItems().length === 0">
                 <div class="mobile-expanded-queue-empty">{{ t.player_queue_empty }}</div>
             </template>
-            <template x-for="(track, idx) in $store.queue.upcoming()" :key="'mobile-expanded-queue-' + track.id + '-' + idx">
+            <template x-for="item in $store.queue.displayItems()" :key="'mobile-expanded-queue-' + item.key">
                 <button class="mobile-expanded-queue-row"
-                        :class="{ 'foreign-jam-track': $store.queue.isForeignJamTrack(track) }"
-                        :style="$store.queue.isForeignJamTrack(track) ? $store.queue.contributorStyle(track) : ''"
+                        :class="{ current: item.state === 'current', played: item.state === 'played', 'foreign-jam-track': $store.queue.isForeignJamTrack(item.track) }"
+                        :style="$store.queue.isForeignJamTrack(item.track) ? $store.queue.contributorStyle(item.track) : ''"
                         type="button"
-                        @click="$store.queue.playFromIndex($store.queue.currentIndex + idx + 1)">
+                        @click="item.index >= 0 ? $store.queue.playFromIndex(item.index) : $store.player.play(item.track)">
                     <div class="mobile-expanded-queue-cover">
-                        <template x-if="track.cover_url">
-                            <img :src="track.cover_url" :alt="track.title" loading="lazy">
+                        <template x-if="item.track.cover_url">
+                            <img :src="item.track.cover_url" :alt="item.track.title" loading="lazy">
                         </template>
-                        <template x-if="!track.cover_url">
+                        <template x-if="!item.track.cover_url">
                             <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M9 18V5l12-2v13"/><circle cx="6" cy="18" r="3"/><circle cx="18" cy="16" r="3"/></svg>
                         </template>
                     </div>
                     <div class="mobile-expanded-queue-info">
-                        <div class="mobile-expanded-queue-name" x-text="track.title"></div>
+                        <div class="mobile-expanded-queue-name" x-text="item.track.title"></div>
                         <div class="mobile-expanded-queue-artist">
-                            <template x-for="(artist, artistIdx) in $store.library.trackArtistLinks(track)" :key="artist.label + '-' + artist.id + '-' + artistIdx">
+                            <template x-for="(artist, artistIdx) in $store.library.trackArtistLinks(item.track)" :key="artist.label + '-' + artist.id + '-' + artistIdx">
                                 <span>
                                     <template x-if="artistIdx > 0"><span>, </span></template>
                                     <span x-text="artist.label"></span>
@@ -1320,7 +1321,7 @@
                             </template>
                         </div>
                     </div>
-                    <span class="mobile-expanded-queue-time" x-text="formatTime(track.duration_seconds)"></span>
+                    <span class="mobile-expanded-queue-time" x-text="formatTime(item.track.duration_seconds)"></span>
                 </button>
             </template>
             </div>

templates/player/styles.html

@@ -1224,7 +1224,22 @@ button.user-stat:hover {
 }
 
 .queue-track:hover { background: var(--bg-hover); }
-.queue-track.active { background: var(--bg-active); }
+.queue-track.active,
+.queue-track.current { background: var(--bg-active); }
+.queue-track.played {
+    color: var(--text-subdued);
+    opacity: 0.58;
+}
+.queue-track.played:hover {
+    opacity: 0.78;
+}
+.queue-track.played .queue-track-cover {
+    filter: grayscale(1);
+    opacity: 0.72;
+}
+.queue-track.synthetic .queue-drag-handle {
+    display: none;
+}
 .queue-track.foreign-jam-track {
     background: linear-gradient(90deg, var(--jam-contributor-bg, rgba(82,145,255,0.12)), transparent 78%);
 }
@@ -1259,7 +1274,9 @@ button.user-stat:hover {
     text-overflow: ellipsis;
 }
 
-.queue-track.active .queue-track-title { color: var(--accent); }
+.queue-track.active .queue-track-title,
+.queue-track.current .queue-track-title { color: var(--accent); }
+.queue-track.played .queue-track-title { color: var(--text-subdued); }
 
 .queue-track-artist {
     font-size: 11px;
@@ -4925,6 +4942,28 @@ button.user-stat:hover {
         background: var(--bg-hover);
     }
 
+    .mobile-expanded-queue-row.current {
+        background: var(--bg-active);
+    }
+
+    .mobile-expanded-queue-row.current .mobile-expanded-queue-name {
+        color: var(--accent);
+    }
+
+    .mobile-expanded-queue-row.played {
+        color: var(--text-subdued);
+        opacity: 0.56;
+    }
+
+    .mobile-expanded-queue-row.played:active {
+        opacity: 0.74;
+    }
+
+    .mobile-expanded-queue-row.played .mobile-expanded-queue-cover {
+        filter: grayscale(1);
+        opacity: 0.72;
+    }
+
     .mobile-expanded-queue-row.foreign-jam-track {
         background: linear-gradient(90deg, var(--jam-contributor-bg, rgba(82,145,255,0.12)), transparent 82%);
     }