From 5a49c5b097a26e11016a80f49da65ab5e5fa0a54 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 26 Oct 2026 09:35:28 +0100
Subject: [PATCH 1/4] refactor(config): move config.rs and cli.rs to their own
 directories

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 src/{cli.rs => cli/mod.rs}       | 0
 src/{config.rs => config/mod.rs} | 0
 2 files changed, 0 insertions(+), 0 deletions(-)
 rename src/{cli.rs => cli/mod.rs} (100%)
 rename src/{config.rs => config/mod.rs} (100%)

diff --git a/src/cli.rs b/src/cli/mod.rs
similarity index 100%
rename from src/cli.rs
rename to src/cli/mod.rs
diff --git a/src/config.rs b/src/config/mod.rs
similarity index 100%
rename from src/config.rs
rename to src/config/mod.rs

From 9247edc5dc14e2dd957d705bd83b10b0a3f50e09 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 26 Oct 2026 09:51:49 +0100
Subject: [PATCH 2/4] refactor(app): split the crate root into an app module of
 state, boot, router and openapi

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 src/app/boot.rs    |  234 ++++++++
 src/app/mod.rs     |   20 +
 src/app/openapi.rs |  625 ++++++++++++++++++++
 src/app/router.rs  |  222 +++++++
 src/app/state.rs   |   70 +++
 src/app/tests.rs   |  256 ++++++++
 src/lib.rs         | 1387 +-------------------------------------------
 7 files changed, 1429 insertions(+), 1385 deletions(-)
 create mode 100644 src/app/boot.rs
 create mode 100644 src/app/mod.rs
 create mode 100644 src/app/openapi.rs
 create mode 100644 src/app/router.rs
 create mode 100644 src/app/state.rs
 create mode 100644 src/app/tests.rs

diff --git a/src/app/boot.rs b/src/app/boot.rs
new file mode 100644
index 00000000..dedabc2a
--- /dev/null
+++ b/src/app/boot.rs
@@ -0,0 +1,234 @@
+//! Bringing the state up — the migrations, the instance key, every service
+//! and outbound adapter — and the signal that takes the server down.
+
+use std::{sync::Arc, time::Duration};
+
+use super::state::{chunk_body_limit, negotiation_body_limit, AppState};
+use crate::{
+    authentication, database, enrichment, link_roots, lrclib, media, migration_backup, quality,
+    scanner, scrobblers, security, services, setup_token, sync, Config,
+};
+
+pub async fn initialize(config: &Config) -> anyhow::Result<AppState> {
+    let db = database::Database::open(config).await?;
+    let booted = boot(db.clone(), config).await;
+    if booted.is_err() {
+        // A refused boot closes what it opened before it says so. Dropping the
+        // pool would not be enough: sqlx closes each connection on its own
+        // thread after the drop has returned, and the last one to close
+        // checkpoints the WAL under an exclusive lock. Whoever opens the file
+        // next — the operator retrying, or a test that has just watched the
+        // refusal — races that close and can find the database locked.
+        db.pool().close().await;
+    }
+    booted
+}
+
+async fn boot(db: database::Database, config: &Config) -> anyhow::Result<AppState> {
+    // Before anything is applied, and only when something will be (RFC-019
+    // decision 3): the copy is the database as this boot found it.
+    let copy = migration_backup::before_migrating(&db, config).await?;
+    if let Err(error) = db.migrate().await {
+        return Err(match copy {
+            Some(copy) => error.context(migration_backup::restore_hint(&copy)),
+            None => error,
+        });
+    }
+    let secret_box = Arc::new(security::SecretBox::load_or_create(
+        &config.instance_key_path,
+    )?);
+    let instance_key = std::fs::read(&config.instance_key_path)?;
+    let fingerprint = security::bytes_hash(&instance_key);
+    if !db
+        .bind_instance_key(&fingerprint, authentication::now_ms())
+        .await?
+    {
+        anyhow::bail!(
+            "instance.key does not match waveflow.db; restore the database and key from the same backup bundle"
+        );
+    }
+    // After the key check, not before: a mismatched pair aborts the boot, and
+    // scheduling a rescan on a database this instance is about to refuse would
+    // be writing to a catalogue that is not ours.
+    db.reconcile_catalog_identity(&config.pid).await?;
+    // After the key check too: a boot that is about to be refused has no
+    // business writing a token into a data directory that is not its own.
+    let setup = Arc::new(setup_token::SetupGate::prepare(
+        config,
+        db.setup_required().await?,
+    )?);
+    let auth = authentication::AuthService::new(db.clone(), config);
+    let scanner = scanner::ScanManager::new(
+        db.clone(),
+        config.artwork_dir.clone(),
+        config.scan_parallelism,
+    )
+    .with_link_roots(link_roots::LinkRoots::new(config.link_roots.clone()));
+    let media = media::MediaService::initialize(config).await?;
+    let sync = sync::SyncService::new(db.clone());
+    let services = services::DomainServices::new(
+        db.clone(),
+        Arc::clone(&secret_box),
+        sync.clone(),
+        scanner.clone(),
+        config,
+    );
+    // One of the two outbound surfaces this server has — metadata enrichment,
+    // below, is the other — and it is switched on by the operator naming a
+    // destination rather than by anybody linking an account.
+    // Nothing leaves until both are true: an adapter with no authorisation
+    // behind it is never handed a listen. RFC-010 decision 11.
+    for destination in &config.destinations {
+        // `Config::from_env` refuses to boot on a malformed destination, so the
+        // URL reaching here has already been through `validate_destination` —
+        // and `for_data_dir` builds an empty list rather than an unchecked one.
+        //
+        // Building the client is a different matter and really can fail at
+        // runtime, for reasons that have nothing to do with the operator's URL.
+        let target = match destination.provider {
+            services::ScrobbleProvider::ListenBrainz => {
+                scrobblers::outbound_client(config.scrobbling.request_timeout)
+                    .and_then(|client| {
+                        scrobblers::listenbrainz::ListenBrainz::new(client, &destination.url)
+                    })
+                    .map(|target| Arc::new(target) as Arc<dyn services::ScrobbleTarget>)
+            }
+            services::ScrobbleProvider::Maloja => {
+                scrobblers::outbound_client(config.scrobbling.request_timeout)
+                    .and_then(|client| scrobblers::maloja::Maloja::new(client, &destination.url))
+                    .map(|target| Arc::new(target) as Arc<dyn services::ScrobbleTarget>)
+            }
+            // **Last.fm needs more than a URL**, and a destination declared
+            // without it is not an error. Decision 4 forbids shipping any
+            // provider credential in an AGPL binary, so the application belongs
+            // to the operator; without one, the name stays listed — with the
+            // reason, which `GET /api/v2/scrobble-destinations` publishes — and
+            // nothing drains for it.
+            services::ScrobbleProvider::LastFm => {
+                let Some(application) = config.lastfm.clone() else {
+                    continue;
+                };
+                scrobblers::outbound_client(config.scrobbling.request_timeout)
+                    .and_then(|client| {
+                        scrobblers::lastfm::LastFm::new(
+                            client,
+                            &destination.url,
+                            application,
+                            config.scrobbling.request_timeout,
+                        )
+                    })
+                    .map(|target| {
+                        let target = Arc::new(target);
+                        // The same object in both registries: submitting a
+                        // listen and exchanging a token are two calls to one
+                        // destination, signed by one application, and splitting
+                        // them would be two places for that to drift.
+                        services.register_lastfm_exchange(
+                            &destination.name,
+                            Arc::clone(&target) as Arc<dyn services::LastFmSessionExchange>,
+                        );
+                        target as Arc<dyn services::ScrobbleTarget>
+                    })
+            }
+        };
+        match target {
+            Ok(target) => {
+                services.register_scrobble_target(destination.provider, &destination.name, target)
+            }
+            Err(error) => {
+                // **Never the URL itself.** `validate_destination` refuses a
+                // destination that carries credentials, so the one thing this
+                // branch is most likely to be handed is exactly the thing that
+                // must not be printed: `http://user:secret@host` would land in
+                // a startup log, or a support paste, in full. The variant names
+                // the fault precisely enough without it, and this repository's
+                // rule about secrets has no exception for an error path.
+                anyhow::bail!(
+                    "the configured {} destination {:?} is unusable: {error}",
+                    destination.provider.as_str(),
+                    destination.name
+                )
+            }
+        }
+    }
+    // Catching up and reconciling, once, under the writer gate — and *before*
+    // `main` starts the drain. The order is half the rule: reconciling while
+    // the background task already runs leaves a window, short and sufficient,
+    // in which listens leave for yesterday's destination. RFC-010 decision 10.
+    services.reconcile_scrobble_links().await?;
+    // A portrait search left fetching has no task across a restart; left at
+    // `complete = 0` it would hold its account's next search at 429 until its
+    // deadline passed (RFC-013 decision 4).
+    services.forget_unfinished_image_searches().await?;
+    // A podcast download the last process left running has no task any more
+    // (RFC-025): it goes back to `new`, and its staging file goes.
+    services.reconcile_podcasts().await?;
+    // Off unless the operator named a provider, and then it still makes no
+    // request until somebody asks about an artist (RFC-011 decisions 3 and 6).
+    services.use_enrichment(enrichment::Enrichment::new(
+        db.clone(),
+        &config.metadata,
+        config.artwork_dir.clone(),
+    )?);
+    // Off unless the operator named `lrclib`, and then it still asks nothing
+    // until somebody asks for the lyrics of a track that has none (RFC-024
+    // decisions 1 and 3).
+    services.use_lyrics_lookup(lrclib::LyricsLookup::new(db.clone(), &config.lyrics)?);
+    // Before anything reads `track_quality`: a measurement another analyser or
+    // another FFmpeg made is deleted here, so every read can call a row current
+    // on its content hash alone (RFC-016 decision 5).
+    services
+        .use_quality_decoder(quality::Decoder {
+            digest: media.ffmpeg_digest().to_owned(),
+            webp: quality::probe_webp(&config.ffmpeg_path).await,
+        })
+        .await?;
+    Ok(AppState {
+        db,
+        auth,
+        secret_box,
+        scanner,
+        media,
+        services,
+        sync,
+        artwork_dir: config.artwork_dir.clone(),
+        instance_key_path: config.instance_key_path.clone(),
+        public_url: config.public_url.clone(),
+        stream_ticket_ttl: config.stream_ticket_ttl,
+        refresh_token_ttl: config.refresh_token_ttl,
+        upload_batch_body_limit: negotiation_body_limit(&config.uploads),
+        upload_chunk_body_limit: chunk_body_limit(&config.uploads),
+        // Refused at startup if it does not fit, so this conversion cannot be
+        // the place that decides what a ceiling falls back to.
+        canvas_body_limit: usize::try_from(config.canvas.max_bytes).unwrap_or(usize::MAX),
+        trusted_proxies: config.trusted_proxies.clone().into(),
+        setup,
+    })
+}
+
+pub async fn shutdown_signal() {
+    let ctrl_c = async {
+        if let Err(error) = tokio::signal::ctrl_c().await {
+            tracing::error!(error = %error, "failed to install Ctrl-C handler");
+        }
+    };
+
+    #[cfg(unix)]
+    let terminate = async {
+        match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) {
+            Ok(mut signal) => {
+                signal.recv().await;
+            }
+            Err(error) => tracing::error!(error = %error, "failed to install terminate handler"),
+        }
+    };
+
+    #[cfg(not(unix))]
+    let terminate = std::future::pending::<()>();
+
+    tokio::select! {
+        () = ctrl_c => {},
+        () = terminate => {},
+    }
+    tokio::time::sleep(Duration::from_millis(25)).await;
+}
diff --git a/src/app/mod.rs b/src/app/mod.rs
new file mode 100644
index 00000000..54d31485
--- /dev/null
+++ b/src/app/mod.rs
@@ -0,0 +1,20 @@
+//! The assembled server: the state every surface shares, the boot that
+//! builds it, the router that serves it and the OpenAPI document it
+//! publishes.
+//!
+//! Private on purpose. What it holds was public at the crate root before it
+//! had a module of its own, and is still reached there through the
+//! re-exports in `lib.rs`.
+
+mod boot;
+mod openapi;
+mod router;
+mod state;
+
+pub use boot::{initialize, shutdown_signal};
+pub use openapi::{ApiDoc, OPENAPI_JSON_PATH, SCALAR_PATH};
+pub use router::app;
+pub use state::AppState;
+
+#[cfg(test)]
+mod tests;
diff --git a/src/app/openapi.rs b/src/app/openapi.rs
new file mode 100644
index 00000000..eb56d758
--- /dev/null
+++ b/src/app/openapi.rs
@@ -0,0 +1,625 @@
+//! The OpenAPI document: the routes and schemas it lists, the passes that
+//! state once what holds of every route in a class, and the route that
+//! serves it.
+
+use axum::response::{IntoResponse, Response};
+use utoipa::OpenApi;
+
+use crate::{api, authentication, catalog, database, lyrics, media, services, sync};
+
+pub const OPENAPI_JSON_PATH: &str = "/openapi.json";
+pub const SCALAR_PATH: &str = "/reference";
+
+#[derive(OpenApi)]
+#[openapi(
+    info(
+        title = "WaveFlow Server API",
+        version = env!("CARGO_PKG_VERSION"),
+        description = "Self-hosted WaveFlow music server v2.",
+        license(name = "AGPL-3.0-only")
+    ),
+    paths(
+        api::health,
+        api::ready,
+        api::setup_status,
+        api::setup,
+        api::login,
+        api::refresh,
+        api::logout,
+        api::web_login,
+        api::web_refresh,
+        api::web_logout,
+        api::oauth_authorize,
+        api::oauth_token,
+        api::start_scan,
+        api::list_libraries,
+        api::create_library,
+        api::update_library,
+        api::delete_library,
+        api::library_settings,
+        api::unavailable_tracks,
+        api::purge_unavailable_tracks,
+        api::purged_tracks,
+        api::restore_purged_tracks,
+        api::list_library_members,
+        api::set_library_member,
+        api::remove_library_member,
+        api::scan_status,
+        api::scan_events,
+        api::library_events,
+        api::library_events_ack,
+        api::negotiate_uploads,
+        api::upload_session,
+        api::upload_chunk,
+        api::commit_upload,
+        api::list_tracks,
+        api::library_tree,
+        api::list_folders,
+        api::create_folder,
+        api::update_folder,
+        api::delete_folder,
+        api::folder_tracks,
+        api::place_tracks,
+        api::attention_summary,
+        api::attention_credits,
+        api::attention_tracks,
+        api::list_credit_decisions,
+        api::create_credit_decision,
+        api::delete_credit_decision,
+        api::quality_summary,
+        api::quality_tracks,
+        api::request_quality_analysis,
+        api::track_quality,
+        api::track_spectrogram,
+        api::get_track,
+        api::update_track,
+        api::get_track_lyrics,
+        api::put_track_lyrics,
+        api::delete_track_lyrics,
+        api::get_track_lyrics_file,
+        api::get_track_overrides,
+        api::list_albums,
+        api::list_genres,
+        api::get_album,
+        api::list_artists,
+        api::get_artist,
+        api::put_artist_image,
+        api::delete_artist_image,
+        api::list_artist_image_candidates,
+        api::put_artist_deezer_portrait,
+        api::list_artist_top_songs,
+        api::list_artist_albums,
+        api::search_catalog,
+        api::list_songs,
+        api::list_random_songs,
+        api::get_listening_stats,
+        api::list_mixes,
+        api::get_mix,
+        api::list_similar_songs,
+        api::list_songs_by_genre,
+        api::list_playlists,
+        api::create_playlist,
+        api::import_playlist,
+        api::export_playlist,
+        api::get_playlist,
+        api::update_playlist,
+        api::move_playlist_entry,
+        api::remove_playlist_entry,
+        api::delete_playlist,
+        api::list_smart_playlists,
+        api::create_smart_playlist,
+        api::preview_smart_playlist,
+        api::get_smart_playlist,
+        api::update_smart_playlist,
+        api::delete_smart_playlist,
+        api::podcast_overview,
+        api::create_podcast_channel,
+        api::refresh_podcasts,
+        api::get_podcast_channel,
+        api::delete_podcast_channel,
+        api::newest_podcast_episodes,
+        api::get_podcast_episode,
+        api::download_podcast_episode,
+        api::delete_podcast_episode,
+        api::list_favorites,
+        api::add_favorite,
+        api::remove_favorite,
+        api::set_rating,
+        api::list_ratings,
+        api::create_scrobble,
+        api::list_history,
+        api::list_now_playing,
+        api::list_scrobble_links,
+        api::list_scrobble_destinations,
+        api::link_scrobble,
+        api::unlink_scrobble,
+        api::authorize_lastfm,
+        api::lastfm_callback,
+        api::list_uncertain_scrobbles,
+        api::discard_uncertain_scrobble,
+        api::retry_uncertain_scrobble,
+        api::get_queue,
+        api::save_queue,
+        api::list_shares,
+        api::create_share,
+        api::update_share,
+        api::delete_share,
+        api::sync_changes,
+        api::sync_snapshot,
+        api::sync_ack,
+        api::sync_socket,
+        api::transcode_status,
+        api::list_users,
+        api::create_user,
+        api::update_user,
+        api::delete_user,
+        api::set_subsonic_credential,
+        api::revoke_subsonic_credential,
+        api::list_radio_stations,
+        api::get_radio_station,
+        api::create_radio_station,
+        api::replace_radio_station,
+        api::delete_radio_station,
+        api::list_bookmarks,
+        api::set_bookmark,
+        api::delete_bookmark,
+        api::list_own_api_tokens,
+        api::create_own_api_token,
+        api::revoke_own_api_token,
+        api::own_subsonic_credential,
+        api::rotate_own_subsonic_credential,
+        api::revoke_own_subsonic_credential,
+        api::list_api_tokens,
+        api::create_api_token,
+        api::revoke_api_token,
+        media::stream_track,
+        media::create_stream_ticket,
+        media::stream_with_ticket,
+        media::artwork,
+        media::canvas_by_hash,
+        media::canvas_for_track,
+        media::put_canvas,
+        media::delete_canvas,
+        media::create_canvas_ticket,
+        media::canvas_with_ticket
+    ),
+    components(schemas(
+        api::ProbeResponse,
+        api::ReadyResponse,
+        api::SetupStatusResponse,
+        api::SetupRequest,
+        api::SetupResponse,
+        api::LoginRequest,
+        api::RefreshRequest,
+        api::WebAuthResponse,
+        api::ErrorResponse,
+        authentication::AuthTokens,
+        authentication::AuthUser,
+        database::AccountRole,
+        api::ScanQueuedResponse,
+        catalog::ScanJobRecord,
+        catalog::TrackRecord,
+        catalog::LibraryAccess,
+        api::DeleteLibraryRequest,
+        services::LibraryUpdate,
+        services::LibraryUpdated,
+        services::LibrarySettings,
+        services::LibraryDeleted,
+        services::UnavailableTrack,
+        services::UnavailableTracks,
+        services::PurgeRequest,
+        services::PurgeOutcome,
+        services::RestoreOutcome,
+        services::AlbumItem,
+        services::ReleaseGroup,
+        services::ArtistItem,
+        services::GenreItem,
+        services::LibraryMember,
+        services::SongItem,
+        services::TrackDetail,
+        services::TrackOverrides,
+        services::TrackOverrideValues,
+        services::TrackSourceTags,
+        lyrics::LyricsList,
+        lyrics::StructuredLyrics,
+        lyrics::LyricsLine,
+        services::ArtistSummary,
+        services::AlbumDetail,
+        services::ArtistDetail,
+        services::ArtistEnrichment,
+        services::EnrichmentState,
+        services::EnrichmentSource,
+        services::EnrichedBio,
+        services::EnrichedImage,
+        services::EnrichedSimilar,
+        services::ListeningStats,
+        services::StatsBucketSize,
+        services::StatsTotals,
+        services::StatsBucket,
+        services::TopTrack,
+        services::TopAlbum,
+        services::TopArtist,
+        services::TopGenre,
+        services::PlayMoment,
+        services::MixSummary,
+        services::Mix,
+        services::SearchResult,
+        services::PlaylistItem,
+        services::SmartPlaylistItem,
+        services::SmartPlaylistPreview,
+        services::SmartRules,
+        services::SmartCondition,
+        services::SmartMatch,
+        services::SmartField,
+        services::SmartOperator,
+        services::SmartSort,
+        services::SmartOrder,
+        api::SmartPlaylistRequest,
+        api::SmartPlaylistPatch,
+        api::SmartPreviewRequest,
+        api::RuleErrorResponse,
+        services::PodcastOverview,
+        services::PodcastChannelItem,
+        services::PodcastEpisodeItem,
+        api::CreatePodcastChannelRequest,
+        api::FeedErrorResponse,
+        services::QueueItem,
+        services::RatingItem,
+        services::HistoryItem,
+        services::ScrobbleProvider,
+        services::ScrobbleLinkState,
+        services::ScrobbleDestinationName,
+        services::ScrobbleUnavailable,
+        api::LastFmAuthorizationResponse,
+        services::UncertainScrobble,
+        api::LinkScrobbleRequest,
+        api::RetriedScrobbleResponse,
+        services::BookmarkItem,
+        services::RadioStationItem,
+        services::UserItem,
+        api::CreatePlaylistRequest,
+        api::UpdatePlaylistRequest,
+        api::MovePlaylistEntryRequest,
+        api::RemovePlaylistEntryRequest,
+        api::RatingRequest,
+        api::ScrobbleRequest,
+        api::SaveQueueRequest,
+        api::CreateShareRequest,
+        api::UpdateShareRequest,
+        api::ShareResponse,
+        api::AuthorizeRequest,
+        api::AuthorizeResponse,
+        api::TokenRequest,
+        api::StarredEntry,
+        api::NowPlayingEntry,
+        api::SyncAckRequest,
+        api::SyncSnapshot,
+        services::LibraryEventPage,
+        services::DiskListing,
+        services::DiskFolder,
+        services::DiskTrack,
+        services::FiledFolder,
+        services::ImageChoices,
+        services::ImageChoice,
+        services::ArtistImageCandidate,
+        api::DeezerPortraitPick,
+        services::FiledTree,
+        services::AttentionCategory,
+        services::AttentionCount,
+        services::AttentionTrack,
+        services::CreditCandidate,
+        services::CreditFragment,
+        services::CreditDecisionKind,
+        services::CreditDecisionRecord,
+        services::QualitySummary,
+        services::QualityAnalysis,
+        services::AnalysisState,
+        services::QualityVerdict,
+        services::QualityVerdictCount,
+        services::QualityTrack,
+        services::TrackQuality,
+        services::TrackQualityDetail,
+        api::CreditDecisionRequest,
+        services::FolderPatch,
+        services::FolderRemoved,
+        services::Placed,
+        api::CreateFolderRequest,
+        api::PlacementRequest,
+        services::TrackMetadataPatch,
+        services::UploadOffer,
+        services::UploadVerdict,
+        services::UploadDecision,
+        services::UploadSessionState,
+        services::CommittedUpload,
+        api::NegotiateUploadsRequest,
+        api::NegotiateUploadsResponse,
+        services::LibraryEvent,
+        api::TranscodeStatusResponse,
+        api::CreateUserRequest,
+        api::UpdateUserRequest,
+        api::SetSubsonicCredentialRequest,
+        api::SubsonicCredentialResponse,
+        crate::database::SubsonicCredentialStatus,
+        api::BookmarkRequest,
+        api::RadioStationRequest,
+        api::CreateApiTokenRequest,
+        api::CreateApiTokenResponse,
+        database::ApiTokenRecord,
+        api::CreateLibraryRequest,
+        api::CreateLibraryResponse,
+        api::SetLibraryMemberRequest,
+        sync::SyncChange,
+        sync::SyncPage,
+        media::StreamTicketResponse,
+        media::CanvasResponse,
+        api::LibraryEventAckRequest
+    )),
+    modifiers(&SecurityAddon),
+    tags(
+        (name = "probes", description = "Process and SQLite health"),
+        (name = "authentication", description = "Local WaveFlow sessions")
+        ,(name = "catalog", description = "Authoritative library scans and catalogue reads")
+        ,(name = "user-data", description = "Cross-protocol playlists and playback state")
+        ,(name = "sync", description = "Durable WaveFlow Desktop user-data synchronization")
+        ,(name = "administration", description = "Administrative user and credential management")
+        ,(name = "scrobbling", description = "Per-account authorisations at external listening services, and the queue behind them")
+        ,(name = "radio", description = "Internet radio stations, one list per account")
+        ,(name = "smart-playlists", description = "Playlists defined by rules, evaluated when read (RFC-025)")
+        ,(name = "podcasts", description = "Podcast channels and episodes, one list per instance (RFC-025)")
+    )
+)]
+pub struct ApiDoc;
+
+/// Declares the bearer scheme and the two mutation headers.
+///
+/// Without this, a client generated from the document alone authenticates
+/// nowhere and never sends `X-WaveFlow-Operation-Id` — losing replay safety,
+/// which is the one thing the native API offers over the Subsonic facade.
+struct SecurityAddon;
+
+impl utoipa::Modify for SecurityAddon {
+    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
+        use utoipa::openapi::security::{Http, HttpAuthScheme, SecurityScheme};
+
+        let components = openapi.components.get_or_insert_with(Default::default);
+        components.add_security_scheme(
+            BEARER_SECURITY_SCHEME,
+            SecurityScheme::Http(
+                Http::builder()
+                    .scheme(HttpAuthScheme::Bearer)
+                    .description(Some(
+                        "Access token from /api/v2/auth/login, /api/v2/auth/refresh or the \
+                         PKCE exchange, or a long-lived `wfapi_` token minted by the CLI.",
+                    ))
+                    .build(),
+            ),
+        );
+        openapi.security = Some(vec![utoipa::openapi::security::SecurityRequirement::new(
+            BEARER_SECURITY_SCHEME,
+            Vec::<String>::new(),
+        )]);
+
+        clear_security_on_public_operations(openapi);
+        annotate_scope_refusals(openapi);
+        annotate_mutation_headers(openapi);
+    }
+}
+
+const BEARER_SECURITY_SCHEME: &str = "bearer";
+
+/// Operations that carry their own credential, or none at all. The global
+/// requirement above would otherwise claim a token is needed to log in.
+///
+/// The two `{ticket}` routes belong here on purpose: the sealed ticket in the
+/// path *is* the credential, because neither `<audio src>` nor `<video src>`
+/// can send a header. A document that omitted them would generate clients
+/// convinced a bearer is required, and they would send one that is not read.
+pub(super) const PUBLIC_OPERATIONS: &[(&str, &str)] = &[
+    ("/health", "get"),
+    ("/ready", "get"),
+    ("/api/v2/setup", "get"),
+    ("/api/v2/setup", "post"),
+    ("/api/v2/auth/login", "post"),
+    ("/api/v2/auth/refresh", "post"),
+    ("/api/v2/auth/logout", "post"),
+    ("/api/v2/web/auth/login", "post"),
+    ("/api/v2/web/auth/refresh", "post"),
+    ("/api/v2/web/auth/logout", "post"),
+    ("/api/v2/oauth/token", "post"),
+    ("/api/v2/stream/{ticket}", "get"),
+    ("/api/v2/canvas-stream/{ticket}", "get"),
+    // The Last.fm return, and the one entry here that is not a ticket. It is
+    // reached by a person's browser coming back from another site, with no
+    // `Authorization` header and — every cookie of this server being
+    // `SameSite=Strict` — no session cookie either. What stands in for proof is
+    // narrower than an `Access`: a single-use random, an expiry of a few
+    // minutes, and a cookie good for this path alone, all three of which must
+    // agree. Listed so the document says what the route does rather than
+    // advertising a requirement nothing checks.
+    ("/api/v2/scrobble-links/lastfm/callback/{state}", "get"),
+];
+
+fn clear_security_on_public_operations(openapi: &mut utoipa::openapi::OpenApi) {
+    for (path, method) in PUBLIC_OPERATIONS {
+        let Some(item) = openapi.paths.paths.get_mut(*path) else {
+            continue;
+        };
+        // Every method the list may name, not only the two it happens to name
+        // today. `annotate_scope_refusals` reads what this leaves behind, so a
+        // public `PUT` that fell through here would keep the global requirement
+        // and be handed a 403 it can never answer — the pass would be declaring
+        // a refusal on a route that has no credential to refuse.
+        let operation = match *method {
+            "get" => item.get.as_mut(),
+            "post" => item.post.as_mut(),
+            "put" => item.put.as_mut(),
+            "delete" => item.delete.as_mut(),
+            "patch" => item.patch.as_mut(),
+            _ => None,
+        };
+        if let Some(operation) = operation {
+            operation.security = Some(Vec::new());
+        }
+    }
+}
+
+/// Declares the refusal a narrowed credential meets, on every mutation that can
+/// meet it.
+///
+/// [`api::authenticated`] answers `Forbidden` — 403 — whenever a route asks for
+/// `Access::Write` or `Access::Admin` and the caller's scopes do not grant it.
+/// Every mutation asks for one of the two, so every secured mutation can answer
+/// 403; nineteen of them documented 401 and 422 and stopped there. A client
+/// generated from that document has no branch for the refusal and reads a
+/// perfectly ordinary answer as a transport failure.
+///
+/// Injected here rather than written onto each `#[utoipa::path]`, for the
+/// reason [`annotate_mutation_headers`] is: a property that holds of every
+/// route in a class is stated once, somewhere adding a route cannot forget it.
+/// The nineteen were not an oversight repeated nineteen times — they are what
+/// happens when the same true sentence has to be typed again per route.
+///
+/// Reads are excluded because a read normally cannot produce it: `Access::Read`
+/// is granted by every scope list. That is a statement about `Access::Read` and
+/// not about GET, and the two come apart — `GET /api/v2/uploads/{session_id}`
+/// asks for `Access::Write`, because reading a transfer's state belongs to the
+/// write flow. Such a route documents its own 403, and
+/// `every_refusal_a_narrow_token_meets_is_documented` is what notices when one
+/// does not: it asks the server rather than this list.
+fn annotate_scope_refusals(openapi: &mut utoipa::openapi::OpenApi) {
+    use utoipa::openapi::{ContentBuilder, Ref, RefOr, ResponseBuilder};
+
+    for item in openapi.paths.paths.values_mut() {
+        // GET excluded on purpose: see above.
+        let operations = [
+            item.put.as_mut(),
+            item.post.as_mut(),
+            item.delete.as_mut(),
+            item.patch.as_mut(),
+        ];
+        for operation in operations.into_iter().flatten() {
+            // Emptied by `clear_security_on_public_operations`, which must
+            // therefore have run before this: a route that carries no
+            // credential has none to have refused.
+            if operation.security.as_ref().is_some_and(Vec::is_empty) {
+                continue;
+            }
+            // `or_insert_with`, so a route that already describes its own 403
+            // — the administrative ones, and the library feed acknowledgement —
+            // keeps the wording it chose.
+            operation
+                .responses
+                .responses
+                .entry("403".to_owned())
+                .or_insert_with(|| {
+                    ResponseBuilder::new()
+                        .description(
+                            "Forbidden. `code` is `forbidden`: the credential authenticates, \
+                             but its scopes do not admit this operation. Retrying is futile \
+                             — the token has to be reissued with wider scopes.",
+                        )
+                        .content(
+                            "application/json",
+                            ContentBuilder::new()
+                                .schema(Some(RefOr::Ref(Ref::from_schema_name("ErrorResponse"))))
+                                .build(),
+                        )
+                        .build()
+                        .into()
+                });
+        }
+    }
+}
+
+/// Attaches the two optional mutation headers, and the 409 they can produce, to
+/// every user-data *write*. `mutation_context` accepts them on any such route,
+/// so they are declared per operation rather than described in prose nobody
+/// generates a client from.
+///
+/// Reads are skipped: a GET carries no operation id and cannot conflict.
+fn annotate_mutation_headers(openapi: &mut utoipa::openapi::OpenApi) {
+    use utoipa::openapi::path::{ParameterBuilder, ParameterIn};
+    use utoipa::openapi::{RefOr, Required, ResponseBuilder, Schema, Type};
+
+    // utoipa 6 holds a parameter list as `RefOr`, so a parameter built here
+    // is wrapped on the way in rather than pushed bare.
+    let header = |name: &str, description: &str| {
+        RefOr::T(
+            ParameterBuilder::new()
+                .name(name)
+                .parameter_in(ParameterIn::Header)
+                .required(Required::False)
+                .description(Some(description.to_owned()))
+                .schema(Some(Schema::Object({
+                    let mut object = utoipa::openapi::Object::new();
+                    object.schema_type = utoipa::openapi::schema::SchemaType::new(Type::String);
+                    object.format = Some(utoipa::openapi::SchemaFormat::Custom("uuid".to_owned()));
+                    object
+                })))
+                .build(),
+        )
+    };
+
+    for item in openapi.paths.paths.values_mut() {
+        // GET excluded on purpose: reads carry no operation id.
+        let operations = [
+            item.put.as_mut(),
+            item.post.as_mut(),
+            item.delete.as_mut(),
+            item.patch.as_mut(),
+        ];
+        for operation in operations.into_iter().flatten() {
+            if !operation
+                .tags
+                .as_ref()
+                .is_some_and(|tags| tags.iter().any(|tag| tag == "user-data"))
+            {
+                continue;
+            }
+            operation
+                .responses
+                .responses
+                .entry("409".to_owned())
+                .or_insert_with(|| {
+                    ResponseBuilder::new()
+                        .description(
+                            "Conflict. `code` is `conflict`: the operation id was already used \
+                         for a different payload. Retrying verbatim will fail again — mint \
+                         a new operation id.",
+                        )
+                        .build()
+                        .into()
+                });
+            let parameters = operation.parameters.get_or_insert_with(Vec::new);
+            parameters.push(header(
+                api::OPERATION_ID_HEADER,
+                "Stable id for this logical mutation. Repeating it replays the original \
+                 outcome instead of applying twice; reusing it for a different payload is \
+                 rejected as a conflict. Generated server-side when absent.",
+            ));
+            parameters.push(header(
+                api::DEVICE_ID_HEADER,
+                "Device originating the mutation. Rejected when it belongs to another \
+                 account. Lets other devices skip their own echo in the sync journal.",
+            ));
+        }
+    }
+}
+
+pub(super) async fn openapi_response(openapi: utoipa::openapi::OpenApi) -> Response {
+    match serde_json::to_string(&openapi) {
+        Ok(body) => (
+            [(axum::http::header::CONTENT_TYPE, "application/json")],
+            body,
+        )
+            .into_response(),
+        Err(error) => {
+            tracing::error!(error = %error, "OpenAPI serialization failed");
+            (
+                axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+                "OpenAPI serialization failed",
+            )
+                .into_response()
+        }
+    }
+}
diff --git a/src/app/router.rs b/src/app/router.rs
new file mode 100644
index 00000000..c6593b5e
--- /dev/null
+++ b/src/app/router.rs
@@ -0,0 +1,222 @@
+//! The router `main` serves and the tests drive: every surface merged under
+//! the layers they share, and the redaction applied to the paths it traces.
+
+use axum::{extract::DefaultBodyLimit, http::Request, Router};
+use tower::ServiceBuilder;
+use tower_http::{
+    cors::{AllowOrigin, CorsLayer},
+    request_id::{MakeRequestUuid, PropagateRequestIdLayer, SetRequestIdLayer},
+    trace::TraceLayer,
+};
+use utoipa::OpenApi;
+
+use super::openapi::{openapi_response, ApiDoc, OPENAPI_JSON_PATH};
+use super::state::AppState;
+use crate::{api, media, public_share, reference, subsonic, webui, Config};
+
+const REQUEST_ID_HEADER: &str = "x-request-id";
+
+pub fn app(config: &Config, state: AppState) -> Router {
+    let openapi = ApiDoc::openapi();
+    let openapi_for_route = openapi.clone();
+    let request_id_header = axum::http::HeaderName::from_static(REQUEST_ID_HEADER);
+    let middleware = ServiceBuilder::new()
+        // Before `SetRequestIdLayer`, which keeps whatever the caller sent and
+        // only forges an id when the header is absent. Dropping the inbound one
+        // unconditionally is what makes the layer below always mint, so the
+        // value in every `http_request` span is one this server chose.
+        //
+        // `CLAUDE.md` says no header reaches a trace sink, without exception,
+        // and an id narrow enough to look like an identifier is still a string
+        // a stranger picked: send a well-formed UUID that somebody else's
+        // requests are using and the trace record stops telling two callers
+        // apart. Validating the shape would have addressed the noise and left
+        // that.
+        //
+        // The correlation the header exists for is not lost, only reversed:
+        // `PropagateRequestIdLayer` returns the minted id on the response, so
+        // an upstream proxy records the name this server gave rather than
+        // imposing one. That is the ordinary arrangement wherever a server does
+        // not trust what is in front of it, and this one is routinely in front
+        // of nothing at all.
+        .map_request(|mut request: Request<_>| {
+            request.headers_mut().remove(REQUEST_ID_HEADER);
+            request
+        })
+        .layer(SetRequestIdLayer::new(
+            request_id_header.clone(),
+            MakeRequestUuid,
+        ))
+        // Query strings may contain Subsonic credentials and public-share
+        // paths contain bearer tokens. Neither may reach a trace sink.
+        .layer(
+            TraceLayer::new_for_http().make_span_with(|request: &Request<_>| {
+                let request_id = request
+                    .headers()
+                    .get(REQUEST_ID_HEADER)
+                    .and_then(|value| value.to_str().ok())
+                    .unwrap_or("");
+                let path = trace_path(request.uri().path());
+                tracing::info_span!(
+                    "http_request",
+                    method = %request.method(),
+                    path = path,
+                    request_id = %request_id
+                )
+            }),
+        )
+        .layer(PropagateRequestIdLayer::new(request_id_header));
+
+    let ordinary = Router::new()
+        .merge(api::router(state.clone()))
+        .route(
+            OPENAPI_JSON_PATH,
+            axum::routing::get(move || openapi_response(openapi_for_route.clone())),
+        )
+        .layer(tower_http::timeout::TimeoutLayer::with_status_code(
+            axum::http::StatusCode::REQUEST_TIMEOUT,
+            config.request_timeout,
+        ));
+
+    // What may be compressed, kept apart from what may not.
+    //
+    // The exclusion is **structural rather than conditional**: the media
+    // routes and the Subsonic facade are merged outside this group, so no
+    // predicate decides whether a stream is compressed — the layer never sees
+    // one. Compressing an already-compressed body spends CPU for nothing, and
+    // a body that arrives re-encoded is a body whose length and ranges no
+    // longer describe the file a player is seeking through.
+    //
+    // `CompressionLayer::new()` carries tower-http's `DefaultPredicate`, which
+    // leaves alone anything under 32 bytes, images, gRPC and — load-bearing
+    // here — `text/event-stream`: the scan event feed lives on `/api/v2` and
+    // would otherwise be buffered into silence by its own encoder.
+    //
+    // The Subsonic facade is out for a reason worth writing down, because it
+    // costs a real gain: it serves every method through one route,
+    // `/rest/{method}`, so a catalogue listing and an audio stream arrive by
+    // the same path. Separating them there would mean trusting a content-type
+    // predicate with the correctness of byte-range playback, which is the one
+    // thing in this server that four clients were replayed to establish.
+    let compressible = Router::new()
+        .merge(ordinary)
+        // A portrait search may take minutes; it keeps a timeout of its own.
+        .merge(api::search_router(state.clone()))
+        // Anything no API route claimed is served by the embedded web client:
+        // a built asset, or the shell for a client-side route. This is what
+        // the layer is mostly for — the built client leaves raw at roughly
+        // 497 kB and about 152 kB gzipped.
+        .fallback(webui::handler)
+        .layer(tower_http::compression::CompressionLayer::new());
+
+    let router = Router::new()
+        .merge(compressible)
+        // Media bodies can outlive the ordinary API timeout. FFmpeg and
+        // disconnected consumers are bounded by MediaService itself.
+        .merge(media::router(state.clone()))
+        .merge(public_share::router(state.clone(), config.request_timeout))
+        // The API reference and the script it loads, from the binary (RFC-023
+        // decision 3). Outside the compression layer: the script is stored
+        // compressed already.
+        .merge(reference::router(&openapi))
+        .merge(subsonic::router(state))
+        .layer(DefaultBodyLimit::max(16 * 1024));
+
+    // CORS goes on first so that the request-id and trace layers end up
+    // outside it. `CorsLayer` answers a preflight itself without calling the
+    // service under it, so anything applied inside it never runs for an
+    // `OPTIONS` — which would leave preflights unnamed, against what the API
+    // guide promises, and invisible in the traces. An origin rejected by
+    // `WAVEFLOW_ALLOWED_ORIGINS` is exactly the thing an operator has to
+    // diagnose, and it was the one request that left no record.
+    let cors = if config.allowed_origins.is_empty() {
+        router
+    } else {
+        router.layer(
+            CorsLayer::new()
+                .allow_origin(AllowOrigin::list(config.allowed_origins.clone()))
+                .allow_methods([
+                    axum::http::Method::GET,
+                    axum::http::Method::POST,
+                    axum::http::Method::PUT,
+                    axum::http::Method::PATCH,
+                    axum::http::Method::DELETE,
+                    axum::http::Method::OPTIONS,
+                ])
+                .allow_headers([
+                    axum::http::header::AUTHORIZATION,
+                    axum::http::header::CONTENT_TYPE,
+                    axum::http::header::RANGE,
+                    axum::http::HeaderName::from_static(api::WEB_CSRF_HEADER),
+                    axum::http::HeaderName::from_static(api::OPERATION_ID_HEADER),
+                    axum::http::HeaderName::from_static(api::DEVICE_ID_HEADER),
+                ])
+                // `x-request-id` is exposed and deliberately not allowed: a
+                // browser client should be able to read the name this server
+                // gave its request, which is what makes it quotable in a bug
+                // report, but it has no business sending one — an inbound value
+                // is dropped before anything reads it.
+                .expose_headers([
+                    axum::http::header::ACCEPT_RANGES,
+                    axum::http::header::CONTENT_LENGTH,
+                    axum::http::header::CONTENT_RANGE,
+                    axum::http::HeaderName::from_static(REQUEST_ID_HEADER),
+                ]),
+        )
+    };
+
+    cors.layer(middleware)
+}
+
+/// Every prefix whose next path segment is a credential, and what a trace sink
+/// sees instead.
+///
+/// **A table rather than a chain of `if`s, because the chain lost one.** This
+/// function knew the audio ticket and the share token; the server has a third
+/// such route, `/api/v2/canvas-stream/{ticket}`, minted beside the audio one in
+/// `media.rs`, played by a `<video src>` that cannot send an `Authorization`
+/// header, and listed beside its twin in `PUBLIC_OPERATIONS` two hundred lines
+/// above. It was never added here, so the sealed ticket went into the
+/// `http_request` span verbatim.
+///
+/// **What that actually cost, stated exactly.** The span is opened at INFO, but
+/// nothing here asks for span lifecycle events, so opening one writes nothing on
+/// its own: a canvas playback that succeeds quietly emitted no line. The ticket
+/// reached a sink on every canvas request that logged anything *inside* that
+/// span — a failed ticket lookup, a 5xx — and on every request at all under
+/// `tower_http=debug`, where the tower layer's own request and response events
+/// fire in it. An earlier version of this paragraph said "every canvas
+/// playback", which is one notch stronger than the mechanism.
+///
+/// The shape is the fix. A new ticket route now has one obvious place to be
+/// declared, next to the ones that look exactly like it, rather than a branch
+/// somebody has to remember to add.
+///
+/// Matched on the raw path, so `/API/v2/stream/…` and a percent-encoded
+/// separator miss every entry. Left that way deliberately: reaching those
+/// spellings means already holding the ticket, so it is hardening rather than a
+/// disclosure route, and normalising here would put a second opinion about what
+/// a path means next to the router's.
+pub(super) const CREDENTIAL_BEARING_PREFIXES: [(&str, &str); 4] = [
+    ("/api/v2/stream/", "/api/v2/stream/{redacted}"),
+    ("/api/v2/canvas-stream/", "/api/v2/canvas-stream/{redacted}"),
+    ("/share/", "/share/{redacted}"),
+    // The Last.fm return. Its `{state}` is a single-use random worth a
+    // profile for a quarter of an hour, and the `token` Last.fm appends is
+    // worth one for an hour — that one sits in the query string, which no
+    // trace of this server keeps. The rule in `CLAUDE.md` has no exception for
+    // a secret that only lasts an hour.
+    (
+        crate::services::LASTFM_CALLBACK_PREFIX,
+        "/api/v2/scrobble-links/lastfm/callback/{redacted}",
+    ),
+];
+
+pub(super) fn trace_path(path: &str) -> &str {
+    for (prefix, redacted) in CREDENTIAL_BEARING_PREFIXES {
+        if path.starts_with(prefix) {
+            return redacted;
+        }
+    }
+    path
+}
diff --git a/src/app/state.rs b/src/app/state.rs
new file mode 100644
index 00000000..a0e8e91d
--- /dev/null
+++ b/src/app/state.rs
@@ -0,0 +1,70 @@
+//! `AppState`, the singletons every surface shares, and the body ceilings it
+//! derives from the upload limits.
+
+use std::sync::Arc;
+
+use crate::{
+    authentication, config, database, media, scanner, security, services, setup_token, sync,
+};
+
+#[derive(Clone)]
+pub struct AppState {
+    pub db: database::Database,
+    pub auth: authentication::AuthService,
+    pub secret_box: Arc<security::SecretBox>,
+    pub scanner: scanner::ScanManager,
+    pub media: media::MediaService,
+    pub services: services::DomainServices,
+    pub sync: sync::SyncService,
+    pub artwork_dir: std::path::PathBuf,
+    pub instance_key_path: std::path::PathBuf,
+    pub public_url: Option<String>,
+    pub stream_ticket_ttl: std::time::Duration,
+    pub refresh_token_ttl: std::time::Duration,
+    /// The body ceiling the upload negotiation route carries, derived from how
+    /// many offers a batch may hold.
+    ///
+    /// The router's global limit is sixteen kilobytes and stays there: an API
+    /// whose every route accepts that much cannot be drowned in a request body,
+    /// and that property is worth more than the convenience of raising it once.
+    /// A batch of two hundred offers does not fit in it, so the route that
+    /// needs the room asks for it alone.
+    pub upload_batch_body_limit: usize,
+    /// The body ceiling one fragment may occupy.
+    ///
+    /// A little above the advertised fragment size, for the framing rather than
+    /// for slack: a client that sends more than it was told to is refused by
+    /// the route before the service has to read it.
+    pub upload_chunk_body_limit: usize,
+    /// The body ceiling the canvas route carries, derived from
+    /// `WAVEFLOW_CANVAS_MAX_BYTES` so the two cannot disagree.
+    pub canvas_body_limit: usize,
+    /// `WAVEFLOW_TRUSTED_PROXIES`: whose `X-Forwarded-For` names the client a
+    /// sign-in is counted under (RFC-017 decision 2).
+    pub trusted_proxies: Arc<[ipnet::IpNet]>,
+    /// The one-time token first-run setup asks for while no account exists
+    /// (RFC-019 decision 1).
+    pub setup: Arc<setup_token::SetupGate>,
+}
+
+/// Roughly one offer's worth of JSON — a sixty-four character hash, a size, a
+/// short extension and their punctuation — times the batch, with a fixed
+/// allowance for the envelope. Derived rather than configured, so a raised
+/// batch limit cannot quietly start rejecting the batches it just permitted.
+pub(super) fn negotiation_body_limit(limits: &config::UploadLimits) -> usize {
+    limits.batch_limit.saturating_mul(160).saturating_add(1024)
+}
+
+/// One fragment, plus room for its framing.
+///
+/// `Config` refuses a fragment size this platform cannot represent, so the
+/// fallback below is unreachable. It is a small finite number rather than
+/// `usize::MAX` anyway: a ceiling that falls back to "no ceiling" is the one
+/// mistake this value must never make, and an unreachable branch is exactly
+/// where that would go unnoticed.
+pub(super) fn chunk_body_limit(limits: &config::UploadLimits) -> usize {
+    const FALLBACK: usize = 16 * 1024 * 1024;
+    usize::try_from(limits.chunk_bytes)
+        .unwrap_or(FALLBACK)
+        .saturating_add(4096)
+}
diff --git a/src/app/tests.rs b/src/app/tests.rs
new file mode 100644
index 00000000..5f9cb495
--- /dev/null
+++ b/src/app/tests.rs
@@ -0,0 +1,256 @@
+use super::router::trace_path;
+
+/// The scrobbling routes carry no operation-id protocol, and must not
+/// advertise one.
+///
+/// `annotate_mutation_headers` injects a `409` and the two mutation headers
+/// into every `user-data` write, because every one of those goes through
+/// `mutation_context`. These do not — RFC-010 decision 12 keeps this state
+/// out of synchronisation entirely — so they carry their own tag.
+///
+/// Written because removing a hand-written `409` from the retry route did
+/// not remove the `409`: it vacated the entry that the injected one then
+/// filled, with no response schema and a description about operation ids
+/// that was false for it. The document was worse than before the fix, and
+/// nothing said so.
+#[test]
+fn the_scrobbling_routes_advertise_no_operation_id_protocol() {
+    use utoipa::openapi::RefOr;
+    use utoipa::OpenApi;
+
+    let openapi = super::ApiDoc::openapi();
+    let mut checked = 0;
+    for (path, item) in &openapi.paths.paths {
+        if !path.starts_with("/api/v2/scrobble-") {
+            continue;
+        }
+        for operation in [
+            item.put.as_ref(),
+            item.post.as_ref(),
+            item.delete.as_ref(),
+            item.patch.as_ref(),
+        ]
+        .into_iter()
+        .flatten()
+        {
+            checked += 1;
+            assert!(
+                !operation.responses.responses.contains_key("409"),
+                "{path} advertises a conflict it cannot produce"
+            );
+            let names: Vec<&str> = operation
+                .parameters
+                .iter()
+                .flatten()
+                .map(|parameter| match parameter {
+                    RefOr::T(parameter) => parameter.name.as_str(),
+                    RefOr::Ref(reference) => panic!(
+                        "{path} advertises a parameter by reference ({}), which this check cannot read",
+                        reference.ref_location
+                    ),
+                })
+                .collect();
+            assert!(
+                !names.contains(&crate::api::OPERATION_ID_HEADER),
+                "{path} advertises an operation id it never reads"
+            );
+            assert!(
+                !names.contains(&crate::api::DEVICE_ID_HEADER),
+                "{path} advertises a device id it never reads"
+            );
+        }
+    }
+    assert_eq!(
+        checked, 5,
+        "two on the link, two on the queue, and the Last.fm authorisation — a count that \
+         falls if a route is added without deciding which protocol it belongs to"
+    );
+}
+
+/// Every `user-data` mutation advertises both headers and a `409`.
+///
+/// Written because nothing asserted the presence of what
+/// `annotate_mutation_headers` injects — only its absence on the
+/// scrobbling routes. An annotation that stopped injecting would have made
+/// that neighbouring test pass more easily, and the document would have
+/// lost the operation-id protocol with a green suite.
+///
+/// `user-data` is the tag the annotation selects on, so this walk asks the
+/// same question the pass answers rather than a wider one it never claimed.
+#[test]
+fn every_user_data_mutation_advertises_the_operation_id_protocol() {
+    use utoipa::openapi::RefOr;
+    use utoipa::OpenApi;
+
+    // Sixteen today: the favourite, rating, play-queue and now-playing
+    // mutations, the playlist import — which claims an operation like
+    // every other playlist creation, because that is the verb it calls —
+    // and the move and the removal of one playlist entry, which journal as
+    // an update does. A new one lands here deliberately, not silently.
+    let expected = 16;
+    let openapi = super::ApiDoc::openapi();
+    let mut checked = 0;
+    for (path, item) in &openapi.paths.paths {
+        for operation in [
+            item.put.as_ref(),
+            item.post.as_ref(),
+            item.delete.as_ref(),
+            item.patch.as_ref(),
+        ]
+        .into_iter()
+        .flatten()
+        {
+            if !operation
+                .tags
+                .as_ref()
+                .is_some_and(|tags| tags.iter().any(|tag| tag == "user-data"))
+            {
+                continue;
+            }
+            assert!(
+                operation.responses.responses.contains_key("409"),
+                "{path} takes an operation id without documenting the conflict it can answer"
+            );
+            let names: Vec<&str> = operation
+                .parameters
+                .iter()
+                .flatten()
+                .map(|parameter| match parameter {
+                    RefOr::T(parameter) => parameter.name.as_str(),
+                    RefOr::Ref(reference) => panic!(
+                        "{path} advertises a parameter by reference ({}), which this check cannot read",
+                        reference.ref_location
+                    ),
+                })
+                .collect();
+            assert!(
+                names.contains(&crate::api::OPERATION_ID_HEADER),
+                "{path} mutates without advertising an operation id"
+            );
+            assert!(
+                names.contains(&crate::api::DEVICE_ID_HEADER),
+                "{path} mutates without advertising a device id"
+            );
+            checked += 1;
+        }
+    }
+    assert_eq!(
+        checked, expected,
+        "{checked} tagged mutations examined, not {expected} — a walk that stops finding \
+         them makes every assertion above vacuous, so the count is pinned rather than \
+         merely non-zero"
+    );
+}
+
+/// Every entry in `PUBLIC_OPERATIONS` names an operation that exists, and
+/// leaves it carrying no security requirement.
+///
+/// The list is looked up by two strings, so a path that is renamed or a
+/// method spelled `PUT` instead of `put` matches nothing, clears nothing,
+/// and goes on looking correct. That was cheap while the result was only a
+/// missing security block. `annotate_scope_refusals` reads what this pass
+/// leaves behind, so a public operation that keeps the global requirement
+/// is now handed a 403 it can never answer — a refusal documented on a
+/// route that holds no credential to refuse.
+#[test]
+fn every_public_operation_is_found_and_cleared() {
+    use utoipa::OpenApi;
+
+    let openapi = super::ApiDoc::openapi();
+    for (path, method) in super::openapi::PUBLIC_OPERATIONS {
+        let item = openapi
+            .paths
+            .paths
+            .get(*path)
+            .unwrap_or_else(|| panic!("{path} is named here but is not a documented path"));
+        let operation = match *method {
+            "get" => item.get.as_ref(),
+            "post" => item.post.as_ref(),
+            "put" => item.put.as_ref(),
+            "delete" => item.delete.as_ref(),
+            "patch" => item.patch.as_ref(),
+            other => panic!("{other} is not a method this list may name"),
+        }
+        .unwrap_or_else(|| panic!("{method} {path} is not a documented operation"));
+        assert!(
+            operation.security.as_ref().is_some_and(Vec::is_empty),
+            "{method} {path} is public and must carry no security requirement"
+        );
+    }
+}
+
+/// Every entry in the table redacts, and no entry can shadow another.
+///
+/// A property over the table rather than one `assert_eq!` per entry,
+/// because a hand-written assertion per entry has exactly the weakness the
+/// table was written to fix: it cannot notice the entry nobody wrote. This
+/// form also catches the edit that would quietly undo the whole thing — a
+/// broad prefix inserted above a narrow one, which first-match-wins would
+/// silently relabel.
+#[test]
+fn every_credential_bearing_prefix_is_redacted() {
+    for (prefix, redacted) in super::router::CREDENTIAL_BEARING_PREFIXES {
+        assert_eq!(
+            redacted,
+            format!("{prefix}{{redacted}}"),
+            "{prefix} must replace its next segment and nothing else"
+        );
+        assert_eq!(
+            trace_path(&format!("{prefix}a-sealed-secret")),
+            redacted,
+            "{prefix} must not reach a trace sink carrying its credential"
+        );
+        // A share token is followed by more path, and the whole tail goes.
+        assert_eq!(
+            trace_path(&format!("{prefix}a-sealed-secret/tracks/id/stream")),
+            redacted
+        );
+    }
+
+    for (outer, _) in super::router::CREDENTIAL_BEARING_PREFIXES {
+        for (inner, _) in super::router::CREDENTIAL_BEARING_PREFIXES {
+            assert!(
+                outer == inner || !inner.starts_with(outer),
+                "{outer} shadows {inner}: first match wins, so {inner} would never be reached"
+            );
+        }
+    }
+
+    // And a path that carries nothing is left exactly as it is.
+    assert_eq!(trace_path("/rest/ping.view"), "/rest/ping.view");
+}
+
+/// Every public route whose path ends in a ticket has a redaction prefix.
+///
+/// **This is the assertion that would have caught the canvas ticket**, and
+/// the test above would not have. A table is self-consistent on its own: an
+/// entry with a typo in its prefix redacts its own typo and satisfies every
+/// property there, while the real route goes on being logged. What no
+/// property over the table alone can do is notice a route nobody added to
+/// it.
+///
+/// `PUBLIC_OPERATIONS` had `/api/v2/canvas-stream/{ticket}` listed
+/// correctly, two hundred lines from a redaction list that did not. The two
+/// are tied together here so that distance stops mattering.
+#[test]
+fn every_public_ticket_route_has_a_redaction_prefix() {
+    for (path, _) in super::openapi::PUBLIC_OPERATIONS {
+        // `{state}` as well as `{ticket}`: the Last.fm return is the first
+        // public route whose path carries a credential under another name,
+        // and a check that knew only one spelling would have let it through
+        // — which is the shape of the canvas ticket this test was written
+        // for.
+        let Some(prefix) = path
+            .strip_suffix("{ticket}")
+            .or_else(|| path.strip_suffix("{state}"))
+        else {
+            continue;
+        };
+        assert!(
+            super::router::CREDENTIAL_BEARING_PREFIXES
+                .iter()
+                .any(|(candidate, _)| *candidate == prefix),
+            "{path} carries a credential in its path and nothing redacts it"
+        );
+    }
+}
diff --git a/src/lib.rs b/src/lib.rs
index 83ee2cda..71928351 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,6 +1,7 @@
 //! WaveFlow Server v2 library surface.
 
 pub mod api;
+mod app;
 pub mod authentication;
 pub mod catalog;
 pub mod cli;
@@ -38,1389 +39,5 @@ pub mod tags;
 pub mod watcher;
 pub mod webui;
 
-use std::{sync::Arc, time::Duration};
-
-use axum::{
-    extract::DefaultBodyLimit,
-    http::Request,
-    response::{IntoResponse, Response},
-    Router,
-};
-use tower::ServiceBuilder;
-use tower_http::{
-    cors::{AllowOrigin, CorsLayer},
-    request_id::{MakeRequestUuid, PropagateRequestIdLayer, SetRequestIdLayer},
-    trace::TraceLayer,
-};
-use utoipa::OpenApi;
-
+pub use app::{app, initialize, shutdown_signal, ApiDoc, AppState, OPENAPI_JSON_PATH, SCALAR_PATH};
 pub use config::Config;
-
-pub const OPENAPI_JSON_PATH: &str = "/openapi.json";
-pub const SCALAR_PATH: &str = "/reference";
-const REQUEST_ID_HEADER: &str = "x-request-id";
-
-#[derive(Clone)]
-pub struct AppState {
-    pub db: database::Database,
-    pub auth: authentication::AuthService,
-    pub secret_box: Arc<security::SecretBox>,
-    pub scanner: scanner::ScanManager,
-    pub media: media::MediaService,
-    pub services: services::DomainServices,
-    pub sync: sync::SyncService,
-    pub artwork_dir: std::path::PathBuf,
-    pub instance_key_path: std::path::PathBuf,
-    pub public_url: Option<String>,
-    pub stream_ticket_ttl: std::time::Duration,
-    pub refresh_token_ttl: std::time::Duration,
-    /// The body ceiling the upload negotiation route carries, derived from how
-    /// many offers a batch may hold.
-    ///
-    /// The router's global limit is sixteen kilobytes and stays there: an API
-    /// whose every route accepts that much cannot be drowned in a request body,
-    /// and that property is worth more than the convenience of raising it once.
-    /// A batch of two hundred offers does not fit in it, so the route that
-    /// needs the room asks for it alone.
-    pub upload_batch_body_limit: usize,
-    /// The body ceiling one fragment may occupy.
-    ///
-    /// A little above the advertised fragment size, for the framing rather than
-    /// for slack: a client that sends more than it was told to is refused by
-    /// the route before the service has to read it.
-    pub upload_chunk_body_limit: usize,
-    /// The body ceiling the canvas route carries, derived from
-    /// `WAVEFLOW_CANVAS_MAX_BYTES` so the two cannot disagree.
-    pub canvas_body_limit: usize,
-    /// `WAVEFLOW_TRUSTED_PROXIES`: whose `X-Forwarded-For` names the client a
-    /// sign-in is counted under (RFC-017 decision 2).
-    pub trusted_proxies: Arc<[ipnet::IpNet]>,
-    /// The one-time token first-run setup asks for while no account exists
-    /// (RFC-019 decision 1).
-    pub setup: Arc<setup_token::SetupGate>,
-}
-
-/// Roughly one offer's worth of JSON — a sixty-four character hash, a size, a
-/// short extension and their punctuation — times the batch, with a fixed
-/// allowance for the envelope. Derived rather than configured, so a raised
-/// batch limit cannot quietly start rejecting the batches it just permitted.
-fn negotiation_body_limit(limits: &config::UploadLimits) -> usize {
-    limits.batch_limit.saturating_mul(160).saturating_add(1024)
-}
-
-/// One fragment, plus room for its framing.
-///
-/// `Config` refuses a fragment size this platform cannot represent, so the
-/// fallback below is unreachable. It is a small finite number rather than
-/// `usize::MAX` anyway: a ceiling that falls back to "no ceiling" is the one
-/// mistake this value must never make, and an unreachable branch is exactly
-/// where that would go unnoticed.
-fn chunk_body_limit(limits: &config::UploadLimits) -> usize {
-    const FALLBACK: usize = 16 * 1024 * 1024;
-    usize::try_from(limits.chunk_bytes)
-        .unwrap_or(FALLBACK)
-        .saturating_add(4096)
-}
-
-#[derive(OpenApi)]
-#[openapi(
-    info(
-        title = "WaveFlow Server API",
-        version = env!("CARGO_PKG_VERSION"),
-        description = "Self-hosted WaveFlow music server v2.",
-        license(name = "AGPL-3.0-only")
-    ),
-    paths(
-        api::health,
-        api::ready,
-        api::setup_status,
-        api::setup,
-        api::login,
-        api::refresh,
-        api::logout,
-        api::web_login,
-        api::web_refresh,
-        api::web_logout,
-        api::oauth_authorize,
-        api::oauth_token,
-        api::start_scan,
-        api::list_libraries,
-        api::create_library,
-        api::update_library,
-        api::delete_library,
-        api::library_settings,
-        api::unavailable_tracks,
-        api::purge_unavailable_tracks,
-        api::purged_tracks,
-        api::restore_purged_tracks,
-        api::list_library_members,
-        api::set_library_member,
-        api::remove_library_member,
-        api::scan_status,
-        api::scan_events,
-        api::library_events,
-        api::library_events_ack,
-        api::negotiate_uploads,
-        api::upload_session,
-        api::upload_chunk,
-        api::commit_upload,
-        api::list_tracks,
-        api::library_tree,
-        api::list_folders,
-        api::create_folder,
-        api::update_folder,
-        api::delete_folder,
-        api::folder_tracks,
-        api::place_tracks,
-        api::attention_summary,
-        api::attention_credits,
-        api::attention_tracks,
-        api::list_credit_decisions,
-        api::create_credit_decision,
-        api::delete_credit_decision,
-        api::quality_summary,
-        api::quality_tracks,
-        api::request_quality_analysis,
-        api::track_quality,
-        api::track_spectrogram,
-        api::get_track,
-        api::update_track,
-        api::get_track_lyrics,
-        api::put_track_lyrics,
-        api::delete_track_lyrics,
-        api::get_track_lyrics_file,
-        api::get_track_overrides,
-        api::list_albums,
-        api::list_genres,
-        api::get_album,
-        api::list_artists,
-        api::get_artist,
-        api::put_artist_image,
-        api::delete_artist_image,
-        api::list_artist_image_candidates,
-        api::put_artist_deezer_portrait,
-        api::list_artist_top_songs,
-        api::list_artist_albums,
-        api::search_catalog,
-        api::list_songs,
-        api::list_random_songs,
-        api::get_listening_stats,
-        api::list_mixes,
-        api::get_mix,
-        api::list_similar_songs,
-        api::list_songs_by_genre,
-        api::list_playlists,
-        api::create_playlist,
-        api::import_playlist,
-        api::export_playlist,
-        api::get_playlist,
-        api::update_playlist,
-        api::move_playlist_entry,
-        api::remove_playlist_entry,
-        api::delete_playlist,
-        api::list_smart_playlists,
-        api::create_smart_playlist,
-        api::preview_smart_playlist,
-        api::get_smart_playlist,
-        api::update_smart_playlist,
-        api::delete_smart_playlist,
-        api::podcast_overview,
-        api::create_podcast_channel,
-        api::refresh_podcasts,
-        api::get_podcast_channel,
-        api::delete_podcast_channel,
-        api::newest_podcast_episodes,
-        api::get_podcast_episode,
-        api::download_podcast_episode,
-        api::delete_podcast_episode,
-        api::list_favorites,
-        api::add_favorite,
-        api::remove_favorite,
-        api::set_rating,
-        api::list_ratings,
-        api::create_scrobble,
-        api::list_history,
-        api::list_now_playing,
-        api::list_scrobble_links,
-        api::list_scrobble_destinations,
-        api::link_scrobble,
-        api::unlink_scrobble,
-        api::authorize_lastfm,
-        api::lastfm_callback,
-        api::list_uncertain_scrobbles,
-        api::discard_uncertain_scrobble,
-        api::retry_uncertain_scrobble,
-        api::get_queue,
-        api::save_queue,
-        api::list_shares,
-        api::create_share,
-        api::update_share,
-        api::delete_share,
-        api::sync_changes,
-        api::sync_snapshot,
-        api::sync_ack,
-        api::sync_socket,
-        api::transcode_status,
-        api::list_users,
-        api::create_user,
-        api::update_user,
-        api::delete_user,
-        api::set_subsonic_credential,
-        api::revoke_subsonic_credential,
-        api::list_radio_stations,
-        api::get_radio_station,
-        api::create_radio_station,
-        api::replace_radio_station,
-        api::delete_radio_station,
-        api::list_bookmarks,
-        api::set_bookmark,
-        api::delete_bookmark,
-        api::list_own_api_tokens,
-        api::create_own_api_token,
-        api::revoke_own_api_token,
-        api::own_subsonic_credential,
-        api::rotate_own_subsonic_credential,
-        api::revoke_own_subsonic_credential,
-        api::list_api_tokens,
-        api::create_api_token,
-        api::revoke_api_token,
-        media::stream_track,
-        media::create_stream_ticket,
-        media::stream_with_ticket,
-        media::artwork,
-        media::canvas_by_hash,
-        media::canvas_for_track,
-        media::put_canvas,
-        media::delete_canvas,
-        media::create_canvas_ticket,
-        media::canvas_with_ticket
-    ),
-    components(schemas(
-        api::ProbeResponse,
-        api::ReadyResponse,
-        api::SetupStatusResponse,
-        api::SetupRequest,
-        api::SetupResponse,
-        api::LoginRequest,
-        api::RefreshRequest,
-        api::WebAuthResponse,
-        api::ErrorResponse,
-        authentication::AuthTokens,
-        authentication::AuthUser,
-        database::AccountRole,
-        api::ScanQueuedResponse,
-        catalog::ScanJobRecord,
-        catalog::TrackRecord,
-        catalog::LibraryAccess,
-        api::DeleteLibraryRequest,
-        services::LibraryUpdate,
-        services::LibraryUpdated,
-        services::LibrarySettings,
-        services::LibraryDeleted,
-        services::UnavailableTrack,
-        services::UnavailableTracks,
-        services::PurgeRequest,
-        services::PurgeOutcome,
-        services::RestoreOutcome,
-        services::AlbumItem,
-        services::ReleaseGroup,
-        services::ArtistItem,
-        services::GenreItem,
-        services::LibraryMember,
-        services::SongItem,
-        services::TrackDetail,
-        services::TrackOverrides,
-        services::TrackOverrideValues,
-        services::TrackSourceTags,
-        lyrics::LyricsList,
-        lyrics::StructuredLyrics,
-        lyrics::LyricsLine,
-        services::ArtistSummary,
-        services::AlbumDetail,
-        services::ArtistDetail,
-        services::ArtistEnrichment,
-        services::EnrichmentState,
-        services::EnrichmentSource,
-        services::EnrichedBio,
-        services::EnrichedImage,
-        services::EnrichedSimilar,
-        services::ListeningStats,
-        services::StatsBucketSize,
-        services::StatsTotals,
-        services::StatsBucket,
-        services::TopTrack,
-        services::TopAlbum,
-        services::TopArtist,
-        services::TopGenre,
-        services::PlayMoment,
-        services::MixSummary,
-        services::Mix,
-        services::SearchResult,
-        services::PlaylistItem,
-        services::SmartPlaylistItem,
-        services::SmartPlaylistPreview,
-        services::SmartRules,
-        services::SmartCondition,
-        services::SmartMatch,
-        services::SmartField,
-        services::SmartOperator,
-        services::SmartSort,
-        services::SmartOrder,
-        api::SmartPlaylistRequest,
-        api::SmartPlaylistPatch,
-        api::SmartPreviewRequest,
-        api::RuleErrorResponse,
-        services::PodcastOverview,
-        services::PodcastChannelItem,
-        services::PodcastEpisodeItem,
-        api::CreatePodcastChannelRequest,
-        api::FeedErrorResponse,
-        services::QueueItem,
-        services::RatingItem,
-        services::HistoryItem,
-        services::ScrobbleProvider,
-        services::ScrobbleLinkState,
-        services::ScrobbleDestinationName,
-        services::ScrobbleUnavailable,
-        api::LastFmAuthorizationResponse,
-        services::UncertainScrobble,
-        api::LinkScrobbleRequest,
-        api::RetriedScrobbleResponse,
-        services::BookmarkItem,
-        services::RadioStationItem,
-        services::UserItem,
-        api::CreatePlaylistRequest,
-        api::UpdatePlaylistRequest,
-        api::MovePlaylistEntryRequest,
-        api::RemovePlaylistEntryRequest,
-        api::RatingRequest,
-        api::ScrobbleRequest,
-        api::SaveQueueRequest,
-        api::CreateShareRequest,
-        api::UpdateShareRequest,
-        api::ShareResponse,
-        api::AuthorizeRequest,
-        api::AuthorizeResponse,
-        api::TokenRequest,
-        api::StarredEntry,
-        api::NowPlayingEntry,
-        api::SyncAckRequest,
-        api::SyncSnapshot,
-        services::LibraryEventPage,
-        services::DiskListing,
-        services::DiskFolder,
-        services::DiskTrack,
-        services::FiledFolder,
-        services::ImageChoices,
-        services::ImageChoice,
-        services::ArtistImageCandidate,
-        api::DeezerPortraitPick,
-        services::FiledTree,
-        services::AttentionCategory,
-        services::AttentionCount,
-        services::AttentionTrack,
-        services::CreditCandidate,
-        services::CreditFragment,
-        services::CreditDecisionKind,
-        services::CreditDecisionRecord,
-        services::QualitySummary,
-        services::QualityAnalysis,
-        services::AnalysisState,
-        services::QualityVerdict,
-        services::QualityVerdictCount,
-        services::QualityTrack,
-        services::TrackQuality,
-        services::TrackQualityDetail,
-        api::CreditDecisionRequest,
-        services::FolderPatch,
-        services::FolderRemoved,
-        services::Placed,
-        api::CreateFolderRequest,
-        api::PlacementRequest,
-        services::TrackMetadataPatch,
-        services::UploadOffer,
-        services::UploadVerdict,
-        services::UploadDecision,
-        services::UploadSessionState,
-        services::CommittedUpload,
-        api::NegotiateUploadsRequest,
-        api::NegotiateUploadsResponse,
-        services::LibraryEvent,
-        api::TranscodeStatusResponse,
-        api::CreateUserRequest,
-        api::UpdateUserRequest,
-        api::SetSubsonicCredentialRequest,
-        api::SubsonicCredentialResponse,
-        crate::database::SubsonicCredentialStatus,
-        api::BookmarkRequest,
-        api::RadioStationRequest,
-        api::CreateApiTokenRequest,
-        api::CreateApiTokenResponse,
-        database::ApiTokenRecord,
-        api::CreateLibraryRequest,
-        api::CreateLibraryResponse,
-        api::SetLibraryMemberRequest,
-        sync::SyncChange,
-        sync::SyncPage,
-        media::StreamTicketResponse,
-        media::CanvasResponse,
-        api::LibraryEventAckRequest
-    )),
-    modifiers(&SecurityAddon),
-    tags(
-        (name = "probes", description = "Process and SQLite health"),
-        (name = "authentication", description = "Local WaveFlow sessions")
-        ,(name = "catalog", description = "Authoritative library scans and catalogue reads")
-        ,(name = "user-data", description = "Cross-protocol playlists and playback state")
-        ,(name = "sync", description = "Durable WaveFlow Desktop user-data synchronization")
-        ,(name = "administration", description = "Administrative user and credential management")
-        ,(name = "scrobbling", description = "Per-account authorisations at external listening services, and the queue behind them")
-        ,(name = "radio", description = "Internet radio stations, one list per account")
-        ,(name = "smart-playlists", description = "Playlists defined by rules, evaluated when read (RFC-025)")
-        ,(name = "podcasts", description = "Podcast channels and episodes, one list per instance (RFC-025)")
-    )
-)]
-pub struct ApiDoc;
-
-/// Declares the bearer scheme and the two mutation headers.
-///
-/// Without this, a client generated from the document alone authenticates
-/// nowhere and never sends `X-WaveFlow-Operation-Id` — losing replay safety,
-/// which is the one thing the native API offers over the Subsonic facade.
-struct SecurityAddon;
-
-impl utoipa::Modify for SecurityAddon {
-    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
-        use utoipa::openapi::security::{Http, HttpAuthScheme, SecurityScheme};
-
-        let components = openapi.components.get_or_insert_with(Default::default);
-        components.add_security_scheme(
-            BEARER_SECURITY_SCHEME,
-            SecurityScheme::Http(
-                Http::builder()
-                    .scheme(HttpAuthScheme::Bearer)
-                    .description(Some(
-                        "Access token from /api/v2/auth/login, /api/v2/auth/refresh or the \
-                         PKCE exchange, or a long-lived `wfapi_` token minted by the CLI.",
-                    ))
-                    .build(),
-            ),
-        );
-        openapi.security = Some(vec![utoipa::openapi::security::SecurityRequirement::new(
-            BEARER_SECURITY_SCHEME,
-            Vec::<String>::new(),
-        )]);
-
-        clear_security_on_public_operations(openapi);
-        annotate_scope_refusals(openapi);
-        annotate_mutation_headers(openapi);
-    }
-}
-
-const BEARER_SECURITY_SCHEME: &str = "bearer";
-
-/// Operations that carry their own credential, or none at all. The global
-/// requirement above would otherwise claim a token is needed to log in.
-///
-/// The two `{ticket}` routes belong here on purpose: the sealed ticket in the
-/// path *is* the credential, because neither `<audio src>` nor `<video src>`
-/// can send a header. A document that omitted them would generate clients
-/// convinced a bearer is required, and they would send one that is not read.
-const PUBLIC_OPERATIONS: &[(&str, &str)] = &[
-    ("/health", "get"),
-    ("/ready", "get"),
-    ("/api/v2/setup", "get"),
-    ("/api/v2/setup", "post"),
-    ("/api/v2/auth/login", "post"),
-    ("/api/v2/auth/refresh", "post"),
-    ("/api/v2/auth/logout", "post"),
-    ("/api/v2/web/auth/login", "post"),
-    ("/api/v2/web/auth/refresh", "post"),
-    ("/api/v2/web/auth/logout", "post"),
-    ("/api/v2/oauth/token", "post"),
-    ("/api/v2/stream/{ticket}", "get"),
-    ("/api/v2/canvas-stream/{ticket}", "get"),
-    // The Last.fm return, and the one entry here that is not a ticket. It is
-    // reached by a person's browser coming back from another site, with no
-    // `Authorization` header and — every cookie of this server being
-    // `SameSite=Strict` — no session cookie either. What stands in for proof is
-    // narrower than an `Access`: a single-use random, an expiry of a few
-    // minutes, and a cookie good for this path alone, all three of which must
-    // agree. Listed so the document says what the route does rather than
-    // advertising a requirement nothing checks.
-    ("/api/v2/scrobble-links/lastfm/callback/{state}", "get"),
-];
-
-fn clear_security_on_public_operations(openapi: &mut utoipa::openapi::OpenApi) {
-    for (path, method) in PUBLIC_OPERATIONS {
-        let Some(item) = openapi.paths.paths.get_mut(*path) else {
-            continue;
-        };
-        // Every method the list may name, not only the two it happens to name
-        // today. `annotate_scope_refusals` reads what this leaves behind, so a
-        // public `PUT` that fell through here would keep the global requirement
-        // and be handed a 403 it can never answer — the pass would be declaring
-        // a refusal on a route that has no credential to refuse.
-        let operation = match *method {
-            "get" => item.get.as_mut(),
-            "post" => item.post.as_mut(),
-            "put" => item.put.as_mut(),
-            "delete" => item.delete.as_mut(),
-            "patch" => item.patch.as_mut(),
-            _ => None,
-        };
-        if let Some(operation) = operation {
-            operation.security = Some(Vec::new());
-        }
-    }
-}
-
-/// Declares the refusal a narrowed credential meets, on every mutation that can
-/// meet it.
-///
-/// [`api::authenticated`] answers `Forbidden` — 403 — whenever a route asks for
-/// `Access::Write` or `Access::Admin` and the caller's scopes do not grant it.
-/// Every mutation asks for one of the two, so every secured mutation can answer
-/// 403; nineteen of them documented 401 and 422 and stopped there. A client
-/// generated from that document has no branch for the refusal and reads a
-/// perfectly ordinary answer as a transport failure.
-///
-/// Injected here rather than written onto each `#[utoipa::path]`, for the
-/// reason [`annotate_mutation_headers`] is: a property that holds of every
-/// route in a class is stated once, somewhere adding a route cannot forget it.
-/// The nineteen were not an oversight repeated nineteen times — they are what
-/// happens when the same true sentence has to be typed again per route.
-///
-/// Reads are excluded because a read normally cannot produce it: `Access::Read`
-/// is granted by every scope list. That is a statement about `Access::Read` and
-/// not about GET, and the two come apart — `GET /api/v2/uploads/{session_id}`
-/// asks for `Access::Write`, because reading a transfer's state belongs to the
-/// write flow. Such a route documents its own 403, and
-/// `every_refusal_a_narrow_token_meets_is_documented` is what notices when one
-/// does not: it asks the server rather than this list.
-fn annotate_scope_refusals(openapi: &mut utoipa::openapi::OpenApi) {
-    use utoipa::openapi::{ContentBuilder, Ref, RefOr, ResponseBuilder};
-
-    for item in openapi.paths.paths.values_mut() {
-        // GET excluded on purpose: see above.
-        let operations = [
-            item.put.as_mut(),
-            item.post.as_mut(),
-            item.delete.as_mut(),
-            item.patch.as_mut(),
-        ];
-        for operation in operations.into_iter().flatten() {
-            // Emptied by `clear_security_on_public_operations`, which must
-            // therefore have run before this: a route that carries no
-            // credential has none to have refused.
-            if operation.security.as_ref().is_some_and(Vec::is_empty) {
-                continue;
-            }
-            // `or_insert_with`, so a route that already describes its own 403
-            // — the administrative ones, and the library feed acknowledgement —
-            // keeps the wording it chose.
-            operation
-                .responses
-                .responses
-                .entry("403".to_owned())
-                .or_insert_with(|| {
-                    ResponseBuilder::new()
-                        .description(
-                            "Forbidden. `code` is `forbidden`: the credential authenticates, \
-                             but its scopes do not admit this operation. Retrying is futile \
-                             — the token has to be reissued with wider scopes.",
-                        )
-                        .content(
-                            "application/json",
-                            ContentBuilder::new()
-                                .schema(Some(RefOr::Ref(Ref::from_schema_name("ErrorResponse"))))
-                                .build(),
-                        )
-                        .build()
-                        .into()
-                });
-        }
-    }
-}
-
-/// Attaches the two optional mutation headers, and the 409 they can produce, to
-/// every user-data *write*. `mutation_context` accepts them on any such route,
-/// so they are declared per operation rather than described in prose nobody
-/// generates a client from.
-///
-/// Reads are skipped: a GET carries no operation id and cannot conflict.
-fn annotate_mutation_headers(openapi: &mut utoipa::openapi::OpenApi) {
-    use utoipa::openapi::path::{ParameterBuilder, ParameterIn};
-    use utoipa::openapi::{RefOr, Required, ResponseBuilder, Schema, Type};
-
-    // utoipa 6 holds a parameter list as `RefOr`, so a parameter built here
-    // is wrapped on the way in rather than pushed bare.
-    let header = |name: &str, description: &str| {
-        RefOr::T(
-            ParameterBuilder::new()
-                .name(name)
-                .parameter_in(ParameterIn::Header)
-                .required(Required::False)
-                .description(Some(description.to_owned()))
-                .schema(Some(Schema::Object({
-                    let mut object = utoipa::openapi::Object::new();
-                    object.schema_type = utoipa::openapi::schema::SchemaType::new(Type::String);
-                    object.format = Some(utoipa::openapi::SchemaFormat::Custom("uuid".to_owned()));
-                    object
-                })))
-                .build(),
-        )
-    };
-
-    for item in openapi.paths.paths.values_mut() {
-        // GET excluded on purpose: reads carry no operation id.
-        let operations = [
-            item.put.as_mut(),
-            item.post.as_mut(),
-            item.delete.as_mut(),
-            item.patch.as_mut(),
-        ];
-        for operation in operations.into_iter().flatten() {
-            if !operation
-                .tags
-                .as_ref()
-                .is_some_and(|tags| tags.iter().any(|tag| tag == "user-data"))
-            {
-                continue;
-            }
-            operation
-                .responses
-                .responses
-                .entry("409".to_owned())
-                .or_insert_with(|| {
-                    ResponseBuilder::new()
-                        .description(
-                            "Conflict. `code` is `conflict`: the operation id was already used \
-                         for a different payload. Retrying verbatim will fail again — mint \
-                         a new operation id.",
-                        )
-                        .build()
-                        .into()
-                });
-            let parameters = operation.parameters.get_or_insert_with(Vec::new);
-            parameters.push(header(
-                api::OPERATION_ID_HEADER,
-                "Stable id for this logical mutation. Repeating it replays the original \
-                 outcome instead of applying twice; reusing it for a different payload is \
-                 rejected as a conflict. Generated server-side when absent.",
-            ));
-            parameters.push(header(
-                api::DEVICE_ID_HEADER,
-                "Device originating the mutation. Rejected when it belongs to another \
-                 account. Lets other devices skip their own echo in the sync journal.",
-            ));
-        }
-    }
-}
-
-pub async fn initialize(config: &Config) -> anyhow::Result<AppState> {
-    let db = database::Database::open(config).await?;
-    let booted = boot(db.clone(), config).await;
-    if booted.is_err() {
-        // A refused boot closes what it opened before it says so. Dropping the
-        // pool would not be enough: sqlx closes each connection on its own
-        // thread after the drop has returned, and the last one to close
-        // checkpoints the WAL under an exclusive lock. Whoever opens the file
-        // next — the operator retrying, or a test that has just watched the
-        // refusal — races that close and can find the database locked.
-        db.pool().close().await;
-    }
-    booted
-}
-
-async fn boot(db: database::Database, config: &Config) -> anyhow::Result<AppState> {
-    // Before anything is applied, and only when something will be (RFC-019
-    // decision 3): the copy is the database as this boot found it.
-    let copy = migration_backup::before_migrating(&db, config).await?;
-    if let Err(error) = db.migrate().await {
-        return Err(match copy {
-            Some(copy) => error.context(migration_backup::restore_hint(&copy)),
-            None => error,
-        });
-    }
-    let secret_box = Arc::new(security::SecretBox::load_or_create(
-        &config.instance_key_path,
-    )?);
-    let instance_key = std::fs::read(&config.instance_key_path)?;
-    let fingerprint = security::bytes_hash(&instance_key);
-    if !db
-        .bind_instance_key(&fingerprint, authentication::now_ms())
-        .await?
-    {
-        anyhow::bail!(
-            "instance.key does not match waveflow.db; restore the database and key from the same backup bundle"
-        );
-    }
-    // After the key check, not before: a mismatched pair aborts the boot, and
-    // scheduling a rescan on a database this instance is about to refuse would
-    // be writing to a catalogue that is not ours.
-    db.reconcile_catalog_identity(&config.pid).await?;
-    // After the key check too: a boot that is about to be refused has no
-    // business writing a token into a data directory that is not its own.
-    let setup = Arc::new(setup_token::SetupGate::prepare(
-        config,
-        db.setup_required().await?,
-    )?);
-    let auth = authentication::AuthService::new(db.clone(), config);
-    let scanner = scanner::ScanManager::new(
-        db.clone(),
-        config.artwork_dir.clone(),
-        config.scan_parallelism,
-    )
-    .with_link_roots(link_roots::LinkRoots::new(config.link_roots.clone()));
-    let media = media::MediaService::initialize(config).await?;
-    let sync = sync::SyncService::new(db.clone());
-    let services = services::DomainServices::new(
-        db.clone(),
-        Arc::clone(&secret_box),
-        sync.clone(),
-        scanner.clone(),
-        config,
-    );
-    // One of the two outbound surfaces this server has — metadata enrichment,
-    // below, is the other — and it is switched on by the operator naming a
-    // destination rather than by anybody linking an account.
-    // Nothing leaves until both are true: an adapter with no authorisation
-    // behind it is never handed a listen. RFC-010 decision 11.
-    for destination in &config.destinations {
-        // `Config::from_env` refuses to boot on a malformed destination, so the
-        // URL reaching here has already been through `validate_destination` —
-        // and `for_data_dir` builds an empty list rather than an unchecked one.
-        //
-        // Building the client is a different matter and really can fail at
-        // runtime, for reasons that have nothing to do with the operator's URL.
-        let target = match destination.provider {
-            services::ScrobbleProvider::ListenBrainz => {
-                scrobblers::outbound_client(config.scrobbling.request_timeout)
-                    .and_then(|client| {
-                        scrobblers::listenbrainz::ListenBrainz::new(client, &destination.url)
-                    })
-                    .map(|target| Arc::new(target) as Arc<dyn services::ScrobbleTarget>)
-            }
-            services::ScrobbleProvider::Maloja => {
-                scrobblers::outbound_client(config.scrobbling.request_timeout)
-                    .and_then(|client| scrobblers::maloja::Maloja::new(client, &destination.url))
-                    .map(|target| Arc::new(target) as Arc<dyn services::ScrobbleTarget>)
-            }
-            // **Last.fm needs more than a URL**, and a destination declared
-            // without it is not an error. Decision 4 forbids shipping any
-            // provider credential in an AGPL binary, so the application belongs
-            // to the operator; without one, the name stays listed — with the
-            // reason, which `GET /api/v2/scrobble-destinations` publishes — and
-            // nothing drains for it.
-            services::ScrobbleProvider::LastFm => {
-                let Some(application) = config.lastfm.clone() else {
-                    continue;
-                };
-                scrobblers::outbound_client(config.scrobbling.request_timeout)
-                    .and_then(|client| {
-                        scrobblers::lastfm::LastFm::new(
-                            client,
-                            &destination.url,
-                            application,
-                            config.scrobbling.request_timeout,
-                        )
-                    })
-                    .map(|target| {
-                        let target = Arc::new(target);
-                        // The same object in both registries: submitting a
-                        // listen and exchanging a token are two calls to one
-                        // destination, signed by one application, and splitting
-                        // them would be two places for that to drift.
-                        services.register_lastfm_exchange(
-                            &destination.name,
-                            Arc::clone(&target) as Arc<dyn services::LastFmSessionExchange>,
-                        );
-                        target as Arc<dyn services::ScrobbleTarget>
-                    })
-            }
-        };
-        match target {
-            Ok(target) => {
-                services.register_scrobble_target(destination.provider, &destination.name, target)
-            }
-            Err(error) => {
-                // **Never the URL itself.** `validate_destination` refuses a
-                // destination that carries credentials, so the one thing this
-                // branch is most likely to be handed is exactly the thing that
-                // must not be printed: `http://user:secret@host` would land in
-                // a startup log, or a support paste, in full. The variant names
-                // the fault precisely enough without it, and this repository's
-                // rule about secrets has no exception for an error path.
-                anyhow::bail!(
-                    "the configured {} destination {:?} is unusable: {error}",
-                    destination.provider.as_str(),
-                    destination.name
-                )
-            }
-        }
-    }
-    // Catching up and reconciling, once, under the writer gate — and *before*
-    // `main` starts the drain. The order is half the rule: reconciling while
-    // the background task already runs leaves a window, short and sufficient,
-    // in which listens leave for yesterday's destination. RFC-010 decision 10.
-    services.reconcile_scrobble_links().await?;
-    // A portrait search left fetching has no task across a restart; left at
-    // `complete = 0` it would hold its account's next search at 429 until its
-    // deadline passed (RFC-013 decision 4).
-    services.forget_unfinished_image_searches().await?;
-    // A podcast download the last process left running has no task any more
-    // (RFC-025): it goes back to `new`, and its staging file goes.
-    services.reconcile_podcasts().await?;
-    // Off unless the operator named a provider, and then it still makes no
-    // request until somebody asks about an artist (RFC-011 decisions 3 and 6).
-    services.use_enrichment(enrichment::Enrichment::new(
-        db.clone(),
-        &config.metadata,
-        config.artwork_dir.clone(),
-    )?);
-    // Off unless the operator named `lrclib`, and then it still asks nothing
-    // until somebody asks for the lyrics of a track that has none (RFC-024
-    // decisions 1 and 3).
-    services.use_lyrics_lookup(lrclib::LyricsLookup::new(db.clone(), &config.lyrics)?);
-    // Before anything reads `track_quality`: a measurement another analyser or
-    // another FFmpeg made is deleted here, so every read can call a row current
-    // on its content hash alone (RFC-016 decision 5).
-    services
-        .use_quality_decoder(quality::Decoder {
-            digest: media.ffmpeg_digest().to_owned(),
-            webp: quality::probe_webp(&config.ffmpeg_path).await,
-        })
-        .await?;
-    Ok(AppState {
-        db,
-        auth,
-        secret_box,
-        scanner,
-        media,
-        services,
-        sync,
-        artwork_dir: config.artwork_dir.clone(),
-        instance_key_path: config.instance_key_path.clone(),
-        public_url: config.public_url.clone(),
-        stream_ticket_ttl: config.stream_ticket_ttl,
-        refresh_token_ttl: config.refresh_token_ttl,
-        upload_batch_body_limit: negotiation_body_limit(&config.uploads),
-        upload_chunk_body_limit: chunk_body_limit(&config.uploads),
-        // Refused at startup if it does not fit, so this conversion cannot be
-        // the place that decides what a ceiling falls back to.
-        canvas_body_limit: usize::try_from(config.canvas.max_bytes).unwrap_or(usize::MAX),
-        trusted_proxies: config.trusted_proxies.clone().into(),
-        setup,
-    })
-}
-
-pub fn app(config: &Config, state: AppState) -> Router {
-    let openapi = ApiDoc::openapi();
-    let openapi_for_route = openapi.clone();
-    let request_id_header = axum::http::HeaderName::from_static(REQUEST_ID_HEADER);
-    let middleware = ServiceBuilder::new()
-        // Before `SetRequestIdLayer`, which keeps whatever the caller sent and
-        // only forges an id when the header is absent. Dropping the inbound one
-        // unconditionally is what makes the layer below always mint, so the
-        // value in every `http_request` span is one this server chose.
-        //
-        // `CLAUDE.md` says no header reaches a trace sink, without exception,
-        // and an id narrow enough to look like an identifier is still a string
-        // a stranger picked: send a well-formed UUID that somebody else's
-        // requests are using and the trace record stops telling two callers
-        // apart. Validating the shape would have addressed the noise and left
-        // that.
-        //
-        // The correlation the header exists for is not lost, only reversed:
-        // `PropagateRequestIdLayer` returns the minted id on the response, so
-        // an upstream proxy records the name this server gave rather than
-        // imposing one. That is the ordinary arrangement wherever a server does
-        // not trust what is in front of it, and this one is routinely in front
-        // of nothing at all.
-        .map_request(|mut request: Request<_>| {
-            request.headers_mut().remove(REQUEST_ID_HEADER);
-            request
-        })
-        .layer(SetRequestIdLayer::new(
-            request_id_header.clone(),
-            MakeRequestUuid,
-        ))
-        // Query strings may contain Subsonic credentials and public-share
-        // paths contain bearer tokens. Neither may reach a trace sink.
-        .layer(
-            TraceLayer::new_for_http().make_span_with(|request: &Request<_>| {
-                let request_id = request
-                    .headers()
-                    .get(REQUEST_ID_HEADER)
-                    .and_then(|value| value.to_str().ok())
-                    .unwrap_or("");
-                let path = trace_path(request.uri().path());
-                tracing::info_span!(
-                    "http_request",
-                    method = %request.method(),
-                    path = path,
-                    request_id = %request_id
-                )
-            }),
-        )
-        .layer(PropagateRequestIdLayer::new(request_id_header));
-
-    let ordinary = Router::new()
-        .merge(api::router(state.clone()))
-        .route(
-            OPENAPI_JSON_PATH,
-            axum::routing::get(move || openapi_response(openapi_for_route.clone())),
-        )
-        .layer(tower_http::timeout::TimeoutLayer::with_status_code(
-            axum::http::StatusCode::REQUEST_TIMEOUT,
-            config.request_timeout,
-        ));
-
-    // What may be compressed, kept apart from what may not.
-    //
-    // The exclusion is **structural rather than conditional**: the media
-    // routes and the Subsonic facade are merged outside this group, so no
-    // predicate decides whether a stream is compressed — the layer never sees
-    // one. Compressing an already-compressed body spends CPU for nothing, and
-    // a body that arrives re-encoded is a body whose length and ranges no
-    // longer describe the file a player is seeking through.
-    //
-    // `CompressionLayer::new()` carries tower-http's `DefaultPredicate`, which
-    // leaves alone anything under 32 bytes, images, gRPC and — load-bearing
-    // here — `text/event-stream`: the scan event feed lives on `/api/v2` and
-    // would otherwise be buffered into silence by its own encoder.
-    //
-    // The Subsonic facade is out for a reason worth writing down, because it
-    // costs a real gain: it serves every method through one route,
-    // `/rest/{method}`, so a catalogue listing and an audio stream arrive by
-    // the same path. Separating them there would mean trusting a content-type
-    // predicate with the correctness of byte-range playback, which is the one
-    // thing in this server that four clients were replayed to establish.
-    let compressible = Router::new()
-        .merge(ordinary)
-        // A portrait search may take minutes; it keeps a timeout of its own.
-        .merge(api::search_router(state.clone()))
-        // Anything no API route claimed is served by the embedded web client:
-        // a built asset, or the shell for a client-side route. This is what
-        // the layer is mostly for — the built client leaves raw at roughly
-        // 497 kB and about 152 kB gzipped.
-        .fallback(webui::handler)
-        .layer(tower_http::compression::CompressionLayer::new());
-
-    let router = Router::new()
-        .merge(compressible)
-        // Media bodies can outlive the ordinary API timeout. FFmpeg and
-        // disconnected consumers are bounded by MediaService itself.
-        .merge(media::router(state.clone()))
-        .merge(public_share::router(state.clone(), config.request_timeout))
-        // The API reference and the script it loads, from the binary (RFC-023
-        // decision 3). Outside the compression layer: the script is stored
-        // compressed already.
-        .merge(reference::router(&openapi))
-        .merge(subsonic::router(state))
-        .layer(DefaultBodyLimit::max(16 * 1024));
-
-    // CORS goes on first so that the request-id and trace layers end up
-    // outside it. `CorsLayer` answers a preflight itself without calling the
-    // service under it, so anything applied inside it never runs for an
-    // `OPTIONS` — which would leave preflights unnamed, against what the API
-    // guide promises, and invisible in the traces. An origin rejected by
-    // `WAVEFLOW_ALLOWED_ORIGINS` is exactly the thing an operator has to
-    // diagnose, and it was the one request that left no record.
-    let cors = if config.allowed_origins.is_empty() {
-        router
-    } else {
-        router.layer(
-            CorsLayer::new()
-                .allow_origin(AllowOrigin::list(config.allowed_origins.clone()))
-                .allow_methods([
-                    axum::http::Method::GET,
-                    axum::http::Method::POST,
-                    axum::http::Method::PUT,
-                    axum::http::Method::PATCH,
-                    axum::http::Method::DELETE,
-                    axum::http::Method::OPTIONS,
-                ])
-                .allow_headers([
-                    axum::http::header::AUTHORIZATION,
-                    axum::http::header::CONTENT_TYPE,
-                    axum::http::header::RANGE,
-                    axum::http::HeaderName::from_static(api::WEB_CSRF_HEADER),
-                    axum::http::HeaderName::from_static(api::OPERATION_ID_HEADER),
-                    axum::http::HeaderName::from_static(api::DEVICE_ID_HEADER),
-                ])
-                // `x-request-id` is exposed and deliberately not allowed: a
-                // browser client should be able to read the name this server
-                // gave its request, which is what makes it quotable in a bug
-                // report, but it has no business sending one — an inbound value
-                // is dropped before anything reads it.
-                .expose_headers([
-                    axum::http::header::ACCEPT_RANGES,
-                    axum::http::header::CONTENT_LENGTH,
-                    axum::http::header::CONTENT_RANGE,
-                    axum::http::HeaderName::from_static(REQUEST_ID_HEADER),
-                ]),
-        )
-    };
-
-    cors.layer(middleware)
-}
-
-/// Every prefix whose next path segment is a credential, and what a trace sink
-/// sees instead.
-///
-/// **A table rather than a chain of `if`s, because the chain lost one.** This
-/// function knew the audio ticket and the share token; the server has a third
-/// such route, `/api/v2/canvas-stream/{ticket}`, minted beside the audio one in
-/// `media.rs`, played by a `<video src>` that cannot send an `Authorization`
-/// header, and listed beside its twin in `PUBLIC_OPERATIONS` two hundred lines
-/// above. It was never added here, so the sealed ticket went into the
-/// `http_request` span verbatim.
-///
-/// **What that actually cost, stated exactly.** The span is opened at INFO, but
-/// nothing here asks for span lifecycle events, so opening one writes nothing on
-/// its own: a canvas playback that succeeds quietly emitted no line. The ticket
-/// reached a sink on every canvas request that logged anything *inside* that
-/// span — a failed ticket lookup, a 5xx — and on every request at all under
-/// `tower_http=debug`, where the tower layer's own request and response events
-/// fire in it. An earlier version of this paragraph said "every canvas
-/// playback", which is one notch stronger than the mechanism.
-///
-/// The shape is the fix. A new ticket route now has one obvious place to be
-/// declared, next to the ones that look exactly like it, rather than a branch
-/// somebody has to remember to add.
-///
-/// Matched on the raw path, so `/API/v2/stream/…` and a percent-encoded
-/// separator miss every entry. Left that way deliberately: reaching those
-/// spellings means already holding the ticket, so it is hardening rather than a
-/// disclosure route, and normalising here would put a second opinion about what
-/// a path means next to the router's.
-const CREDENTIAL_BEARING_PREFIXES: [(&str, &str); 4] = [
-    ("/api/v2/stream/", "/api/v2/stream/{redacted}"),
-    ("/api/v2/canvas-stream/", "/api/v2/canvas-stream/{redacted}"),
-    ("/share/", "/share/{redacted}"),
-    // The Last.fm return. Its `{state}` is a single-use random worth a
-    // profile for a quarter of an hour, and the `token` Last.fm appends is
-    // worth one for an hour — that one sits in the query string, which no
-    // trace of this server keeps. The rule in `CLAUDE.md` has no exception for
-    // a secret that only lasts an hour.
-    (
-        crate::services::LASTFM_CALLBACK_PREFIX,
-        "/api/v2/scrobble-links/lastfm/callback/{redacted}",
-    ),
-];
-
-fn trace_path(path: &str) -> &str {
-    for (prefix, redacted) in CREDENTIAL_BEARING_PREFIXES {
-        if path.starts_with(prefix) {
-            return redacted;
-        }
-    }
-    path
-}
-
-async fn openapi_response(openapi: utoipa::openapi::OpenApi) -> Response {
-    match serde_json::to_string(&openapi) {
-        Ok(body) => (
-            [(axum::http::header::CONTENT_TYPE, "application/json")],
-            body,
-        )
-            .into_response(),
-        Err(error) => {
-            tracing::error!(error = %error, "OpenAPI serialization failed");
-            (
-                axum::http::StatusCode::INTERNAL_SERVER_ERROR,
-                "OpenAPI serialization failed",
-            )
-                .into_response()
-        }
-    }
-}
-
-pub async fn shutdown_signal() {
-    let ctrl_c = async {
-        if let Err(error) = tokio::signal::ctrl_c().await {
-            tracing::error!(error = %error, "failed to install Ctrl-C handler");
-        }
-    };
-
-    #[cfg(unix)]
-    let terminate = async {
-        match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) {
-            Ok(mut signal) => {
-                signal.recv().await;
-            }
-            Err(error) => tracing::error!(error = %error, "failed to install terminate handler"),
-        }
-    };
-
-    #[cfg(not(unix))]
-    let terminate = std::future::pending::<()>();
-
-    tokio::select! {
-        () = ctrl_c => {},
-        () = terminate => {},
-    }
-    tokio::time::sleep(Duration::from_millis(25)).await;
-}
-
-#[cfg(test)]
-mod tests {
-    use super::trace_path;
-
-    /// The scrobbling routes carry no operation-id protocol, and must not
-    /// advertise one.
-    ///
-    /// `annotate_mutation_headers` injects a `409` and the two mutation headers
-    /// into every `user-data` write, because every one of those goes through
-    /// `mutation_context`. These do not — RFC-010 decision 12 keeps this state
-    /// out of synchronisation entirely — so they carry their own tag.
-    ///
-    /// Written because removing a hand-written `409` from the retry route did
-    /// not remove the `409`: it vacated the entry that the injected one then
-    /// filled, with no response schema and a description about operation ids
-    /// that was false for it. The document was worse than before the fix, and
-    /// nothing said so.
-    #[test]
-    fn the_scrobbling_routes_advertise_no_operation_id_protocol() {
-        use utoipa::openapi::RefOr;
-        use utoipa::OpenApi;
-
-        let openapi = super::ApiDoc::openapi();
-        let mut checked = 0;
-        for (path, item) in &openapi.paths.paths {
-            if !path.starts_with("/api/v2/scrobble-") {
-                continue;
-            }
-            for operation in [
-                item.put.as_ref(),
-                item.post.as_ref(),
-                item.delete.as_ref(),
-                item.patch.as_ref(),
-            ]
-            .into_iter()
-            .flatten()
-            {
-                checked += 1;
-                assert!(
-                    !operation.responses.responses.contains_key("409"),
-                    "{path} advertises a conflict it cannot produce"
-                );
-                let names: Vec<&str> = operation
-                    .parameters
-                    .iter()
-                    .flatten()
-                    .map(|parameter| match parameter {
-                        RefOr::T(parameter) => parameter.name.as_str(),
-                        RefOr::Ref(reference) => panic!(
-                            "{path} advertises a parameter by reference ({}), which this check cannot read",
-                            reference.ref_location
-                        ),
-                    })
-                    .collect();
-                assert!(
-                    !names.contains(&super::api::OPERATION_ID_HEADER),
-                    "{path} advertises an operation id it never reads"
-                );
-                assert!(
-                    !names.contains(&super::api::DEVICE_ID_HEADER),
-                    "{path} advertises a device id it never reads"
-                );
-            }
-        }
-        assert_eq!(
-            checked, 5,
-            "two on the link, two on the queue, and the Last.fm authorisation — a count that \
-             falls if a route is added without deciding which protocol it belongs to"
-        );
-    }
-
-    /// Every `user-data` mutation advertises both headers and a `409`.
-    ///
-    /// Written because nothing asserted the presence of what
-    /// `annotate_mutation_headers` injects — only its absence on the
-    /// scrobbling routes. An annotation that stopped injecting would have made
-    /// that neighbouring test pass more easily, and the document would have
-    /// lost the operation-id protocol with a green suite.
-    ///
-    /// `user-data` is the tag the annotation selects on, so this walk asks the
-    /// same question the pass answers rather than a wider one it never claimed.
-    #[test]
-    fn every_user_data_mutation_advertises_the_operation_id_protocol() {
-        use utoipa::openapi::RefOr;
-        use utoipa::OpenApi;
-
-        // Sixteen today: the favourite, rating, play-queue and now-playing
-        // mutations, the playlist import — which claims an operation like
-        // every other playlist creation, because that is the verb it calls —
-        // and the move and the removal of one playlist entry, which journal as
-        // an update does. A new one lands here deliberately, not silently.
-        let expected = 16;
-        let openapi = super::ApiDoc::openapi();
-        let mut checked = 0;
-        for (path, item) in &openapi.paths.paths {
-            for operation in [
-                item.put.as_ref(),
-                item.post.as_ref(),
-                item.delete.as_ref(),
-                item.patch.as_ref(),
-            ]
-            .into_iter()
-            .flatten()
-            {
-                if !operation
-                    .tags
-                    .as_ref()
-                    .is_some_and(|tags| tags.iter().any(|tag| tag == "user-data"))
-                {
-                    continue;
-                }
-                assert!(
-                    operation.responses.responses.contains_key("409"),
-                    "{path} takes an operation id without documenting the conflict it can answer"
-                );
-                let names: Vec<&str> = operation
-                    .parameters
-                    .iter()
-                    .flatten()
-                    .map(|parameter| match parameter {
-                        RefOr::T(parameter) => parameter.name.as_str(),
-                        RefOr::Ref(reference) => panic!(
-                            "{path} advertises a parameter by reference ({}), which this check cannot read",
-                            reference.ref_location
-                        ),
-                    })
-                    .collect();
-                assert!(
-                    names.contains(&super::api::OPERATION_ID_HEADER),
-                    "{path} mutates without advertising an operation id"
-                );
-                assert!(
-                    names.contains(&super::api::DEVICE_ID_HEADER),
-                    "{path} mutates without advertising a device id"
-                );
-                checked += 1;
-            }
-        }
-        assert_eq!(
-            checked, expected,
-            "{checked} tagged mutations examined, not {expected} — a walk that stops finding \
-             them makes every assertion above vacuous, so the count is pinned rather than \
-             merely non-zero"
-        );
-    }
-
-    /// Every entry in `PUBLIC_OPERATIONS` names an operation that exists, and
-    /// leaves it carrying no security requirement.
-    ///
-    /// The list is looked up by two strings, so a path that is renamed or a
-    /// method spelled `PUT` instead of `put` matches nothing, clears nothing,
-    /// and goes on looking correct. That was cheap while the result was only a
-    /// missing security block. `annotate_scope_refusals` reads what this pass
-    /// leaves behind, so a public operation that keeps the global requirement
-    /// is now handed a 403 it can never answer — a refusal documented on a
-    /// route that holds no credential to refuse.
-    #[test]
-    fn every_public_operation_is_found_and_cleared() {
-        use utoipa::OpenApi;
-
-        let openapi = super::ApiDoc::openapi();
-        for (path, method) in super::PUBLIC_OPERATIONS {
-            let item = openapi
-                .paths
-                .paths
-                .get(*path)
-                .unwrap_or_else(|| panic!("{path} is named here but is not a documented path"));
-            let operation = match *method {
-                "get" => item.get.as_ref(),
-                "post" => item.post.as_ref(),
-                "put" => item.put.as_ref(),
-                "delete" => item.delete.as_ref(),
-                "patch" => item.patch.as_ref(),
-                other => panic!("{other} is not a method this list may name"),
-            }
-            .unwrap_or_else(|| panic!("{method} {path} is not a documented operation"));
-            assert!(
-                operation.security.as_ref().is_some_and(Vec::is_empty),
-                "{method} {path} is public and must carry no security requirement"
-            );
-        }
-    }
-
-    /// Every entry in the table redacts, and no entry can shadow another.
-    ///
-    /// A property over the table rather than one `assert_eq!` per entry,
-    /// because a hand-written assertion per entry has exactly the weakness the
-    /// table was written to fix: it cannot notice the entry nobody wrote. This
-    /// form also catches the edit that would quietly undo the whole thing — a
-    /// broad prefix inserted above a narrow one, which first-match-wins would
-    /// silently relabel.
-    #[test]
-    fn every_credential_bearing_prefix_is_redacted() {
-        for (prefix, redacted) in super::CREDENTIAL_BEARING_PREFIXES {
-            assert_eq!(
-                redacted,
-                format!("{prefix}{{redacted}}"),
-                "{prefix} must replace its next segment and nothing else"
-            );
-            assert_eq!(
-                trace_path(&format!("{prefix}a-sealed-secret")),
-                redacted,
-                "{prefix} must not reach a trace sink carrying its credential"
-            );
-            // A share token is followed by more path, and the whole tail goes.
-            assert_eq!(
-                trace_path(&format!("{prefix}a-sealed-secret/tracks/id/stream")),
-                redacted
-            );
-        }
-
-        for (outer, _) in super::CREDENTIAL_BEARING_PREFIXES {
-            for (inner, _) in super::CREDENTIAL_BEARING_PREFIXES {
-                assert!(
-                    outer == inner || !inner.starts_with(outer),
-                    "{outer} shadows {inner}: first match wins, so {inner} would never be reached"
-                );
-            }
-        }
-
-        // And a path that carries nothing is left exactly as it is.
-        assert_eq!(trace_path("/rest/ping.view"), "/rest/ping.view");
-    }
-
-    /// Every public route whose path ends in a ticket has a redaction prefix.
-    ///
-    /// **This is the assertion that would have caught the canvas ticket**, and
-    /// the test above would not have. A table is self-consistent on its own: an
-    /// entry with a typo in its prefix redacts its own typo and satisfies every
-    /// property there, while the real route goes on being logged. What no
-    /// property over the table alone can do is notice a route nobody added to
-    /// it.
-    ///
-    /// `PUBLIC_OPERATIONS` had `/api/v2/canvas-stream/{ticket}` listed
-    /// correctly, two hundred lines from a redaction list that did not. The two
-    /// are tied together here so that distance stops mattering.
-    #[test]
-    fn every_public_ticket_route_has_a_redaction_prefix() {
-        for (path, _) in super::PUBLIC_OPERATIONS {
-            // `{state}` as well as `{ticket}`: the Last.fm return is the first
-            // public route whose path carries a credential under another name,
-            // and a check that knew only one spelling would have let it through
-            // — which is the shape of the canvas ticket this test was written
-            // for.
-            let Some(prefix) = path
-                .strip_suffix("{ticket}")
-                .or_else(|| path.strip_suffix("{state}"))
-            else {
-                continue;
-            };
-            assert!(
-                super::CREDENTIAL_BEARING_PREFIXES
-                    .iter()
-                    .any(|(candidate, _)| *candidate == prefix),
-                "{path} carries a credential in its path and nothing redacts it"
-            );
-        }
-    }
-}

From 180afed74e888566baa0bd43fedebadf90653695 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 26 Oct 2026 09:51:51 +0100
Subject: [PATCH 3/4] refactor(config): split the configuration into one file
 per settings family

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 src/config/access.rs       |   53 ++
 src/config/env.rs          |   59 ++
 src/config/for_data_dir.rs |  165 ++++
 src/config/from_env.rs     |  392 ++++++++
 src/config/limits.rs       |  111 +++
 src/config/metadata.rs     |  235 +++++
 src/config/mod.rs          | 1795 +-----------------------------------
 src/config/pid.rs          |   49 +
 src/config/podcasts.rs     |  111 +++
 src/config/scrobbling.rs   |  250 +++++
 src/config/tests.rs        |  409 ++++++++
 11 files changed, 1854 insertions(+), 1775 deletions(-)
 create mode 100644 src/config/access.rs
 create mode 100644 src/config/env.rs
 create mode 100644 src/config/for_data_dir.rs
 create mode 100644 src/config/from_env.rs
 create mode 100644 src/config/limits.rs
 create mode 100644 src/config/metadata.rs
 create mode 100644 src/config/pid.rs
 create mode 100644 src/config/podcasts.rs
 create mode 100644 src/config/scrobbling.rs
 create mode 100644 src/config/tests.rs

diff --git a/src/config/access.rs b/src/config/access.rs
new file mode 100644
index 00000000..73cf8d78
--- /dev/null
+++ b/src/config/access.rs
@@ -0,0 +1,53 @@
+//! How the server is reached: the origin it is published at, the proxies whose
+//! forwarding it believes, and the token that guards first-run setup.
+
+/// The shortest operator-chosen setup token accepted.
+///
+/// The drawn one carries 256 bits. This is the floor for a value somebody
+/// typed, and nothing throttles setup: a guess at the token costs one request.
+pub const SETUP_TOKEN_MIN_CHARS: usize = 16;
+
+/// `WAVEFLOW_SETUP_TOKEN`, refused when too short to stand unthrottled.
+pub(super) fn parse_setup_token(value: Option<String>) -> anyhow::Result<Option<String>> {
+    match value {
+        Some(token) if token.chars().count() < SETUP_TOKEN_MIN_CHARS => anyhow::bail!(
+            "WAVEFLOW_SETUP_TOKEN must be at least {SETUP_TOKEN_MIN_CHARS} characters"
+        ),
+        other => Ok(other),
+    }
+}
+
+pub(super) fn normalize_public_url(value: &str) -> anyhow::Result<String> {
+    let parsed = url::Url::parse(value.trim())
+        .map_err(|error| anyhow::anyhow!("invalid WAVEFLOW_PUBLIC_URL: {error}"))?;
+    if !matches!(parsed.scheme(), "http" | "https")
+        || !parsed.username().is_empty()
+        || parsed.password().is_some()
+        || parsed.query().is_some()
+        || parsed.fragment().is_some()
+        || !matches!(parsed.path(), "" | "/")
+    {
+        anyhow::bail!(
+            "WAVEFLOW_PUBLIC_URL must be an http(s) origin without credentials, path, query or fragment"
+        );
+    }
+    Ok(parsed.origin().ascii_serialization())
+}
+
+/// `WAVEFLOW_TRUSTED_PROXIES`: addresses or CIDR blocks. A bare address is its
+/// own block. A typo refuses to boot rather than trusting less, or more, than
+/// the operator wrote. A block written in IPv4-mapped form is read as the IPv4
+/// block it spells, which is how the limiter compares it.
+pub(super) fn parse_proxy_addresses(list: &str) -> anyhow::Result<Vec<ipnet::IpNet>> {
+    list.split(',')
+        .map(str::trim)
+        .filter(|entry| !entry.is_empty())
+        .map(|entry| {
+            entry
+                .parse::<ipnet::IpNet>()
+                .or_else(|_| entry.parse::<std::net::IpAddr>().map(ipnet::IpNet::from))
+                .map(crate::sign_in::trusted_network)
+                .map_err(|_| anyhow::anyhow!("invalid WAVEFLOW_TRUSTED_PROXIES entry {entry:?}"))
+        })
+        .collect()
+}
diff --git a/src/config/env.rs b/src/config/env.rs
new file mode 100644
index 00000000..0a8074af
--- /dev/null
+++ b/src/config/env.rs
@@ -0,0 +1,59 @@
+//! The generic readers every setting goes through: one variable, parsed or
+//! refused.
+
+/// One environment variable, trimmed, with an empty value read as absent.
+///
+/// "Set to nothing" and "not set" are the same statement from an operator, and
+/// an `.env` file that keeps a commented-out key as `NAME=` is the ordinary way
+/// of making it.
+pub(super) fn read_trimmed_env(name: &str) -> Option<String> {
+    std::env::var(name)
+        .ok()
+        .map(|value| value.trim().to_owned())
+        .filter(|value| !value.is_empty())
+}
+
+pub(super) fn parse_env<T>(name: &str, default: &str) -> anyhow::Result<T>
+where
+    T: std::str::FromStr,
+    T::Err: std::fmt::Display,
+{
+    std::env::var(name)
+        .unwrap_or_else(|_| default.to_owned())
+        .parse()
+        .map_err(|error| anyhow::anyhow!("invalid {name}: {error}"))
+}
+
+/// A flag an operator either set on purpose or did not set at all.
+///
+/// A spelling this does not recognise is refused rather than read as `false`.
+/// Every silent fallback in this file is a bug waiting to be filed against
+/// something else, and this one especially: `WAVEFLOW_SCROBBLE_ALLOW_PLAINTEXT`
+/// guards whether a personal token may cross a network in clear, so an operator
+/// who typed `True ` or `on` must be told, not quietly overruled.
+pub(super) fn parse_bool_env(name: &str, default: bool) -> anyhow::Result<bool> {
+    let Ok(raw) = std::env::var(name) else {
+        return Ok(default);
+    };
+    match raw.trim().to_ascii_lowercase().as_str() {
+        "" => Ok(default),
+        "1" | "true" | "yes" | "on" => Ok(true),
+        "0" | "false" | "no" | "off" => Ok(false),
+        other => anyhow::bail!("invalid {name}: expected a boolean, found {other:?}"),
+    }
+}
+
+pub(super) fn parse_positive_env<T>(name: &str, default: T) -> anyhow::Result<T>
+where
+    T: std::str::FromStr + PartialOrd + Default + Copy + std::fmt::Display,
+    T::Err: std::fmt::Display,
+{
+    let raw = std::env::var(name).unwrap_or_else(|_| default.to_string());
+    let value = raw
+        .parse::<T>()
+        .map_err(|error| anyhow::anyhow!("invalid {name}: {error}"))?;
+    if value <= T::default() {
+        anyhow::bail!("invalid {name}: must be greater than zero");
+    }
+    Ok(value)
+}
diff --git a/src/config/for_data_dir.rs b/src/config/for_data_dir.rs
new file mode 100644
index 00000000..77e8ad43
--- /dev/null
+++ b/src/config/for_data_dir.rs
@@ -0,0 +1,165 @@
+//! `Config::for_data_dir`: the configuration the test suite boots under.
+
+use std::{path::PathBuf, time::Duration};
+
+use super::pid::default_pid_specs;
+use super::scrobbling::test_destinations;
+use super::{
+    CanvasLimits, Config, LibraryEventRetention, LyricsSettings, MetadataSettings, PodcastSettings,
+    RemoteArtworkSettings, ScrobbleLimits, UploadLimits,
+};
+
+impl Config {
+    pub fn for_data_dir(data_dir: PathBuf) -> Self {
+        let transcode_cache_dir = data_dir.join("transcode-cache");
+        let canvas_dir_for_tests = data_dir.join("canvas");
+        let podcast_dir_for_tests = data_dir.join("podcasts");
+        Self {
+            bind_addr: "127.0.0.1:0".parse().expect("literal socket address"),
+            public_url: Some("http://waveflow.test".to_owned()),
+            request_timeout: Duration::from_secs(30),
+            database_path: data_dir.join("waveflow.db"),
+            instance_key_path: data_dir.join("instance.key"),
+            artwork_dir: data_dir.join("artwork"),
+            data_dir,
+            db_max_connections: 4,
+            // Generous where production is tight, and for a reason production
+            // does not have: a test target boots a whole server per test, so
+            // several cold databases are created at once on a machine already
+            // compiling. Three targets — uploads, media, scrobbling — have
+            // each failed this acquire on the Windows runner at different
+            // times, naming whichever test happened to be unlucky. Raising
+            // the budget removes a lottery; it hides no wrong answer, because
+            // the only thing this timeout can produce is a refusal to start.
+            db_acquire_timeout: Duration::from_secs(30),
+            sqlite_busy_timeout: Duration::from_secs(5),
+            access_token_ttl: Duration::from_secs(15 * 60),
+            stream_ticket_ttl: Duration::from_secs(60 * 60),
+            refresh_token_ttl: Duration::from_secs(30 * 24 * 60 * 60),
+            // A year, as production has it: a suite that minted tokens with no
+            // expiry could not tell a bounded one from an unbounded one.
+            api_token_ttl: Some(Duration::from_secs(365 * 24 * 60 * 60)),
+            scan_interval: None,
+            scan_parallelism: 2,
+            // Off, like the periodic scan: a test that writes a file and then
+            // scans must not find a second scan racing its own. The watcher's
+            // tests start one themselves.
+            watch: false,
+            watch_delay: Duration::from_millis(200),
+            unavailable_retention: None,
+            // Production's default: the suite purges the way a server does.
+            purge_grace: Duration::from_secs(168 * 60 * 60),
+            link_roots: Vec::new(),
+            subsonic_replay_gain: crate::replay_gain::ReplayGainMode::Off,
+            ffmpeg_path: PathBuf::from("ffmpeg"),
+            ffprobe_path: PathBuf::from("ffprobe"),
+            transcode_cache_dir,
+            transcode_cache_max_bytes: 128 * 1024 * 1024,
+            transcode_global_limit: 2,
+            transcode_per_user_limit: 1,
+            quality_parallelism: 1,
+            // Small enough that a test can reach every bound without writing a
+            // gigabyte, and shaped like production rather than unlimited: a
+            // suite that never meets a limit never proves one exists.
+            uploads: UploadLimits {
+                max_file_bytes: 1024 * 1024,
+                library_quota_bytes: 4 * 1024 * 1024,
+                chunk_bytes: 64 * 1024,
+                batch_limit: 8,
+                sessions_per_user: 2,
+                session_ttl: Duration::from_secs(3600),
+            },
+            // Small enough that a test can write past the floor without
+            // writing ten thousand rows, and shaped like production rather
+            // than unlimited.
+            library_event_retention: LibraryEventRetention {
+                days: 30,
+                min_events: 4,
+            },
+            canvas_dir: canvas_dir_for_tests,
+            // Same reasoning as the upload limits above: small enough that a
+            // test can reach every bound, shaped like production rather than
+            // unlimited.
+            canvas: CanvasLimits {
+                max_bytes: 256 * 1024,
+                max_duration_secs: 15,
+                library_quota_bytes: 1024 * 1024,
+            },
+            // Same reasoning again: small enough that a test can exhaust the
+            // attempts without waiting out eight doublings, shaped like
+            // production rather than unlimited. The interval is never reached —
+            // `spawn_scrobble_drain` is started by `main`, and tests run the
+            // pass themselves.
+            scrobbling: ScrobbleLimits {
+                drain_interval: Duration::from_secs(60),
+                // Long enough that no test double ever meets it by accident;
+                // the one test that means to meet it shortens this first.
+                request_timeout: Duration::from_secs(30),
+                max_attempts: 3,
+                stale_after: Duration::from_secs(3600),
+                batch: 8,
+                retention_days: 30,
+            },
+            // One instance, declared and unreachable.
+            //
+            // **Declared**, because a member may only link a name the operator
+            // published, and a suite with an empty list could link nothing and
+            // would exercise none of the queue.
+            //
+            // **Unreachable**, because the suite must never reach the real
+            // ListenBrainz: port 1 on loopback is a port nothing binds. Every
+            // test that drives the queue replaces the adapter with a double
+            // through `register_scrobble_target`, and the handful that mean to
+            // exercise a real request point this at a server they started
+            // themselves — over plain HTTP on loopback, which is why the
+            // plaintext escape is on here and off in production.
+            destinations: test_destinations(),
+            // No application, so the suite never reaches the real Last.fm and
+            // the destination declared above stays adapterless — which is what
+            // two tests here stand on.
+            lastfm: None,
+            outbound_allow_plaintext: true,
+            // Off, as production defaults: the suite never reaches a real
+            // provider, and the targets that exercise enrichment build their
+            // own engine against a listener of their own.
+            metadata: MetadataSettings::off(),
+            // Off as well, and for the same reason: the targets that exercise
+            // LRCLIB build their own lookup against a listener of their own.
+            lyrics: LyricsSettings::off(),
+            // Off, as production defaults, and small enough that a test can
+            // reach every bound. The podcast targets switch it on and point
+            // it at a listener of their own on loopback, which is the one
+            // reason the address policy here admits loopback.
+            podcasts: PodcastSettings {
+                enabled: false,
+                refresh_interval: None,
+                allow_http: false,
+                max_feed_bytes: 256 * 1024,
+                max_episode_bytes: 1024 * 1024,
+                quota_bytes: 4 * 1024 * 1024,
+                feed_timeout: Duration::from_secs(10),
+                download_timeout: Duration::from_secs(30),
+                dir: podcast_dir_for_tests,
+                addresses: crate::portrait::AddressPolicy::AllowLoopback,
+            },
+            // On, as production defaults, and admitting loopback for the same
+            // reason the podcast policy above does: the image hosts the suite
+            // serves are listeners of its own. No test reaches this unless it
+            // names an image, so nothing leaves the machine.
+            remote_artwork: RemoteArtworkSettings {
+                enabled: true,
+                timeout: Duration::from_secs(10),
+                addresses: crate::portrait::AddressPolicy::AllowLoopback,
+            },
+            allowed_origins: Vec::new(),
+            trusted_proxies: Vec::new(),
+            // Drawn at boot and written to the data directory, as production
+            // does by default: the setup tests read it back from there.
+            setup_token: None,
+            migration_backups: 3,
+            // The real defaults, so the whole test suite exercises the specs
+            // production runs under rather than a simplified stand-in.
+            pid: default_pid_specs(),
+        }
+    }
+}
diff --git a/src/config/from_env.rs b/src/config/from_env.rs
new file mode 100644
index 00000000..be238551
--- /dev/null
+++ b/src/config/from_env.rs
@@ -0,0 +1,392 @@
+//! `Config::from_env`: the process environment, read once and refused at boot
+//! when it is wrong.
+
+use std::{path::PathBuf, time::Duration};
+
+use super::access::{normalize_public_url, parse_proxy_addresses, parse_setup_token};
+use super::env::{parse_bool_env, parse_env, parse_positive_env, read_trimmed_env};
+use super::limits::{validate_canvas, validate_uploads};
+use super::metadata::{parse_lyrics_settings, parse_metadata_settings};
+use super::pid::{
+    parse_pid_spec, PidSpecKind, DEFAULT_PID_ALBUM, DEFAULT_PID_ARTIST, DEFAULT_PID_TRACK,
+};
+use super::podcasts::parse_podcast_settings;
+use super::scrobbling::parse_destinations;
+use super::{
+    CanvasLimits, Config, LastFmApplication, LibraryEventRetention, RemoteArtworkSettings,
+    ScrobbleLimits, UploadLimits, DEFAULT_SCROBBLE_MAX_ATTEMPTS,
+};
+
+impl Config {
+    pub fn from_env() -> anyhow::Result<Self> {
+        let data_dir = std::env::var_os("WAVEFLOW_DATA_DIR")
+            .map(PathBuf::from)
+            .unwrap_or_else(|| PathBuf::from("data"));
+
+        let bind_addr = parse_env("WAVEFLOW_BIND", "127.0.0.1:4533")?;
+        let public_url = std::env::var("WAVEFLOW_PUBLIC_URL")
+            .ok()
+            .filter(|value| !value.trim().is_empty())
+            .map(|value| normalize_public_url(&value))
+            .transpose()?;
+        let request_timeout_secs = parse_positive_env("WAVEFLOW_REQUEST_TIMEOUT_SECS", 30u64)?;
+        let db_max_connections = parse_positive_env("WAVEFLOW_DB_MAX_CONNECTIONS", 8u32)?;
+        let db_acquire_timeout_ms = parse_positive_env(
+            "WAVEFLOW_DB_ACQUIRE_TIMEOUT_MS",
+            DEFAULT_DB_ACQUIRE_TIMEOUT_MS,
+        )?;
+        let sqlite_busy_timeout_ms =
+            parse_positive_env("WAVEFLOW_SQLITE_BUSY_TIMEOUT_MS", 5_000u64)?;
+        let stream_ticket_ttl_secs =
+            parse_positive_env("WAVEFLOW_STREAM_TICKET_TTL_SECS", 60 * 60u64)?;
+        let access_token_ttl_secs =
+            parse_positive_env("WAVEFLOW_ACCESS_TOKEN_TTL_SECS", 15 * 60u64)?;
+        let refresh_token_ttl_secs =
+            parse_positive_env("WAVEFLOW_REFRESH_TOKEN_TTL_SECS", 30 * 24 * 60 * 60u64)?;
+        // Zero is a value here and not a refusal — "no expiry" is a choice an
+        // operator may make — so it is read like the scan interval rather than
+        // through `parse_positive_env`.
+        let api_token_ttl_secs = std::env::var("WAVEFLOW_API_TOKEN_TTL_SECS")
+            .unwrap_or_else(|_| "31536000".to_owned())
+            .parse::<u64>()
+            .map_err(|error| anyhow::anyhow!("invalid WAVEFLOW_API_TOKEN_TTL_SECS: {error}"))?;
+        let scan_interval_secs = std::env::var("WAVEFLOW_SCAN_INTERVAL_SECS")
+            .unwrap_or_else(|_| "21600".to_owned())
+            .parse::<u64>()
+            .map_err(|error| anyhow::anyhow!("invalid WAVEFLOW_SCAN_INTERVAL_SECS: {error}"))?;
+        let scan_parallelism = parse_positive_env(
+            "WAVEFLOW_SCAN_PARALLELISM",
+            std::thread::available_parallelism()
+                .map(usize::from)
+                .unwrap_or(4)
+                .clamp(1, 16),
+        )?;
+        let watch = parse_bool_env("WAVEFLOW_WATCH", true)?;
+        let watch_delay =
+            Duration::from_secs(parse_positive_env("WAVEFLOW_WATCH_DELAY_SECS", 10u64)?);
+        // Zero is a setting, the default one: never purge on its own.
+        let unavailable_retention_days = std::env::var("WAVEFLOW_UNAVAILABLE_RETENTION_DAYS")
+            .unwrap_or_else(|_| "0".to_owned())
+            .parse::<u64>()
+            .map_err(|error| {
+                anyhow::anyhow!("invalid WAVEFLOW_UNAVAILABLE_RETENTION_DAYS: {error}")
+            })?;
+        let unavailable_retention = (unavailable_retention_days > 0)
+            .then(|| Duration::from_secs(unavailable_retention_days.saturating_mul(24 * 60 * 60)));
+        // Zero is a setting too: no way back, as before.
+        let purge_grace_hours = std::env::var("WAVEFLOW_PURGE_GRACE_HOURS")
+            .unwrap_or_else(|_| "168".to_owned())
+            .parse::<u64>()
+            .map_err(|error| anyhow::anyhow!("invalid WAVEFLOW_PURGE_GRACE_HOURS: {error}"))?;
+        let purge_grace = Duration::from_secs(purge_grace_hours.saturating_mul(60 * 60));
+        let link_roots = parse_link_roots(std::env::var_os("WAVEFLOW_LINK_ROOTS"))?;
+        let subsonic_replay_gain = match std::env::var("WAVEFLOW_SUBSONIC_REPLAYGAIN") {
+            Err(_) => crate::replay_gain::ReplayGainMode::Off,
+            Ok(raw) if raw.trim().is_empty() => crate::replay_gain::ReplayGainMode::Off,
+            Ok(raw) => crate::replay_gain::ReplayGainMode::parse(&raw).ok_or_else(|| {
+                anyhow::anyhow!(
+                    "invalid WAVEFLOW_SUBSONIC_REPLAYGAIN: expected off, track or album, found {raw:?}"
+                )
+            })?,
+        };
+        let ffmpeg_path = std::env::var_os("WAVEFLOW_FFMPEG_PATH")
+            .map(PathBuf::from)
+            .unwrap_or_else(|| PathBuf::from("ffmpeg"));
+        let ffprobe_path = std::env::var_os("WAVEFLOW_FFPROBE_PATH")
+            .map(PathBuf::from)
+            .unwrap_or_else(|| PathBuf::from("ffprobe"));
+        let transcode_cache_max_bytes =
+            parse_positive_env("WAVEFLOW_TRANSCODE_CACHE_MAX_BYTES", 10_737_418_240u64)?;
+        let transcode_global_limit = parse_positive_env("WAVEFLOW_TRANSCODE_GLOBAL_LIMIT", 4usize)?;
+        let transcode_per_user_limit =
+            parse_positive_env("WAVEFLOW_TRANSCODE_PER_USER_LIMIT", 2usize)?;
+        // Zero is a setting here, not a mistake: it is how an operator turns the
+        // analysis off, so this is not `parse_positive_env`.
+        let quality_parallelism = std::env::var("WAVEFLOW_QUALITY_PARALLELISM")
+            .unwrap_or_else(|_| "1".to_owned())
+            .parse::<usize>()
+            .map_err(|error| anyhow::anyhow!("invalid WAVEFLOW_QUALITY_PARALLELISM: {error}"))?;
+        let uploads = UploadLimits {
+            max_file_bytes: parse_positive_env("WAVEFLOW_UPLOAD_MAX_FILE_BYTES", 1_073_741_824i64)?,
+            library_quota_bytes: parse_positive_env(
+                "WAVEFLOW_UPLOAD_LIBRARY_QUOTA_BYTES",
+                53_687_091_200i64,
+            )?,
+            chunk_bytes: parse_positive_env("WAVEFLOW_UPLOAD_CHUNK_BYTES", 4_194_304i64)?,
+            batch_limit: parse_positive_env("WAVEFLOW_UPLOAD_BATCH_LIMIT", 200usize)?,
+            sessions_per_user: parse_positive_env("WAVEFLOW_UPLOAD_SESSIONS_PER_USER", 4usize)?,
+            session_ttl: Duration::from_secs(parse_positive_env(
+                "WAVEFLOW_UPLOAD_SESSION_TTL_SECS",
+                86_400u64,
+            )?),
+        };
+        validate_uploads(&uploads)?;
+        let canvas = CanvasLimits {
+            // A Spotify-style loop is a few seconds of portrait video: a few
+            // hundred kilobytes in practice. Four megabytes is comfortably
+            // above anything that is still a loop, and low enough that the
+            // body ceiling derived from it stays a ceiling.
+            max_bytes: parse_positive_env("WAVEFLOW_CANVAS_MAX_BYTES", 4_194_304i64)?,
+            // Those loops run three to eight seconds. Fifteen leaves room for
+            // an unusual one without leaving room for an episode.
+            max_duration_secs: parse_positive_env("WAVEFLOW_CANVAS_MAX_DURATION_SECS", 15u32)?,
+            // A gigabyte is thousands of real canvases, and still a number an
+            // operator can reason about against a disk.
+            library_quota_bytes: parse_positive_env(
+                "WAVEFLOW_CANVAS_LIBRARY_QUOTA_BYTES",
+                1_073_741_824i64,
+            )?,
+        };
+        validate_canvas(&canvas)?;
+        let scrobbling = ScrobbleLimits {
+            // A minute is far below what any destination considers a listening
+            // history's resolution, and far above what a queue of a few rows
+            // costs to walk.
+            drain_interval: Duration::from_secs(parse_positive_env(
+                "WAVEFLOW_SCROBBLE_DRAIN_INTERVAL_SECS",
+                60u64,
+            )?),
+            max_attempts: parse_positive_env(
+                "WAVEFLOW_SCROBBLE_MAX_ATTEMPTS",
+                DEFAULT_SCROBBLE_MAX_ATTEMPTS,
+            )?,
+            stale_after: Duration::from_secs(parse_positive_env(
+                "WAVEFLOW_SCROBBLE_STALE_AFTER_SECS",
+                3_600u64,
+            )?),
+            batch: parse_positive_env("WAVEFLOW_SCROBBLE_BATCH", 50usize)?,
+            // Thirty days: long enough to explain a failure somebody noticed
+            // last week, short enough that the queue does not become a second
+            // listening history. A setting, not a carved number — whoever
+            // diagnoses a three-month outage lengthens it, exactly as they
+            // widen the library event window.
+            retention_days: parse_positive_env("WAVEFLOW_SCROBBLE_RETENTION_DAYS", 30u32)?,
+            // Thirty seconds is far past any of the three destinations'
+            // ordinary latency and far short of a drain that has stopped. It
+            // bounds one submission, never the pass: the pass is bounded by
+            // `batch`.
+            request_timeout: Duration::from_secs(parse_positive_env(
+                "WAVEFLOW_SCROBBLE_REQUEST_TIMEOUT_SECS",
+                30u64,
+            )?),
+        };
+        // Both refuse zero and negatives at startup rather than falling back:
+        // every fallback for a bound is wrong, and the operator is turned away
+        // where they can see why. No ceiling — an enormous value means "purge
+        // nothing", which is safe and legible.
+        let library_event_retention = LibraryEventRetention {
+            days: parse_positive_env("WAVEFLOW_LIBRARY_EVENT_RETENTION_DAYS", 30u32)?,
+            min_events: parse_positive_env("WAVEFLOW_LIBRARY_EVENT_RETENTION_MIN", 10_000i64)?,
+        };
+        if transcode_per_user_limit > transcode_global_limit {
+            anyhow::bail!(
+                "WAVEFLOW_TRANSCODE_PER_USER_LIMIT cannot exceed WAVEFLOW_TRANSCODE_GLOBAL_LIMIT"
+            );
+        }
+        // Refused here rather than at the first submission, for the same reason
+        // `WAVEFLOW_PUBLIC_URL` is: booting with scrobbling silently switched
+        // off because of a typo is the exact silent failure RFC-010 spends
+        // itself making visible. An operator who wants no adapter says so by
+        // setting this empty, which is a different thing from misspelling it.
+        let outbound_allow_plaintext = parse_bool_env("WAVEFLOW_SCROBBLE_ALLOW_PLAINTEXT", false)?;
+        let mut destinations = Vec::new();
+        for (provider, variable, default) in [
+            (
+                crate::services::ScrobbleProvider::ListenBrainz,
+                "WAVEFLOW_SCROBBLE_LISTENBRAINZ_URL",
+                "https://api.listenbrainz.org",
+            ),
+            (
+                crate::services::ScrobbleProvider::Maloja,
+                "WAVEFLOW_SCROBBLE_MALOJA_URL",
+                // No default: Maloja is self-hosted by nature, so there is no
+                // public instance to point at, and guessing one would be
+                // inventing a destination the operator never named.
+                "",
+            ),
+            (
+                crate::services::ScrobbleProvider::LastFm,
+                "WAVEFLOW_SCROBBLE_LASTFM_URL",
+                "https://ws.audioscrobbler.com",
+            ),
+        ] {
+            let configured = std::env::var(variable).unwrap_or_else(|_| default.to_owned());
+            destinations.extend(parse_destinations(
+                provider,
+                variable,
+                &configured,
+                outbound_allow_plaintext,
+            )?);
+        }
+
+        // Both or neither, and said at boot rather than discovered when
+        // somebody tries to link: half an application is a typo, and a server
+        // that started with Last.fm quietly switched off because of one is the
+        // silent failure this whole RFC spends itself making visible.
+        let lastfm = match (
+            read_trimmed_env("WAVEFLOW_SCROBBLE_LASTFM_API_KEY"),
+            read_trimmed_env("WAVEFLOW_SCROBBLE_LASTFM_SECRET"),
+        ) {
+            (None, None) => None,
+            (Some(api_key), Some(secret)) => Some(LastFmApplication { api_key, secret }),
+            (Some(_), None) => anyhow::bail!(
+                "WAVEFLOW_SCROBBLE_LASTFM_API_KEY is set without WAVEFLOW_SCROBBLE_LASTFM_SECRET"
+            ),
+            (None, Some(_)) => anyhow::bail!(
+                "WAVEFLOW_SCROBBLE_LASTFM_SECRET is set without WAVEFLOW_SCROBBLE_LASTFM_API_KEY"
+            ),
+        };
+
+        let metadata = parse_metadata_settings()?;
+        let lyrics = parse_lyrics_settings()?;
+        let podcasts = parse_podcast_settings(&data_dir)?;
+        let remote_artwork = RemoteArtworkSettings {
+            enabled: parse_bool_env("WAVEFLOW_REMOTE_ARTWORK", true)?,
+            timeout: Duration::from_secs(20),
+            addresses: crate::portrait::AddressPolicy::Public,
+        };
+        // Absent is empty; a value that is not UTF-8 refuses to boot, rather
+        // than starting with no trusted proxy and counting every client behind
+        // it under the proxy's address.
+        let trusted_proxies = match std::env::var("WAVEFLOW_TRUSTED_PROXIES") {
+            Ok(list) => parse_proxy_addresses(&list)?,
+            Err(std::env::VarError::NotPresent) => Vec::new(),
+            Err(std::env::VarError::NotUnicode(_)) => {
+                anyhow::bail!("WAVEFLOW_TRUSTED_PROXIES is not valid UTF-8")
+            }
+        };
+
+        let setup_token = parse_setup_token(read_trimmed_env("WAVEFLOW_SETUP_TOKEN"))?;
+        // Zero is a setting, not a mistake: an operator with backups of their
+        // own turns the copies off with it.
+        let migration_backups = std::env::var("WAVEFLOW_MIGRATION_BACKUPS")
+            .unwrap_or_else(|_| "3".to_owned())
+            .parse::<usize>()
+            .map_err(|error| anyhow::anyhow!("invalid WAVEFLOW_MIGRATION_BACKUPS: {error}"))?;
+
+        let allowed_origins = std::env::var("WAVEFLOW_ALLOWED_ORIGINS")
+            .unwrap_or_default()
+            .split(',')
+            .map(str::trim)
+            .filter(|origin| !origin.is_empty())
+            .map(|origin| {
+                origin.parse::<axum::http::HeaderValue>().map_err(|error| {
+                    anyhow::anyhow!("invalid WAVEFLOW_ALLOWED_ORIGINS entry {origin:?}: {error}")
+                })
+            })
+            .collect::<anyhow::Result<Vec<_>>>()?;
+
+        // Parsed here rather than at first use: a spec that cannot be parsed —
+        // a recursive `albumid` above all — would otherwise re-identify the
+        // whole catalogue silently at the next scan. Refusing to boot says so.
+        let pid = crate::pid::PidSpecs {
+            album: parse_pid_spec(
+                "WAVEFLOW_PID_ALBUM",
+                DEFAULT_PID_ALBUM,
+                PidSpecKind::MayNotReferenceAlbumId,
+            )?,
+            track: parse_pid_spec(
+                "WAVEFLOW_PID_TRACK",
+                DEFAULT_PID_TRACK,
+                PidSpecKind::MayReferenceAlbumId,
+            )?,
+            artist: parse_pid_spec(
+                "WAVEFLOW_PID_ARTIST",
+                DEFAULT_PID_ARTIST,
+                PidSpecKind::MayNotReferenceAlbumId,
+            )?,
+        };
+
+        if refresh_token_ttl_secs <= access_token_ttl_secs {
+            anyhow::bail!(
+                "WAVEFLOW_REFRESH_TOKEN_TTL_SECS must be greater than WAVEFLOW_ACCESS_TOKEN_TTL_SECS"
+            );
+        }
+        let transcode_cache_dir = data_dir.join("transcode-cache");
+        let canvas_dir = data_dir.join("canvas");
+
+        Ok(Self {
+            bind_addr,
+            public_url,
+            request_timeout: Duration::from_secs(request_timeout_secs),
+            database_path: data_dir.join("waveflow.db"),
+            instance_key_path: data_dir.join("instance.key"),
+            artwork_dir: data_dir.join("artwork"),
+            data_dir,
+            db_max_connections,
+            db_acquire_timeout: Duration::from_millis(db_acquire_timeout_ms),
+            sqlite_busy_timeout: Duration::from_millis(sqlite_busy_timeout_ms),
+            access_token_ttl: Duration::from_secs(access_token_ttl_secs),
+            stream_ticket_ttl: Duration::from_secs(stream_ticket_ttl_secs),
+            refresh_token_ttl: Duration::from_secs(refresh_token_ttl_secs),
+            api_token_ttl: (api_token_ttl_secs > 0)
+                .then(|| Duration::from_secs(api_token_ttl_secs)),
+            scan_interval: (scan_interval_secs > 0)
+                .then(|| Duration::from_secs(scan_interval_secs)),
+            scan_parallelism,
+            watch,
+            watch_delay,
+            unavailable_retention,
+            purge_grace,
+            link_roots,
+            subsonic_replay_gain,
+            ffmpeg_path,
+            ffprobe_path,
+            transcode_cache_dir,
+            transcode_cache_max_bytes,
+            transcode_global_limit,
+            transcode_per_user_limit,
+            quality_parallelism,
+            uploads,
+            library_event_retention,
+            canvas_dir,
+            canvas,
+            scrobbling,
+            destinations,
+            lastfm,
+            outbound_allow_plaintext,
+            metadata,
+            lyrics,
+            podcasts,
+            remote_artwork,
+            allowed_origins,
+            trusted_proxies,
+            setup_token,
+            migration_backups,
+            pid,
+        })
+    }
+}
+
+/// `WAVEFLOW_LINK_ROOTS`: absolute folders, separated as `PATH` is.
+///
+/// Absolute because a relative one would be read against whatever directory
+/// the server happens to start in, which is not a decision about the file
+/// system an operator means to make. Not canonicalised here: a root on a
+/// mount that is not there yet must not stop the boot, so the scan resolves
+/// each one when it runs and skips one it cannot.
+fn parse_link_roots(raw: Option<std::ffi::OsString>) -> anyhow::Result<Vec<PathBuf>> {
+    let Some(raw) = raw else {
+        return Ok(Vec::new());
+    };
+    let mut roots = Vec::new();
+    for root in std::env::split_paths(&raw) {
+        if root.as_os_str().is_empty() {
+            continue;
+        }
+        if !root.is_absolute() {
+            anyhow::bail!(
+                "invalid WAVEFLOW_LINK_ROOTS: {} is not an absolute path",
+                root.display()
+            );
+        }
+        roots.push(root);
+    }
+    Ok(roots)
+}
+
+/// The acquire budget a deployment gets unless it says otherwise.
+///
+/// Named so the test fixture's longer budget can be compared against it
+/// instead of against a second copy of the number.
+pub(super) const DEFAULT_DB_ACQUIRE_TIMEOUT_MS: u64 = 5_000;
diff --git a/src/config/limits.rs b/src/config/limits.rs
new file mode 100644
index 00000000..50decd39
--- /dev/null
+++ b/src/config/limits.rs
@@ -0,0 +1,111 @@
+//! The bounds on what the server keeps on its own disk: files received, loops
+//! attached, and how much of a library's change feed survives.
+
+use std::time::Duration;
+
+/// What the server accepts from a client that offers it a file.
+///
+/// Every one of these is a bound on someone else's disk, which is why they sit
+/// together rather than scattered among the tunables: receiving a file is the
+/// only thing the server does that cannot be undone by restarting it.
+#[derive(Debug, Clone, Copy)]
+pub struct UploadLimits {
+    /// The largest single file the server will take.
+    pub max_file_bytes: i64,
+    /// How much of a library's disk received files may occupy in total, open
+    /// sessions included — a session reserves what it declared, or two
+    /// negotiations racing would each be told there was room for both.
+    pub library_quota_bytes: i64,
+    /// The size a client should send each fragment at. Advertised by the
+    /// negotiation rather than assumed, so it can move without a client
+    /// release.
+    pub chunk_bytes: i64,
+    /// How many offers one negotiation may carry. Bounded because the batch is
+    /// the answer to five thousand round trips, and an unbounded array would
+    /// trade them for one unbounded body.
+    pub batch_limit: usize,
+    /// How many sessions one account may hold open at once, across libraries —
+    /// the same shape as the per-user transcode limit, and for the same reason:
+    /// a client with five thousand files must not open five thousand of
+    /// anything.
+    pub sessions_per_user: usize,
+    /// How long an untouched session survives. Generous, because a large file
+    /// on a domestic link is measured in hours, not minutes.
+    pub session_ttl: Duration,
+}
+
+/// How long a library's change feed keeps what it has written.
+///
+/// The floor wins over the age: a library below it keeps everything, however
+/// old. RFC-007 decision 7.
+#[derive(Debug, Clone, Copy)]
+pub struct LibraryEventRetention {
+    /// Whole days. Only what is **strictly** older is cut, so an event exactly
+    /// this old survives — the same exclusive bound `stream_ticket::verify`
+    /// uses, and the cautious direction: keeping one event too many breaks
+    /// nobody, cutting one too many sends somebody back to the snapshot.
+    pub days: u32,
+    /// The fewest events a library keeps whatever their age.
+    pub min_events: i64,
+}
+
+/// What the server accepts when a member attaches a loop to a track.
+///
+/// Apart from [`UploadLimits`] rather than folded into it: the two magazines
+/// can live on different disks, and mixing the quotas would let loops starve
+/// the space the upload quota exists to protect — the music.
+#[derive(Debug, Clone, Copy)]
+pub struct CanvasLimits {
+    /// The largest canvas the server will take. The route derives its own body
+    /// ceiling from this, so it is also the largest body that route accepts.
+    pub max_bytes: i64,
+    /// How long a loop may run. Not prudence: without it, "a short loop"
+    /// becomes video hosting, which is a different product with different
+    /// costs.
+    pub max_duration_secs: u32,
+    /// How much of a library's disk canvases may occupy. Counted in distinct
+    /// blobs a library references, never in links, so an album's shared loop is
+    /// billed once however many tracks name it.
+    pub library_quota_bytes: i64,
+}
+
+/// The upload limits that only make sense against each other.
+///
+/// Apart here rather than inline so the rules can be exercised without
+/// rewriting the process environment, which is global and shared by every test
+/// running beside it.
+pub(super) fn validate_uploads(uploads: &UploadLimits) -> anyhow::Result<()> {
+    if uploads.max_file_bytes > uploads.library_quota_bytes {
+        anyhow::bail!(
+            "WAVEFLOW_UPLOAD_MAX_FILE_BYTES cannot exceed WAVEFLOW_UPLOAD_LIBRARY_QUOTA_BYTES"
+        );
+    }
+    // The fragment route turns this into a body ceiling, and a value it cannot
+    // represent would have to fall back to something. Every fallback for a
+    // ceiling is wrong — too small breaks the configured size, too large is no
+    // ceiling at all — so it is refused here, where the operator can see why.
+    if usize::try_from(uploads.chunk_bytes).is_err() {
+        anyhow::bail!("invalid WAVEFLOW_UPLOAD_CHUNK_BYTES: too large for this platform");
+    }
+    if uploads.chunk_bytes > uploads.max_file_bytes {
+        anyhow::bail!("WAVEFLOW_UPLOAD_CHUNK_BYTES cannot exceed WAVEFLOW_UPLOAD_MAX_FILE_BYTES");
+    }
+    Ok(())
+}
+
+/// The canvas limits that only make sense against each other.
+pub(super) fn validate_canvas(canvas: &CanvasLimits) -> anyhow::Result<()> {
+    if canvas.max_bytes > canvas.library_quota_bytes {
+        anyhow::bail!(
+            "WAVEFLOW_CANVAS_MAX_BYTES cannot exceed WAVEFLOW_CANVAS_LIBRARY_QUOTA_BYTES"
+        );
+    }
+    // The route turns this into a body ceiling, and a value it cannot represent
+    // would have to fall back to something. Every fallback for a ceiling is
+    // wrong, so it is refused here where the operator can see why — the same
+    // rule the upload chunk size follows.
+    if usize::try_from(canvas.max_bytes).is_err() {
+        anyhow::bail!("invalid WAVEFLOW_CANVAS_MAX_BYTES: too large for this platform");
+    }
+    Ok(())
+}
diff --git a/src/config/metadata.rs b/src/config/metadata.rs
new file mode 100644
index 00000000..ef3638fd
--- /dev/null
+++ b/src/config/metadata.rs
@@ -0,0 +1,235 @@
+//! Outbound lookups about the catalogue, each off until the operator names a
+//! provider: artist enrichment (RFC-011) and lyrics (RFC-024).
+
+use std::time::Duration;
+
+use super::env::{parse_bool_env, parse_positive_env, read_trimmed_env};
+
+/// Metadata enrichment, as RFC-011 decision 3 lists its settings.
+///
+/// **Off unless `providers` names one**, and that is the only switch: an empty
+/// list makes no outbound request of any kind, and nothing else here can
+/// contradict it. Separate from scrobbling on purpose — an operator who placed
+/// a Last.fm application for submissions has not thereby agreed to lookups
+/// about the whole catalogue, so `lastfm_key` is its own setting even when it
+/// holds the same value.
+#[derive(Clone)]
+pub struct MetadataSettings {
+    /// `WAVEFLOW_METADATA_PROVIDERS`: an ordered, comma-separated list, empty
+    /// by default, of `lastfm`, `deezer` and `theaudiodb`. The order is the
+    /// order fields are merged in when read.
+    pub providers: Vec<crate::enrichment::Provider>,
+    /// `WAVEFLOW_METADATA_IMAGES`, on by default, `off` to keep the lookups and
+    /// refuse decision 8's image fetch. A narrowing only: it switches nothing
+    /// on while `providers` is empty.
+    pub images: bool,
+    /// `WAVEFLOW_METADATA_LASTFM_KEY`, the operator's own application key.
+    /// Required when `providers` names `lastfm`: no key ships in this binary.
+    pub lastfm_key: Option<String>,
+    /// `WAVEFLOW_METADATA_THEAUDIODB_KEY`, the operator's own TheAudioDB key.
+    /// Required when `providers` names `theaudiodb` (RFC-014 decision 1): the
+    /// public test key `waveflow-core` uses for one desktop user is not one a
+    /// server may share with everyone else's.
+    pub theaudiodb_key: Option<String>,
+    /// `WAVEFLOW_METADATA_TTL_DAYS`: how long an answer with content stands.
+    pub ttl: Duration,
+    /// `WAVEFLOW_METADATA_MISS_TTL_DAYS`: how long "the provider knows nothing"
+    /// stands. Shorter than `ttl`, and a setting of its own, because it is the
+    /// answer most likely to change.
+    pub miss_ttl: Duration,
+    /// `WAVEFLOW_METADATA_RATE_PER_SEC`: requests per second, per provider.
+    pub rate_per_sec: u32,
+    /// `WAVEFLOW_METADATA_REQUEST_TIMEOUT_SECS`: how long one request to a
+    /// provider may take before it counts as unreached.
+    pub request_timeout: Duration,
+}
+
+impl MetadataSettings {
+    /// Enrichment switched off — what a server that is merely upgraded runs.
+    pub fn off() -> Self {
+        Self {
+            providers: Vec::new(),
+            images: true,
+            lastfm_key: None,
+            theaudiodb_key: None,
+            ttl: Duration::from_secs(30 * 24 * 60 * 60),
+            miss_ttl: Duration::from_secs(7 * 24 * 60 * 60),
+            rate_per_sec: 4,
+            request_timeout: Duration::from_secs(10),
+        }
+    }
+}
+
+/// Written by hand so the key never reaches a log: a `Config` is printed at
+/// startup under `RUST_LOG=debug`, and a Last.fm key travels in a query string
+/// where anyone holding it can spend the operator's quota.
+impl std::fmt::Debug for MetadataSettings {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("MetadataSettings")
+            .field("providers", &self.providers)
+            .field("images", &self.images)
+            .field(
+                "lastfm_key",
+                &self.lastfm_key.as_ref().map(|_| "[redacted]"),
+            )
+            .field(
+                "theaudiodb_key",
+                &self.theaudiodb_key.as_ref().map(|_| "[redacted]"),
+            )
+            .field("ttl", &self.ttl)
+            .field("miss_ttl", &self.miss_ttl)
+            .field("rate_per_sec", &self.rate_per_sec)
+            .field("request_timeout", &self.request_timeout)
+            .finish()
+    }
+}
+
+/// Lyrics looked up on LRCLIB, as RFC-024 decision 1 lists its settings.
+///
+/// **Off unless `providers` names one**, and that is the only switch, exactly
+/// as for [`MetadataSettings`]. A separate list rather than a value of
+/// `WAVEFLOW_METADATA_PROVIDERS`, because a lyrics lookup sends a track title,
+/// its album and its duration at the moment somebody plays it, which is a
+/// different consent from asking about an artist's name.
+#[derive(Debug, Clone)]
+pub struct LyricsSettings {
+    /// `WAVEFLOW_LYRICS_PROVIDERS`: empty by default, or `lrclib`.
+    pub providers: Vec<crate::lrclib::LyricsProvider>,
+    /// `WAVEFLOW_LYRICS_TTL_DAYS`: how long lyrics found are kept.
+    pub ttl: Duration,
+    /// `WAVEFLOW_LYRICS_MISS_TTL_DAYS`: how long "nothing for this track" is
+    /// kept.
+    pub miss_ttl: Duration,
+    /// `WAVEFLOW_LYRICS_RATE_PER_SEC`: requests per second.
+    pub rate_per_sec: u32,
+    /// `WAVEFLOW_LYRICS_REQUEST_TIMEOUT_SECS`: how long one request may take
+    /// before it counts as unanswered.
+    pub request_timeout: Duration,
+}
+
+impl LyricsSettings {
+    /// Lookups switched off — what a server that is merely upgraded runs.
+    pub fn off() -> Self {
+        Self {
+            providers: Vec::new(),
+            ttl: Duration::from_secs(30 * 24 * 60 * 60),
+            miss_ttl: Duration::from_secs(7 * 24 * 60 * 60),
+            rate_per_sec: 2,
+            request_timeout: Duration::from_secs(10),
+        }
+    }
+}
+
+/// Reads RFC-011 decision 3's settings.
+pub(super) fn parse_metadata_settings() -> anyhow::Result<MetadataSettings> {
+    let defaults = MetadataSettings::off();
+    let lastfm_key = read_trimmed_env("WAVEFLOW_METADATA_LASTFM_KEY");
+    let theaudiodb_key = read_trimmed_env("WAVEFLOW_METADATA_THEAUDIODB_KEY");
+    let providers = parse_metadata_providers(
+        &std::env::var("WAVEFLOW_METADATA_PROVIDERS").unwrap_or_default(),
+        lastfm_key.is_some(),
+        theaudiodb_key.is_some(),
+    )?;
+    let days = |name: &str, default: Duration| -> anyhow::Result<Duration> {
+        let days: u64 = parse_positive_env(name, default.as_secs() / (24 * 60 * 60))?;
+        days.checked_mul(24 * 60 * 60)
+            .map(Duration::from_secs)
+            .ok_or_else(|| anyhow::anyhow!("invalid {name}: too large"))
+    };
+    Ok(MetadataSettings {
+        providers,
+        images: parse_bool_env("WAVEFLOW_METADATA_IMAGES", defaults.images)?,
+        lastfm_key,
+        theaudiodb_key,
+        ttl: days("WAVEFLOW_METADATA_TTL_DAYS", defaults.ttl)?,
+        miss_ttl: days("WAVEFLOW_METADATA_MISS_TTL_DAYS", defaults.miss_ttl)?,
+        rate_per_sec: parse_positive_env("WAVEFLOW_METADATA_RATE_PER_SEC", defaults.rate_per_sec)?,
+        request_timeout: Duration::from_secs(parse_positive_env(
+            "WAVEFLOW_METADATA_REQUEST_TIMEOUT_SECS",
+            defaults.request_timeout.as_secs(),
+        )?),
+    })
+}
+
+/// Reads RFC-024 decision 1's settings.
+pub(super) fn parse_lyrics_settings() -> anyhow::Result<LyricsSettings> {
+    let defaults = LyricsSettings::off();
+    let providers =
+        parse_lyrics_providers(&std::env::var("WAVEFLOW_LYRICS_PROVIDERS").unwrap_or_default())?;
+    let days = |name: &str, default: Duration| -> anyhow::Result<Duration> {
+        let days: u64 = parse_positive_env(name, default.as_secs() / (24 * 60 * 60))?;
+        days.checked_mul(24 * 60 * 60)
+            .map(Duration::from_secs)
+            .ok_or_else(|| anyhow::anyhow!("invalid {name}: too large"))
+    };
+    Ok(LyricsSettings {
+        providers,
+        ttl: days("WAVEFLOW_LYRICS_TTL_DAYS", defaults.ttl)?,
+        miss_ttl: days("WAVEFLOW_LYRICS_MISS_TTL_DAYS", defaults.miss_ttl)?,
+        rate_per_sec: parse_positive_env("WAVEFLOW_LYRICS_RATE_PER_SEC", defaults.rate_per_sec)?,
+        request_timeout: Duration::from_secs(parse_positive_env(
+            "WAVEFLOW_LYRICS_REQUEST_TIMEOUT_SECS",
+            defaults.request_timeout.as_secs(),
+        )?),
+    })
+}
+
+/// `WAVEFLOW_LYRICS_PROVIDERS`. An unknown name and a name given twice refuse
+/// to boot, for the reason [`parse_metadata_providers`] gives.
+pub(super) fn parse_lyrics_providers(
+    list: &str,
+) -> anyhow::Result<Vec<crate::lrclib::LyricsProvider>> {
+    let mut providers = Vec::new();
+    for name in list
+        .split(',')
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+    {
+        let provider = crate::lrclib::LyricsProvider::parse(name)
+            .ok_or_else(|| anyhow::anyhow!("invalid WAVEFLOW_LYRICS_PROVIDERS entry {name:?}"))?;
+        if providers.contains(&provider) {
+            anyhow::bail!("WAVEFLOW_LYRICS_PROVIDERS names {name:?} twice");
+        }
+        providers.push(provider);
+    }
+    Ok(providers)
+}
+
+/// `WAVEFLOW_METADATA_PROVIDERS`, in the operator's order.
+///
+/// A provider named without its key, an unknown name and a name given twice
+/// all refuse to boot. Each is a typo, and a server that started with
+/// enrichment quietly narrower than its operator wrote is the silent failure
+/// these settings must not have — the operator learns it here, not from an
+/// artist page that never fills.
+pub(super) fn parse_metadata_providers(
+    list: &str,
+    has_lastfm_key: bool,
+    has_theaudiodb_key: bool,
+) -> anyhow::Result<Vec<crate::enrichment::Provider>> {
+    let mut providers = Vec::new();
+    for name in list
+        .split(',')
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+    {
+        let provider = crate::enrichment::Provider::parse(name)
+            .ok_or_else(|| anyhow::anyhow!("invalid WAVEFLOW_METADATA_PROVIDERS entry {name:?}"))?;
+        if providers.contains(&provider) {
+            anyhow::bail!("WAVEFLOW_METADATA_PROVIDERS names {name:?} twice");
+        }
+        if provider == crate::enrichment::Provider::LastFm && !has_lastfm_key {
+            anyhow::bail!(
+                "WAVEFLOW_METADATA_PROVIDERS names lastfm without WAVEFLOW_METADATA_LASTFM_KEY"
+            );
+        }
+        if provider == crate::enrichment::Provider::TheAudioDb && !has_theaudiodb_key {
+            anyhow::bail!(
+                "WAVEFLOW_METADATA_PROVIDERS names theaudiodb without WAVEFLOW_METADATA_THEAUDIODB_KEY"
+            );
+        }
+        providers.push(provider);
+    }
+    Ok(providers)
+}
diff --git a/src/config/mod.rs b/src/config/mod.rs
index 07dd7387..28d2606a 100644
--- a/src/config/mod.rs
+++ b/src/config/mod.rs
@@ -3,370 +3,26 @@
 //! Environment access is centralised here so domain and repository code stay
 //! deterministic and testable.
 
-use std::{net::SocketAddr, path::PathBuf, time::Duration};
-
-/// What the server accepts from a client that offers it a file.
-///
-/// Every one of these is a bound on someone else's disk, which is why they sit
-/// together rather than scattered among the tunables: receiving a file is the
-/// only thing the server does that cannot be undone by restarting it.
-#[derive(Debug, Clone, Copy)]
-pub struct UploadLimits {
-    /// The largest single file the server will take.
-    pub max_file_bytes: i64,
-    /// How much of a library's disk received files may occupy in total, open
-    /// sessions included — a session reserves what it declared, or two
-    /// negotiations racing would each be told there was room for both.
-    pub library_quota_bytes: i64,
-    /// The size a client should send each fragment at. Advertised by the
-    /// negotiation rather than assumed, so it can move without a client
-    /// release.
-    pub chunk_bytes: i64,
-    /// How many offers one negotiation may carry. Bounded because the batch is
-    /// the answer to five thousand round trips, and an unbounded array would
-    /// trade them for one unbounded body.
-    pub batch_limit: usize,
-    /// How many sessions one account may hold open at once, across libraries —
-    /// the same shape as the per-user transcode limit, and for the same reason:
-    /// a client with five thousand files must not open five thousand of
-    /// anything.
-    pub sessions_per_user: usize,
-    /// How long an untouched session survives. Generous, because a large file
-    /// on a domestic link is measured in hours, not minutes.
-    pub session_ttl: Duration,
-}
-
-/// How long a library's change feed keeps what it has written.
-///
-/// The floor wins over the age: a library below it keeps everything, however
-/// old. RFC-007 decision 7.
-#[derive(Debug, Clone, Copy)]
-pub struct LibraryEventRetention {
-    /// Whole days. Only what is **strictly** older is cut, so an event exactly
-    /// this old survives — the same exclusive bound `stream_ticket::verify`
-    /// uses, and the cautious direction: keeping one event too many breaks
-    /// nobody, cutting one too many sends somebody back to the snapshot.
-    pub days: u32,
-    /// The fewest events a library keeps whatever their age.
-    pub min_events: i64,
-}
-
-/// Podcasts (RFC-025 decisions 7 to 12).
-///
-/// **Off by default, and an upgrade leaves it off**: subscribing to a feed is
-/// outbound traffic to a host a person typed, and nothing of the kind happens
-/// until an operator says so. With the switch off, no feed is fetched, no
-/// episode is downloaded, and `podcastRole` is false for everyone; what was
-/// stored while it was on stays readable, and a downloaded episode stays
-/// playable from disk.
-#[derive(Debug, Clone)]
-pub struct PodcastSettings {
-    /// `WAVEFLOW_PODCASTS`, off by default.
-    pub enabled: bool,
-    /// `WAVEFLOW_PODCAST_REFRESH_INTERVAL_SECS`: how often every channel is
-    /// fetched again, six hours by default; `0` for never on its own — a
-    /// refresh then happens only when somebody asks for one.
-    pub refresh_interval: Option<Duration>,
-    /// `WAVEFLOW_PODCAST_ALLOW_HTTP`: whether a feed or an enclosure may be
-    /// plain http. On by default, because a good share of podcast enclosures
-    /// are still served that way and a feed is public content; the address
-    /// rules apply either way.
-    pub allow_http: bool,
-    /// `WAVEFLOW_PODCAST_MAX_FEED_BYTES`: the largest feed read, 16 MiB.
-    pub max_feed_bytes: usize,
-    /// `WAVEFLOW_PODCAST_MAX_EPISODE_BYTES`: the largest episode stored,
-    /// 1 GiB.
-    pub max_episode_bytes: u64,
-    /// `WAVEFLOW_PODCAST_QUOTA_BYTES`: how much the downloaded episodes may
-    /// occupy together, 20 GiB.
-    pub quota_bytes: u64,
-    /// `WAVEFLOW_PODCAST_FEED_TIMEOUT_SECS`: one feed fetch, redirects
-    /// included, 20 seconds.
-    pub feed_timeout: Duration,
-    /// `WAVEFLOW_PODCAST_DOWNLOAD_TIMEOUT_SECS`: one episode download, 30
-    /// minutes.
-    pub download_timeout: Duration,
-    /// Where episodes are stored: `<data dir>/podcasts`, derived and not set.
-    pub dir: PathBuf,
-    /// Which addresses a fetch may reach. Public ones in production, always;
-    /// not an environment variable. The test suite's feeds live on loopback,
-    /// and its fixture admits loopback for them alone.
-    pub addresses: crate::portrait::AddressPolicy,
-}
-
-/// Remote artwork: the cover a podcast feed names, and the image an account
-/// gives a radio station (RFC-025, amended).
-///
-/// **On by default**, unlike podcasts, because nothing here happens on its own:
-/// a station image is fetched once when an account sets or changes one, and a
-/// podcast cover only while `WAVEFLOW_PODCASTS` is on and a channel is
-/// subscribed or refreshed. Off, an address is still stored and nothing is
-/// fetched; covers already stored stay shown.
-#[derive(Debug, Clone, Copy)]
-pub struct RemoteArtworkSettings {
-    /// `WAVEFLOW_REMOTE_ARTWORK`, on by default.
-    pub enabled: bool,
-    /// One image fetch, redirects included. Derived, not set: the figure the
-    /// feed fetch defaults to, for a body the size of a cover.
-    pub timeout: Duration,
-    /// Which addresses a fetch may reach, as for podcasts: public ones in
-    /// production, always, and loopback as well for the test suite's hosts.
-    pub addresses: crate::portrait::AddressPolicy,
-}
-
-/// What the server accepts when a member attaches a loop to a track.
-///
-/// Apart from [`UploadLimits`] rather than folded into it: the two magazines
-/// can live on different disks, and mixing the quotas would let loops starve
-/// the space the upload quota exists to protect — the music.
-#[derive(Debug, Clone, Copy)]
-pub struct CanvasLimits {
-    /// The largest canvas the server will take. The route derives its own body
-    /// ceiling from this, so it is also the largest body that route accepts.
-    pub max_bytes: i64,
-    /// How long a loop may run. Not prudence: without it, "a short loop"
-    /// becomes video hosting, which is a different product with different
-    /// costs.
-    pub max_duration_secs: u32,
-    /// How much of a library's disk canvases may occupy. Counted in distinct
-    /// blobs a library references, never in links, so an album's shared loop is
-    /// billed once however many tracks name it.
-    pub library_quota_bytes: i64,
-}
-
-/// How the server drains what it owes a third party. RFC-010.
-///
-/// Apart from the credentials, which belong to an account and are posed through
-/// the API — decision 9. What is left here is what belongs to the deployment:
-/// how often the queue moves, how many times a failure is worth repeating, and
-/// how long a queue may sit still before the operator should be told it has
-/// stopped.
-#[derive(Debug, Clone, Copy)]
-pub struct ScrobbleLimits {
-    /// How often the drain walks the queue.
-    pub drain_interval: Duration,
-    /// How long one submission may take before the drain stops waiting for it.
-    ///
-    /// A deployment setting rather than a constant because decision 9 says so,
-    /// and it is load-bearing: the drain is a background task, so a destination
-    /// that accepts a connection and then never answers would hold the queue
-    /// still for the life of the process — the silent failure `degraded` exists
-    /// to surface, arriving by the one route that would also stop `degraded`
-    /// from ever being computed.
-    pub request_timeout: Duration,
-    /// How many times one listen may be submitted before it is abandoned and
-    /// counted. Bounded because a queue that never empties is a fault and not a
-    /// state — decision 6.
-    pub max_attempts: u32,
-    /// How long the oldest waiting listen may be waiting before the link is
-    /// reported `degraded`. A valid token with a queue that has not moved for
-    /// hours is the silent failure a durable queue exists to make visible —
-    /// decision 12.
-    pub stale_after: Duration,
-    /// How many listens one drain pass takes. It bounds the pass, never the
-    /// request: decision 11 sends one listen per request whatever this says.
-    pub batch: usize,
-    /// How long a finished entry stays readable before the purge takes it.
-    ///
-    /// `sent`, `rejected`, `abandoned`, `cancelled` and `discarded` only.
-    /// `uncertain` is kept for as long as nobody has answered it, whatever this
-    /// says: taking away an entry that is still asking a person would be
-    /// deciding in their place, which is the one thing decision 13 refuses.
-    ///
-    /// No floor, unlike the library event feed. There, cutting the head off a
-    /// quiet library sends a device back to the snapshot; here nobody resumes a
-    /// cursor, and what a link publishes is read from `pending` and `uncertain`
-    /// rows that no purge touches.
-    pub retention_days: u32,
-}
-
-/// How many times a listen is offered before the queue gives up on it.
-///
-/// Thirty, because the waits grow to an hour and stop there: six doublings from
-/// a minute, then an hour apiece. Thirty submissions therefore span a little
-/// over **a day** of a destination being down, which is the span worth
-/// surviving — a nightly maintenance window, a regional outage, a certificate
-/// nobody renewed until morning.
-///
-/// It was eight, with a comment claiming the same day; eight delivers two hours
-/// and three minutes. The comment was the honest statement of what this is for,
-/// so the number moved to meet it rather than the sentence being trimmed to fit.
-/// Giving up early buys nothing here: abandoning a listen is a permanent hole in
-/// someone's history, and unlike a retry after an ambiguous answer it risks no
-/// duplicate at all. `the_default_attempt_cap_carries_a_listen_across_a_day_of_outage`
-/// keeps this paragraph and the arithmetic from drifting apart again.
-pub const DEFAULT_SCROBBLE_MAX_ATTEMPTS: u32 = 30;
-
-/// The name an instance takes when the operator declared only an address.
-///
-/// It is written into the link like any other name, so the shorthand and the
-/// long form produce the same rows: `WAVEFLOW_SCROBBLE_MALOJA_URL=https://…`
-/// and `…=default=https://…` are one configuration, and an operator who later
-/// adds a second instance does not invalidate the links the first one holds.
-pub const DEFAULT_SCROBBLE_DESTINATION: &str = "default";
-
-/// The Last.fm application an operator registered for this server.
-///
-/// `WAVEFLOW_SCROBBLE_LASTFM_API_KEY` and `WAVEFLOW_SCROBBLE_LASTFM_SECRET`,
-/// both or neither. Without them Last.fm is simply unavailable: RFC-010
-/// decision 4 forbids shipping any provider credential in an AGPL binary, so
-/// these belong to the deployment and to nobody else.
-///
-/// The operator also registers, at Last.fm, the callback URL their
-/// `WAVEFLOW_PUBLIC_URL` produces. Their documentation does not say whether the
-/// `cb` parameter is checked against the registered domain, and betting on a
-/// tolerance nobody promised is not a deployment step — nothing on this side
-/// can verify it either way.
-#[derive(Clone)]
-pub struct LastFmApplication {
-    pub api_key: String,
-    /// Signs every call. Written by hand below rather than derived, because a
-    /// `Config` is printed at startup under `RUST_LOG=debug` and this field is
-    /// the one thing in it that must never appear there.
-    pub secret: String,
-}
-
-impl std::fmt::Debug for LastFmApplication {
-    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        formatter
-            .debug_struct("LastFmApplication")
-            .field("api_key", &self.api_key)
-            .field("secret", &"[redacted]")
-            .finish()
-    }
-}
-
-/// One instance of one destination, as the operator declared it.
-#[derive(Debug, Clone)]
-pub struct ScrobbleDestination {
-    pub provider: crate::services::ScrobbleProvider,
-    /// What a member names in a path. Validated against the path alphabet at
-    /// boot — see `scrobblers::validate_destination_name`.
-    pub name: String,
-    /// Where it lives. Validated by `scrobblers::validate_destination`, so it
-    /// carries no credentials, no query and no fragment.
-    pub url: url::Url,
-    /// What a link keeps so it can tell this is still the same machine, even
-    /// when the name has not changed. See
-    /// `scrobblers::destination_fingerprint`.
-    pub fingerprint: String,
-}
-
-/// Metadata enrichment, as RFC-011 decision 3 lists its settings.
-///
-/// **Off unless `providers` names one**, and that is the only switch: an empty
-/// list makes no outbound request of any kind, and nothing else here can
-/// contradict it. Separate from scrobbling on purpose — an operator who placed
-/// a Last.fm application for submissions has not thereby agreed to lookups
-/// about the whole catalogue, so `lastfm_key` is its own setting even when it
-/// holds the same value.
-#[derive(Clone)]
-pub struct MetadataSettings {
-    /// `WAVEFLOW_METADATA_PROVIDERS`: an ordered, comma-separated list, empty
-    /// by default, of `lastfm`, `deezer` and `theaudiodb`. The order is the
-    /// order fields are merged in when read.
-    pub providers: Vec<crate::enrichment::Provider>,
-    /// `WAVEFLOW_METADATA_IMAGES`, on by default, `off` to keep the lookups and
-    /// refuse decision 8's image fetch. A narrowing only: it switches nothing
-    /// on while `providers` is empty.
-    pub images: bool,
-    /// `WAVEFLOW_METADATA_LASTFM_KEY`, the operator's own application key.
-    /// Required when `providers` names `lastfm`: no key ships in this binary.
-    pub lastfm_key: Option<String>,
-    /// `WAVEFLOW_METADATA_THEAUDIODB_KEY`, the operator's own TheAudioDB key.
-    /// Required when `providers` names `theaudiodb` (RFC-014 decision 1): the
-    /// public test key `waveflow-core` uses for one desktop user is not one a
-    /// server may share with everyone else's.
-    pub theaudiodb_key: Option<String>,
-    /// `WAVEFLOW_METADATA_TTL_DAYS`: how long an answer with content stands.
-    pub ttl: Duration,
-    /// `WAVEFLOW_METADATA_MISS_TTL_DAYS`: how long "the provider knows nothing"
-    /// stands. Shorter than `ttl`, and a setting of its own, because it is the
-    /// answer most likely to change.
-    pub miss_ttl: Duration,
-    /// `WAVEFLOW_METADATA_RATE_PER_SEC`: requests per second, per provider.
-    pub rate_per_sec: u32,
-    /// `WAVEFLOW_METADATA_REQUEST_TIMEOUT_SECS`: how long one request to a
-    /// provider may take before it counts as unreached.
-    pub request_timeout: Duration,
-}
-
-impl MetadataSettings {
-    /// Enrichment switched off — what a server that is merely upgraded runs.
-    pub fn off() -> Self {
-        Self {
-            providers: Vec::new(),
-            images: true,
-            lastfm_key: None,
-            theaudiodb_key: None,
-            ttl: Duration::from_secs(30 * 24 * 60 * 60),
-            miss_ttl: Duration::from_secs(7 * 24 * 60 * 60),
-            rate_per_sec: 4,
-            request_timeout: Duration::from_secs(10),
-        }
-    }
-}
-
-/// Written by hand so the key never reaches a log: a `Config` is printed at
-/// startup under `RUST_LOG=debug`, and a Last.fm key travels in a query string
-/// where anyone holding it can spend the operator's quota.
-impl std::fmt::Debug for MetadataSettings {
-    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        formatter
-            .debug_struct("MetadataSettings")
-            .field("providers", &self.providers)
-            .field("images", &self.images)
-            .field(
-                "lastfm_key",
-                &self.lastfm_key.as_ref().map(|_| "[redacted]"),
-            )
-            .field(
-                "theaudiodb_key",
-                &self.theaudiodb_key.as_ref().map(|_| "[redacted]"),
-            )
-            .field("ttl", &self.ttl)
-            .field("miss_ttl", &self.miss_ttl)
-            .field("rate_per_sec", &self.rate_per_sec)
-            .field("request_timeout", &self.request_timeout)
-            .finish()
-    }
-}
+mod access;
+mod env;
+mod for_data_dir;
+mod from_env;
+mod limits;
+mod metadata;
+mod pid;
+mod podcasts;
+mod scrobbling;
+
+pub use access::SETUP_TOKEN_MIN_CHARS;
+pub use limits::{CanvasLimits, LibraryEventRetention, UploadLimits};
+pub use metadata::{LyricsSettings, MetadataSettings};
+pub use podcasts::{PodcastSettings, RemoteArtworkSettings};
+pub use scrobbling::{
+    LastFmApplication, ScrobbleDestination, ScrobbleLimits, DEFAULT_SCROBBLE_DESTINATION,
+    DEFAULT_SCROBBLE_MAX_ATTEMPTS,
+};
 
-/// Lyrics looked up on LRCLIB, as RFC-024 decision 1 lists its settings.
-///
-/// **Off unless `providers` names one**, and that is the only switch, exactly
-/// as for [`MetadataSettings`]. A separate list rather than a value of
-/// `WAVEFLOW_METADATA_PROVIDERS`, because a lyrics lookup sends a track title,
-/// its album and its duration at the moment somebody plays it, which is a
-/// different consent from asking about an artist's name.
-#[derive(Debug, Clone)]
-pub struct LyricsSettings {
-    /// `WAVEFLOW_LYRICS_PROVIDERS`: empty by default, or `lrclib`.
-    pub providers: Vec<crate::lrclib::LyricsProvider>,
-    /// `WAVEFLOW_LYRICS_TTL_DAYS`: how long lyrics found are kept.
-    pub ttl: Duration,
-    /// `WAVEFLOW_LYRICS_MISS_TTL_DAYS`: how long "nothing for this track" is
-    /// kept.
-    pub miss_ttl: Duration,
-    /// `WAVEFLOW_LYRICS_RATE_PER_SEC`: requests per second.
-    pub rate_per_sec: u32,
-    /// `WAVEFLOW_LYRICS_REQUEST_TIMEOUT_SECS`: how long one request may take
-    /// before it counts as unanswered.
-    pub request_timeout: Duration,
-}
-
-impl LyricsSettings {
-    /// Lookups switched off — what a server that is merely upgraded runs.
-    pub fn off() -> Self {
-        Self {
-            providers: Vec::new(),
-            ttl: Duration::from_secs(30 * 24 * 60 * 60),
-            miss_ttl: Duration::from_secs(7 * 24 * 60 * 60),
-            rate_per_sec: 2,
-            request_timeout: Duration::from_secs(10),
-        }
-    }
-}
+use std::{net::SocketAddr, path::PathBuf, time::Duration};
 
 #[derive(Clone)]
 pub struct Config {
@@ -669,1416 +325,5 @@ impl std::fmt::Debug for Config {
     }
 }
 
-impl Config {
-    pub fn from_env() -> anyhow::Result<Self> {
-        let data_dir = std::env::var_os("WAVEFLOW_DATA_DIR")
-            .map(PathBuf::from)
-            .unwrap_or_else(|| PathBuf::from("data"));
-
-        let bind_addr = parse_env("WAVEFLOW_BIND", "127.0.0.1:4533")?;
-        let public_url = std::env::var("WAVEFLOW_PUBLIC_URL")
-            .ok()
-            .filter(|value| !value.trim().is_empty())
-            .map(|value| normalize_public_url(&value))
-            .transpose()?;
-        let request_timeout_secs = parse_positive_env("WAVEFLOW_REQUEST_TIMEOUT_SECS", 30u64)?;
-        let db_max_connections = parse_positive_env("WAVEFLOW_DB_MAX_CONNECTIONS", 8u32)?;
-        let db_acquire_timeout_ms = parse_positive_env(
-            "WAVEFLOW_DB_ACQUIRE_TIMEOUT_MS",
-            DEFAULT_DB_ACQUIRE_TIMEOUT_MS,
-        )?;
-        let sqlite_busy_timeout_ms =
-            parse_positive_env("WAVEFLOW_SQLITE_BUSY_TIMEOUT_MS", 5_000u64)?;
-        let stream_ticket_ttl_secs =
-            parse_positive_env("WAVEFLOW_STREAM_TICKET_TTL_SECS", 60 * 60u64)?;
-        let access_token_ttl_secs =
-            parse_positive_env("WAVEFLOW_ACCESS_TOKEN_TTL_SECS", 15 * 60u64)?;
-        let refresh_token_ttl_secs =
-            parse_positive_env("WAVEFLOW_REFRESH_TOKEN_TTL_SECS", 30 * 24 * 60 * 60u64)?;
-        // Zero is a value here and not a refusal — "no expiry" is a choice an
-        // operator may make — so it is read like the scan interval rather than
-        // through `parse_positive_env`.
-        let api_token_ttl_secs = std::env::var("WAVEFLOW_API_TOKEN_TTL_SECS")
-            .unwrap_or_else(|_| "31536000".to_owned())
-            .parse::<u64>()
-            .map_err(|error| anyhow::anyhow!("invalid WAVEFLOW_API_TOKEN_TTL_SECS: {error}"))?;
-        let scan_interval_secs = std::env::var("WAVEFLOW_SCAN_INTERVAL_SECS")
-            .unwrap_or_else(|_| "21600".to_owned())
-            .parse::<u64>()
-            .map_err(|error| anyhow::anyhow!("invalid WAVEFLOW_SCAN_INTERVAL_SECS: {error}"))?;
-        let scan_parallelism = parse_positive_env(
-            "WAVEFLOW_SCAN_PARALLELISM",
-            std::thread::available_parallelism()
-                .map(usize::from)
-                .unwrap_or(4)
-                .clamp(1, 16),
-        )?;
-        let watch = parse_bool_env("WAVEFLOW_WATCH", true)?;
-        let watch_delay =
-            Duration::from_secs(parse_positive_env("WAVEFLOW_WATCH_DELAY_SECS", 10u64)?);
-        // Zero is a setting, the default one: never purge on its own.
-        let unavailable_retention_days = std::env::var("WAVEFLOW_UNAVAILABLE_RETENTION_DAYS")
-            .unwrap_or_else(|_| "0".to_owned())
-            .parse::<u64>()
-            .map_err(|error| {
-                anyhow::anyhow!("invalid WAVEFLOW_UNAVAILABLE_RETENTION_DAYS: {error}")
-            })?;
-        let unavailable_retention = (unavailable_retention_days > 0)
-            .then(|| Duration::from_secs(unavailable_retention_days.saturating_mul(24 * 60 * 60)));
-        // Zero is a setting too: no way back, as before.
-        let purge_grace_hours = std::env::var("WAVEFLOW_PURGE_GRACE_HOURS")
-            .unwrap_or_else(|_| "168".to_owned())
-            .parse::<u64>()
-            .map_err(|error| anyhow::anyhow!("invalid WAVEFLOW_PURGE_GRACE_HOURS: {error}"))?;
-        let purge_grace = Duration::from_secs(purge_grace_hours.saturating_mul(60 * 60));
-        let link_roots = parse_link_roots(std::env::var_os("WAVEFLOW_LINK_ROOTS"))?;
-        let subsonic_replay_gain = match std::env::var("WAVEFLOW_SUBSONIC_REPLAYGAIN") {
-            Err(_) => crate::replay_gain::ReplayGainMode::Off,
-            Ok(raw) if raw.trim().is_empty() => crate::replay_gain::ReplayGainMode::Off,
-            Ok(raw) => crate::replay_gain::ReplayGainMode::parse(&raw).ok_or_else(|| {
-                anyhow::anyhow!(
-                    "invalid WAVEFLOW_SUBSONIC_REPLAYGAIN: expected off, track or album, found {raw:?}"
-                )
-            })?,
-        };
-        let ffmpeg_path = std::env::var_os("WAVEFLOW_FFMPEG_PATH")
-            .map(PathBuf::from)
-            .unwrap_or_else(|| PathBuf::from("ffmpeg"));
-        let ffprobe_path = std::env::var_os("WAVEFLOW_FFPROBE_PATH")
-            .map(PathBuf::from)
-            .unwrap_or_else(|| PathBuf::from("ffprobe"));
-        let transcode_cache_max_bytes =
-            parse_positive_env("WAVEFLOW_TRANSCODE_CACHE_MAX_BYTES", 10_737_418_240u64)?;
-        let transcode_global_limit = parse_positive_env("WAVEFLOW_TRANSCODE_GLOBAL_LIMIT", 4usize)?;
-        let transcode_per_user_limit =
-            parse_positive_env("WAVEFLOW_TRANSCODE_PER_USER_LIMIT", 2usize)?;
-        // Zero is a setting here, not a mistake: it is how an operator turns the
-        // analysis off, so this is not `parse_positive_env`.
-        let quality_parallelism = std::env::var("WAVEFLOW_QUALITY_PARALLELISM")
-            .unwrap_or_else(|_| "1".to_owned())
-            .parse::<usize>()
-            .map_err(|error| anyhow::anyhow!("invalid WAVEFLOW_QUALITY_PARALLELISM: {error}"))?;
-        let uploads = UploadLimits {
-            max_file_bytes: parse_positive_env("WAVEFLOW_UPLOAD_MAX_FILE_BYTES", 1_073_741_824i64)?,
-            library_quota_bytes: parse_positive_env(
-                "WAVEFLOW_UPLOAD_LIBRARY_QUOTA_BYTES",
-                53_687_091_200i64,
-            )?,
-            chunk_bytes: parse_positive_env("WAVEFLOW_UPLOAD_CHUNK_BYTES", 4_194_304i64)?,
-            batch_limit: parse_positive_env("WAVEFLOW_UPLOAD_BATCH_LIMIT", 200usize)?,
-            sessions_per_user: parse_positive_env("WAVEFLOW_UPLOAD_SESSIONS_PER_USER", 4usize)?,
-            session_ttl: Duration::from_secs(parse_positive_env(
-                "WAVEFLOW_UPLOAD_SESSION_TTL_SECS",
-                86_400u64,
-            )?),
-        };
-        validate_uploads(&uploads)?;
-        let canvas = CanvasLimits {
-            // A Spotify-style loop is a few seconds of portrait video: a few
-            // hundred kilobytes in practice. Four megabytes is comfortably
-            // above anything that is still a loop, and low enough that the
-            // body ceiling derived from it stays a ceiling.
-            max_bytes: parse_positive_env("WAVEFLOW_CANVAS_MAX_BYTES", 4_194_304i64)?,
-            // Those loops run three to eight seconds. Fifteen leaves room for
-            // an unusual one without leaving room for an episode.
-            max_duration_secs: parse_positive_env("WAVEFLOW_CANVAS_MAX_DURATION_SECS", 15u32)?,
-            // A gigabyte is thousands of real canvases, and still a number an
-            // operator can reason about against a disk.
-            library_quota_bytes: parse_positive_env(
-                "WAVEFLOW_CANVAS_LIBRARY_QUOTA_BYTES",
-                1_073_741_824i64,
-            )?,
-        };
-        validate_canvas(&canvas)?;
-        let scrobbling = ScrobbleLimits {
-            // A minute is far below what any destination considers a listening
-            // history's resolution, and far above what a queue of a few rows
-            // costs to walk.
-            drain_interval: Duration::from_secs(parse_positive_env(
-                "WAVEFLOW_SCROBBLE_DRAIN_INTERVAL_SECS",
-                60u64,
-            )?),
-            max_attempts: parse_positive_env(
-                "WAVEFLOW_SCROBBLE_MAX_ATTEMPTS",
-                DEFAULT_SCROBBLE_MAX_ATTEMPTS,
-            )?,
-            stale_after: Duration::from_secs(parse_positive_env(
-                "WAVEFLOW_SCROBBLE_STALE_AFTER_SECS",
-                3_600u64,
-            )?),
-            batch: parse_positive_env("WAVEFLOW_SCROBBLE_BATCH", 50usize)?,
-            // Thirty days: long enough to explain a failure somebody noticed
-            // last week, short enough that the queue does not become a second
-            // listening history. A setting, not a carved number — whoever
-            // diagnoses a three-month outage lengthens it, exactly as they
-            // widen the library event window.
-            retention_days: parse_positive_env("WAVEFLOW_SCROBBLE_RETENTION_DAYS", 30u32)?,
-            // Thirty seconds is far past any of the three destinations'
-            // ordinary latency and far short of a drain that has stopped. It
-            // bounds one submission, never the pass: the pass is bounded by
-            // `batch`.
-            request_timeout: Duration::from_secs(parse_positive_env(
-                "WAVEFLOW_SCROBBLE_REQUEST_TIMEOUT_SECS",
-                30u64,
-            )?),
-        };
-        // Both refuse zero and negatives at startup rather than falling back:
-        // every fallback for a bound is wrong, and the operator is turned away
-        // where they can see why. No ceiling — an enormous value means "purge
-        // nothing", which is safe and legible.
-        let library_event_retention = LibraryEventRetention {
-            days: parse_positive_env("WAVEFLOW_LIBRARY_EVENT_RETENTION_DAYS", 30u32)?,
-            min_events: parse_positive_env("WAVEFLOW_LIBRARY_EVENT_RETENTION_MIN", 10_000i64)?,
-        };
-        if transcode_per_user_limit > transcode_global_limit {
-            anyhow::bail!(
-                "WAVEFLOW_TRANSCODE_PER_USER_LIMIT cannot exceed WAVEFLOW_TRANSCODE_GLOBAL_LIMIT"
-            );
-        }
-        // Refused here rather than at the first submission, for the same reason
-        // `WAVEFLOW_PUBLIC_URL` is: booting with scrobbling silently switched
-        // off because of a typo is the exact silent failure RFC-010 spends
-        // itself making visible. An operator who wants no adapter says so by
-        // setting this empty, which is a different thing from misspelling it.
-        let outbound_allow_plaintext = parse_bool_env("WAVEFLOW_SCROBBLE_ALLOW_PLAINTEXT", false)?;
-        let mut destinations = Vec::new();
-        for (provider, variable, default) in [
-            (
-                crate::services::ScrobbleProvider::ListenBrainz,
-                "WAVEFLOW_SCROBBLE_LISTENBRAINZ_URL",
-                "https://api.listenbrainz.org",
-            ),
-            (
-                crate::services::ScrobbleProvider::Maloja,
-                "WAVEFLOW_SCROBBLE_MALOJA_URL",
-                // No default: Maloja is self-hosted by nature, so there is no
-                // public instance to point at, and guessing one would be
-                // inventing a destination the operator never named.
-                "",
-            ),
-            (
-                crate::services::ScrobbleProvider::LastFm,
-                "WAVEFLOW_SCROBBLE_LASTFM_URL",
-                "https://ws.audioscrobbler.com",
-            ),
-        ] {
-            let configured = std::env::var(variable).unwrap_or_else(|_| default.to_owned());
-            destinations.extend(parse_destinations(
-                provider,
-                variable,
-                &configured,
-                outbound_allow_plaintext,
-            )?);
-        }
-
-        // Both or neither, and said at boot rather than discovered when
-        // somebody tries to link: half an application is a typo, and a server
-        // that started with Last.fm quietly switched off because of one is the
-        // silent failure this whole RFC spends itself making visible.
-        let lastfm = match (
-            read_trimmed_env("WAVEFLOW_SCROBBLE_LASTFM_API_KEY"),
-            read_trimmed_env("WAVEFLOW_SCROBBLE_LASTFM_SECRET"),
-        ) {
-            (None, None) => None,
-            (Some(api_key), Some(secret)) => Some(LastFmApplication { api_key, secret }),
-            (Some(_), None) => anyhow::bail!(
-                "WAVEFLOW_SCROBBLE_LASTFM_API_KEY is set without WAVEFLOW_SCROBBLE_LASTFM_SECRET"
-            ),
-            (None, Some(_)) => anyhow::bail!(
-                "WAVEFLOW_SCROBBLE_LASTFM_SECRET is set without WAVEFLOW_SCROBBLE_LASTFM_API_KEY"
-            ),
-        };
-
-        let metadata = parse_metadata_settings()?;
-        let lyrics = parse_lyrics_settings()?;
-        let podcasts = parse_podcast_settings(&data_dir)?;
-        let remote_artwork = RemoteArtworkSettings {
-            enabled: parse_bool_env("WAVEFLOW_REMOTE_ARTWORK", true)?,
-            timeout: Duration::from_secs(20),
-            addresses: crate::portrait::AddressPolicy::Public,
-        };
-        // Absent is empty; a value that is not UTF-8 refuses to boot, rather
-        // than starting with no trusted proxy and counting every client behind
-        // it under the proxy's address.
-        let trusted_proxies = match std::env::var("WAVEFLOW_TRUSTED_PROXIES") {
-            Ok(list) => parse_proxy_addresses(&list)?,
-            Err(std::env::VarError::NotPresent) => Vec::new(),
-            Err(std::env::VarError::NotUnicode(_)) => {
-                anyhow::bail!("WAVEFLOW_TRUSTED_PROXIES is not valid UTF-8")
-            }
-        };
-
-        let setup_token = parse_setup_token(read_trimmed_env("WAVEFLOW_SETUP_TOKEN"))?;
-        // Zero is a setting, not a mistake: an operator with backups of their
-        // own turns the copies off with it.
-        let migration_backups = std::env::var("WAVEFLOW_MIGRATION_BACKUPS")
-            .unwrap_or_else(|_| "3".to_owned())
-            .parse::<usize>()
-            .map_err(|error| anyhow::anyhow!("invalid WAVEFLOW_MIGRATION_BACKUPS: {error}"))?;
-
-        let allowed_origins = std::env::var("WAVEFLOW_ALLOWED_ORIGINS")
-            .unwrap_or_default()
-            .split(',')
-            .map(str::trim)
-            .filter(|origin| !origin.is_empty())
-            .map(|origin| {
-                origin.parse::<axum::http::HeaderValue>().map_err(|error| {
-                    anyhow::anyhow!("invalid WAVEFLOW_ALLOWED_ORIGINS entry {origin:?}: {error}")
-                })
-            })
-            .collect::<anyhow::Result<Vec<_>>>()?;
-
-        // Parsed here rather than at first use: a spec that cannot be parsed —
-        // a recursive `albumid` above all — would otherwise re-identify the
-        // whole catalogue silently at the next scan. Refusing to boot says so.
-        let pid = crate::pid::PidSpecs {
-            album: parse_pid_spec(
-                "WAVEFLOW_PID_ALBUM",
-                DEFAULT_PID_ALBUM,
-                PidSpecKind::MayNotReferenceAlbumId,
-            )?,
-            track: parse_pid_spec(
-                "WAVEFLOW_PID_TRACK",
-                DEFAULT_PID_TRACK,
-                PidSpecKind::MayReferenceAlbumId,
-            )?,
-            artist: parse_pid_spec(
-                "WAVEFLOW_PID_ARTIST",
-                DEFAULT_PID_ARTIST,
-                PidSpecKind::MayNotReferenceAlbumId,
-            )?,
-        };
-
-        if refresh_token_ttl_secs <= access_token_ttl_secs {
-            anyhow::bail!(
-                "WAVEFLOW_REFRESH_TOKEN_TTL_SECS must be greater than WAVEFLOW_ACCESS_TOKEN_TTL_SECS"
-            );
-        }
-        let transcode_cache_dir = data_dir.join("transcode-cache");
-        let canvas_dir = data_dir.join("canvas");
-
-        Ok(Self {
-            bind_addr,
-            public_url,
-            request_timeout: Duration::from_secs(request_timeout_secs),
-            database_path: data_dir.join("waveflow.db"),
-            instance_key_path: data_dir.join("instance.key"),
-            artwork_dir: data_dir.join("artwork"),
-            data_dir,
-            db_max_connections,
-            db_acquire_timeout: Duration::from_millis(db_acquire_timeout_ms),
-            sqlite_busy_timeout: Duration::from_millis(sqlite_busy_timeout_ms),
-            access_token_ttl: Duration::from_secs(access_token_ttl_secs),
-            stream_ticket_ttl: Duration::from_secs(stream_ticket_ttl_secs),
-            refresh_token_ttl: Duration::from_secs(refresh_token_ttl_secs),
-            api_token_ttl: (api_token_ttl_secs > 0)
-                .then(|| Duration::from_secs(api_token_ttl_secs)),
-            scan_interval: (scan_interval_secs > 0)
-                .then(|| Duration::from_secs(scan_interval_secs)),
-            scan_parallelism,
-            watch,
-            watch_delay,
-            unavailable_retention,
-            purge_grace,
-            link_roots,
-            subsonic_replay_gain,
-            ffmpeg_path,
-            ffprobe_path,
-            transcode_cache_dir,
-            transcode_cache_max_bytes,
-            transcode_global_limit,
-            transcode_per_user_limit,
-            quality_parallelism,
-            uploads,
-            library_event_retention,
-            canvas_dir,
-            canvas,
-            scrobbling,
-            destinations,
-            lastfm,
-            outbound_allow_plaintext,
-            metadata,
-            lyrics,
-            podcasts,
-            remote_artwork,
-            allowed_origins,
-            trusted_proxies,
-            setup_token,
-            migration_backups,
-            pid,
-        })
-    }
-
-    pub fn for_data_dir(data_dir: PathBuf) -> Self {
-        let transcode_cache_dir = data_dir.join("transcode-cache");
-        let canvas_dir_for_tests = data_dir.join("canvas");
-        let podcast_dir_for_tests = data_dir.join("podcasts");
-        Self {
-            bind_addr: "127.0.0.1:0".parse().expect("literal socket address"),
-            public_url: Some("http://waveflow.test".to_owned()),
-            request_timeout: Duration::from_secs(30),
-            database_path: data_dir.join("waveflow.db"),
-            instance_key_path: data_dir.join("instance.key"),
-            artwork_dir: data_dir.join("artwork"),
-            data_dir,
-            db_max_connections: 4,
-            // Generous where production is tight, and for a reason production
-            // does not have: a test target boots a whole server per test, so
-            // several cold databases are created at once on a machine already
-            // compiling. Three targets — uploads, media, scrobbling — have
-            // each failed this acquire on the Windows runner at different
-            // times, naming whichever test happened to be unlucky. Raising
-            // the budget removes a lottery; it hides no wrong answer, because
-            // the only thing this timeout can produce is a refusal to start.
-            db_acquire_timeout: Duration::from_secs(30),
-            sqlite_busy_timeout: Duration::from_secs(5),
-            access_token_ttl: Duration::from_secs(15 * 60),
-            stream_ticket_ttl: Duration::from_secs(60 * 60),
-            refresh_token_ttl: Duration::from_secs(30 * 24 * 60 * 60),
-            // A year, as production has it: a suite that minted tokens with no
-            // expiry could not tell a bounded one from an unbounded one.
-            api_token_ttl: Some(Duration::from_secs(365 * 24 * 60 * 60)),
-            scan_interval: None,
-            scan_parallelism: 2,
-            // Off, like the periodic scan: a test that writes a file and then
-            // scans must not find a second scan racing its own. The watcher's
-            // tests start one themselves.
-            watch: false,
-            watch_delay: Duration::from_millis(200),
-            unavailable_retention: None,
-            // Production's default: the suite purges the way a server does.
-            purge_grace: Duration::from_secs(168 * 60 * 60),
-            link_roots: Vec::new(),
-            subsonic_replay_gain: crate::replay_gain::ReplayGainMode::Off,
-            ffmpeg_path: PathBuf::from("ffmpeg"),
-            ffprobe_path: PathBuf::from("ffprobe"),
-            transcode_cache_dir,
-            transcode_cache_max_bytes: 128 * 1024 * 1024,
-            transcode_global_limit: 2,
-            transcode_per_user_limit: 1,
-            quality_parallelism: 1,
-            // Small enough that a test can reach every bound without writing a
-            // gigabyte, and shaped like production rather than unlimited: a
-            // suite that never meets a limit never proves one exists.
-            uploads: UploadLimits {
-                max_file_bytes: 1024 * 1024,
-                library_quota_bytes: 4 * 1024 * 1024,
-                chunk_bytes: 64 * 1024,
-                batch_limit: 8,
-                sessions_per_user: 2,
-                session_ttl: Duration::from_secs(3600),
-            },
-            // Small enough that a test can write past the floor without
-            // writing ten thousand rows, and shaped like production rather
-            // than unlimited.
-            library_event_retention: LibraryEventRetention {
-                days: 30,
-                min_events: 4,
-            },
-            canvas_dir: canvas_dir_for_tests,
-            // Same reasoning as the upload limits above: small enough that a
-            // test can reach every bound, shaped like production rather than
-            // unlimited.
-            canvas: CanvasLimits {
-                max_bytes: 256 * 1024,
-                max_duration_secs: 15,
-                library_quota_bytes: 1024 * 1024,
-            },
-            // Same reasoning again: small enough that a test can exhaust the
-            // attempts without waiting out eight doublings, shaped like
-            // production rather than unlimited. The interval is never reached —
-            // `spawn_scrobble_drain` is started by `main`, and tests run the
-            // pass themselves.
-            scrobbling: ScrobbleLimits {
-                drain_interval: Duration::from_secs(60),
-                // Long enough that no test double ever meets it by accident;
-                // the one test that means to meet it shortens this first.
-                request_timeout: Duration::from_secs(30),
-                max_attempts: 3,
-                stale_after: Duration::from_secs(3600),
-                batch: 8,
-                retention_days: 30,
-            },
-            // One instance, declared and unreachable.
-            //
-            // **Declared**, because a member may only link a name the operator
-            // published, and a suite with an empty list could link nothing and
-            // would exercise none of the queue.
-            //
-            // **Unreachable**, because the suite must never reach the real
-            // ListenBrainz: port 1 on loopback is a port nothing binds. Every
-            // test that drives the queue replaces the adapter with a double
-            // through `register_scrobble_target`, and the handful that mean to
-            // exercise a real request point this at a server they started
-            // themselves — over plain HTTP on loopback, which is why the
-            // plaintext escape is on here and off in production.
-            destinations: test_destinations(),
-            // No application, so the suite never reaches the real Last.fm and
-            // the destination declared above stays adapterless — which is what
-            // two tests here stand on.
-            lastfm: None,
-            outbound_allow_plaintext: true,
-            // Off, as production defaults: the suite never reaches a real
-            // provider, and the targets that exercise enrichment build their
-            // own engine against a listener of their own.
-            metadata: MetadataSettings::off(),
-            // Off as well, and for the same reason: the targets that exercise
-            // LRCLIB build their own lookup against a listener of their own.
-            lyrics: LyricsSettings::off(),
-            // Off, as production defaults, and small enough that a test can
-            // reach every bound. The podcast targets switch it on and point
-            // it at a listener of their own on loopback, which is the one
-            // reason the address policy here admits loopback.
-            podcasts: PodcastSettings {
-                enabled: false,
-                refresh_interval: None,
-                allow_http: false,
-                max_feed_bytes: 256 * 1024,
-                max_episode_bytes: 1024 * 1024,
-                quota_bytes: 4 * 1024 * 1024,
-                feed_timeout: Duration::from_secs(10),
-                download_timeout: Duration::from_secs(30),
-                dir: podcast_dir_for_tests,
-                addresses: crate::portrait::AddressPolicy::AllowLoopback,
-            },
-            // On, as production defaults, and admitting loopback for the same
-            // reason the podcast policy above does: the image hosts the suite
-            // serves are listeners of its own. No test reaches this unless it
-            // names an image, so nothing leaves the machine.
-            remote_artwork: RemoteArtworkSettings {
-                enabled: true,
-                timeout: Duration::from_secs(10),
-                addresses: crate::portrait::AddressPolicy::AllowLoopback,
-            },
-            allowed_origins: Vec::new(),
-            trusted_proxies: Vec::new(),
-            // Drawn at boot and written to the data directory, as production
-            // does by default: the setup tests read it back from there.
-            setup_token: None,
-            migration_backups: 3,
-            // The real defaults, so the whole test suite exercises the specs
-            // production runs under rather than a simplified stand-in.
-            pid: default_pid_specs(),
-        }
-    }
-}
-
-/// The upload limits that only make sense against each other.
-///
-/// Apart here rather than inline so the rules can be exercised without
-/// rewriting the process environment, which is global and shared by every test
-/// running beside it.
-fn validate_uploads(uploads: &UploadLimits) -> anyhow::Result<()> {
-    if uploads.max_file_bytes > uploads.library_quota_bytes {
-        anyhow::bail!(
-            "WAVEFLOW_UPLOAD_MAX_FILE_BYTES cannot exceed WAVEFLOW_UPLOAD_LIBRARY_QUOTA_BYTES"
-        );
-    }
-    // The fragment route turns this into a body ceiling, and a value it cannot
-    // represent would have to fall back to something. Every fallback for a
-    // ceiling is wrong — too small breaks the configured size, too large is no
-    // ceiling at all — so it is refused here, where the operator can see why.
-    if usize::try_from(uploads.chunk_bytes).is_err() {
-        anyhow::bail!("invalid WAVEFLOW_UPLOAD_CHUNK_BYTES: too large for this platform");
-    }
-    if uploads.chunk_bytes > uploads.max_file_bytes {
-        anyhow::bail!("WAVEFLOW_UPLOAD_CHUNK_BYTES cannot exceed WAVEFLOW_UPLOAD_MAX_FILE_BYTES");
-    }
-    Ok(())
-}
-
-/// The canvas limits that only make sense against each other.
-fn validate_canvas(canvas: &CanvasLimits) -> anyhow::Result<()> {
-    if canvas.max_bytes > canvas.library_quota_bytes {
-        anyhow::bail!(
-            "WAVEFLOW_CANVAS_MAX_BYTES cannot exceed WAVEFLOW_CANVAS_LIBRARY_QUOTA_BYTES"
-        );
-    }
-    // The route turns this into a body ceiling, and a value it cannot represent
-    // would have to fall back to something. Every fallback for a ceiling is
-    // wrong, so it is refused here where the operator can see why — the same
-    // rule the upload chunk size follows.
-    if usize::try_from(canvas.max_bytes).is_err() {
-        anyhow::bail!("invalid WAVEFLOW_CANVAS_MAX_BYTES: too large for this platform");
-    }
-    Ok(())
-}
-
-/// The shortest operator-chosen setup token accepted.
-///
-/// The drawn one carries 256 bits. This is the floor for a value somebody
-/// typed, and nothing throttles setup: a guess at the token costs one request.
-pub const SETUP_TOKEN_MIN_CHARS: usize = 16;
-
-/// `WAVEFLOW_SETUP_TOKEN`, refused when too short to stand unthrottled.
-fn parse_setup_token(value: Option<String>) -> anyhow::Result<Option<String>> {
-    match value {
-        Some(token) if token.chars().count() < SETUP_TOKEN_MIN_CHARS => anyhow::bail!(
-            "WAVEFLOW_SETUP_TOKEN must be at least {SETUP_TOKEN_MIN_CHARS} characters"
-        ),
-        other => Ok(other),
-    }
-}
-
-/// One environment variable, trimmed, with an empty value read as absent.
-///
-/// "Set to nothing" and "not set" are the same statement from an operator, and
-/// an `.env` file that keeps a commented-out key as `NAME=` is the ordinary way
-/// of making it.
-fn read_trimmed_env(name: &str) -> Option<String> {
-    std::env::var(name)
-        .ok()
-        .map(|value| value.trim().to_owned())
-        .filter(|value| !value.is_empty())
-}
-
-/// The instance `Config::for_data_dir` declares. See the comment there.
-fn test_destinations() -> Vec<ScrobbleDestination> {
-    // `expect` rather than a fallible signature: the literal is right here, and
-    // a `Config` builder that could fail would push the failure into every
-    // test's first line for no gain.
-    // All three recipients, because an account cannot link a name nobody
-    // declared, and more than one test drives a queue holding two of them —
-    // a destination this process cannot reach must not hold up one it can.
-    //
-    // Declaring a destination is not registering an adapter, and the difference
-    // is what those tests stand on: a Last.fm instance with no application
-    // credentials configured is declared and adapterless, which is a shape a
-    // real deployment has too.
-    [
-        (
-            crate::services::ScrobbleProvider::ListenBrainz,
-            "http://127.0.0.1:1",
-        ),
-        (
-            crate::services::ScrobbleProvider::Maloja,
-            "http://127.0.0.1:2",
-        ),
-        (
-            crate::services::ScrobbleProvider::LastFm,
-            "http://127.0.0.1:3",
-        ),
-    ]
-    .into_iter()
-    .map(|(provider, base)| {
-        let url = crate::scrobblers::validate_destination(base, true)
-            .expect("a loopback destination nothing is listening on");
-        let fingerprint = crate::scrobblers::destination_fingerprint(&url);
-        ScrobbleDestination {
-            provider,
-            name: DEFAULT_SCROBBLE_DESTINATION.to_owned(),
-            url,
-            fingerprint,
-        }
-    })
-    .collect()
-}
-
-/// Reads one recipient's declared instances.
-///
-/// Either a bare URL — one instance, named [`DEFAULT_SCROBBLE_DESTINATION`] —
-/// or a comma-separated list of `name=url`. The two forms produce the same
-/// rows, so adding a second instance later does not rename the first.
-///
-/// **Everything here is refused at boot rather than at the first submission.**
-/// A server that starts with scrobbling quietly switched off by a typo is
-/// exactly the silent failure RFC-010 spends itself making visible. An operator
-/// who wants no adapter for a recipient says so by setting the variable empty,
-/// which is a different thing from misspelling it.
-fn parse_destinations(
-    provider: crate::services::ScrobbleProvider,
-    variable: &str,
-    configured: &str,
-    allow_plaintext: bool,
-) -> anyhow::Result<Vec<ScrobbleDestination>> {
-    let configured = configured.trim();
-    if configured.is_empty() {
-        return Ok(Vec::new());
-    }
-    let mut destinations: Vec<ScrobbleDestination> = Vec::new();
-    for entry in configured
-        .split(',')
-        .map(str::trim)
-        .filter(|entry| !entry.is_empty())
-    {
-        // Split on the first `=` — but only when what precedes it could be a
-        // name at all.
-        //
-        // **The obvious version of this leaks a password.** It said the first
-        // `=` cannot occur inside a URL because a scheme has none, which is
-        // true of the scheme and false of everything after it:
-        // `https://wf:pa=ss@host` splits into `https://wf:pa` and `ss@host`,
-        // and the first half then fails the name check and is quoted back in
-        // the error — scheme, account and half the password, in a startup log.
-        // The paragraph below promises the URL never reaches a message, and
-        // this was the path that broke it.
-        //
-        // A name is letters, digits, `-`, `_` and `.`. Neither `:` nor `/` can
-        // appear in one, so their presence before the `=` means the separator
-        // was inside a URL, and the whole entry is read as a bare address. A
-        // mistyped *name* — `al ice=…` — has neither, so it is still reported
-        // by name, which is what an operator needs to see.
-        let named = entry
-            .split_once('=')
-            .filter(|(before, _)| !before.contains([':', '/']));
-        let (name, raw) = match named {
-            Some((name, raw)) => (name.trim(), raw.trim()),
-            None => (DEFAULT_SCROBBLE_DESTINATION, entry),
-        };
-        crate::scrobblers::validate_destination_name(name)
-            .map_err(|error| anyhow::anyhow!("invalid {variable} entry {name:?}: {error}"))?;
-        // **Never the URL itself in the message.** `validate_destination`
-        // refuses a destination carrying credentials, so the one thing this
-        // branch is most likely to be handed is the one thing that must not be
-        // printed: `http://user:secret@host` would land in a startup log, or a
-        // support paste, in full. The name and the variant say enough.
-        let url = crate::scrobblers::validate_destination(raw, allow_plaintext)
-            .map_err(|error| anyhow::anyhow!("invalid {variable} entry {name:?}: {error}"))?;
-        if destinations.iter().any(|existing| existing.name == name) {
-            anyhow::bail!("{variable} declares {name:?} twice");
-        }
-        // Two names for one machine would give a member two ways to reach the
-        // same profile and two links to keep in step, and the second would look
-        // like a different destination in every counter.
-        let fingerprint = crate::scrobblers::destination_fingerprint(&url);
-        if let Some(twin) = destinations
-            .iter()
-            .find(|existing| existing.fingerprint == fingerprint)
-        {
-            anyhow::bail!(
-                "{variable} declares {name:?} and {:?} at the same address",
-                twin.name
-            );
-        }
-        destinations.push(ScrobbleDestination {
-            provider,
-            name: name.to_owned(),
-            url,
-            fingerprint,
-        });
-    }
-    Ok(destinations)
-}
-
-fn normalize_public_url(value: &str) -> anyhow::Result<String> {
-    let parsed = url::Url::parse(value.trim())
-        .map_err(|error| anyhow::anyhow!("invalid WAVEFLOW_PUBLIC_URL: {error}"))?;
-    if !matches!(parsed.scheme(), "http" | "https")
-        || !parsed.username().is_empty()
-        || parsed.password().is_some()
-        || parsed.query().is_some()
-        || parsed.fragment().is_some()
-        || !matches!(parsed.path(), "" | "/")
-    {
-        anyhow::bail!(
-            "WAVEFLOW_PUBLIC_URL must be an http(s) origin without credentials, path, query or fragment"
-        );
-    }
-    Ok(parsed.origin().ascii_serialization())
-}
-
-/// `WAVEFLOW_TRUSTED_PROXIES`: addresses or CIDR blocks. A bare address is its
-/// own block. A typo refuses to boot rather than trusting less, or more, than
-/// the operator wrote. A block written in IPv4-mapped form is read as the IPv4
-/// block it spells, which is how the limiter compares it.
-fn parse_proxy_addresses(list: &str) -> anyhow::Result<Vec<ipnet::IpNet>> {
-    list.split(',')
-        .map(str::trim)
-        .filter(|entry| !entry.is_empty())
-        .map(|entry| {
-            entry
-                .parse::<ipnet::IpNet>()
-                .or_else(|_| entry.parse::<std::net::IpAddr>().map(ipnet::IpNet::from))
-                .map(crate::sign_in::trusted_network)
-                .map_err(|_| anyhow::anyhow!("invalid WAVEFLOW_TRUSTED_PROXIES entry {entry:?}"))
-        })
-        .collect()
-}
-
-/// Reads RFC-011 decision 3's settings.
-fn parse_metadata_settings() -> anyhow::Result<MetadataSettings> {
-    let defaults = MetadataSettings::off();
-    let lastfm_key = read_trimmed_env("WAVEFLOW_METADATA_LASTFM_KEY");
-    let theaudiodb_key = read_trimmed_env("WAVEFLOW_METADATA_THEAUDIODB_KEY");
-    let providers = parse_metadata_providers(
-        &std::env::var("WAVEFLOW_METADATA_PROVIDERS").unwrap_or_default(),
-        lastfm_key.is_some(),
-        theaudiodb_key.is_some(),
-    )?;
-    let days = |name: &str, default: Duration| -> anyhow::Result<Duration> {
-        let days: u64 = parse_positive_env(name, default.as_secs() / (24 * 60 * 60))?;
-        days.checked_mul(24 * 60 * 60)
-            .map(Duration::from_secs)
-            .ok_or_else(|| anyhow::anyhow!("invalid {name}: too large"))
-    };
-    Ok(MetadataSettings {
-        providers,
-        images: parse_bool_env("WAVEFLOW_METADATA_IMAGES", defaults.images)?,
-        lastfm_key,
-        theaudiodb_key,
-        ttl: days("WAVEFLOW_METADATA_TTL_DAYS", defaults.ttl)?,
-        miss_ttl: days("WAVEFLOW_METADATA_MISS_TTL_DAYS", defaults.miss_ttl)?,
-        rate_per_sec: parse_positive_env("WAVEFLOW_METADATA_RATE_PER_SEC", defaults.rate_per_sec)?,
-        request_timeout: Duration::from_secs(parse_positive_env(
-            "WAVEFLOW_METADATA_REQUEST_TIMEOUT_SECS",
-            defaults.request_timeout.as_secs(),
-        )?),
-    })
-}
-
-/// Reads RFC-024 decision 1's settings.
-fn parse_lyrics_settings() -> anyhow::Result<LyricsSettings> {
-    let defaults = LyricsSettings::off();
-    let providers =
-        parse_lyrics_providers(&std::env::var("WAVEFLOW_LYRICS_PROVIDERS").unwrap_or_default())?;
-    let days = |name: &str, default: Duration| -> anyhow::Result<Duration> {
-        let days: u64 = parse_positive_env(name, default.as_secs() / (24 * 60 * 60))?;
-        days.checked_mul(24 * 60 * 60)
-            .map(Duration::from_secs)
-            .ok_or_else(|| anyhow::anyhow!("invalid {name}: too large"))
-    };
-    Ok(LyricsSettings {
-        providers,
-        ttl: days("WAVEFLOW_LYRICS_TTL_DAYS", defaults.ttl)?,
-        miss_ttl: days("WAVEFLOW_LYRICS_MISS_TTL_DAYS", defaults.miss_ttl)?,
-        rate_per_sec: parse_positive_env("WAVEFLOW_LYRICS_RATE_PER_SEC", defaults.rate_per_sec)?,
-        request_timeout: Duration::from_secs(parse_positive_env(
-            "WAVEFLOW_LYRICS_REQUEST_TIMEOUT_SECS",
-            defaults.request_timeout.as_secs(),
-        )?),
-    })
-}
-
-/// `WAVEFLOW_LYRICS_PROVIDERS`. An unknown name and a name given twice refuse
-/// to boot, for the reason [`parse_metadata_providers`] gives.
-fn parse_lyrics_providers(list: &str) -> anyhow::Result<Vec<crate::lrclib::LyricsProvider>> {
-    let mut providers = Vec::new();
-    for name in list
-        .split(',')
-        .map(str::trim)
-        .filter(|name| !name.is_empty())
-    {
-        let provider = crate::lrclib::LyricsProvider::parse(name)
-            .ok_or_else(|| anyhow::anyhow!("invalid WAVEFLOW_LYRICS_PROVIDERS entry {name:?}"))?;
-        if providers.contains(&provider) {
-            anyhow::bail!("WAVEFLOW_LYRICS_PROVIDERS names {name:?} twice");
-        }
-        providers.push(provider);
-    }
-    Ok(providers)
-}
-
-/// `WAVEFLOW_METADATA_PROVIDERS`, in the operator's order.
-///
-/// A provider named without its key, an unknown name and a name given twice
-/// all refuse to boot. Each is a typo, and a server that started with
-/// enrichment quietly narrower than its operator wrote is the silent failure
-/// these settings must not have — the operator learns it here, not from an
-/// artist page that never fills.
-fn parse_metadata_providers(
-    list: &str,
-    has_lastfm_key: bool,
-    has_theaudiodb_key: bool,
-) -> anyhow::Result<Vec<crate::enrichment::Provider>> {
-    let mut providers = Vec::new();
-    for name in list
-        .split(',')
-        .map(str::trim)
-        .filter(|name| !name.is_empty())
-    {
-        let provider = crate::enrichment::Provider::parse(name)
-            .ok_or_else(|| anyhow::anyhow!("invalid WAVEFLOW_METADATA_PROVIDERS entry {name:?}"))?;
-        if providers.contains(&provider) {
-            anyhow::bail!("WAVEFLOW_METADATA_PROVIDERS names {name:?} twice");
-        }
-        if provider == crate::enrichment::Provider::LastFm && !has_lastfm_key {
-            anyhow::bail!(
-                "WAVEFLOW_METADATA_PROVIDERS names lastfm without WAVEFLOW_METADATA_LASTFM_KEY"
-            );
-        }
-        if provider == crate::enrichment::Provider::TheAudioDb && !has_theaudiodb_key {
-            anyhow::bail!(
-                "WAVEFLOW_METADATA_PROVIDERS names theaudiodb without WAVEFLOW_METADATA_THEAUDIODB_KEY"
-            );
-        }
-        providers.push(provider);
-    }
-    Ok(providers)
-}
-
-/// The podcast switch and its bounds (RFC-025 decision 7).
-///
-/// Every bound refuses zero at startup, as the other bounds here do; the
-/// interval is the exception, because zero is how "never on its own" is said.
-fn parse_podcast_settings(data_dir: &std::path::Path) -> anyhow::Result<PodcastSettings> {
-    let refresh_secs = std::env::var("WAVEFLOW_PODCAST_REFRESH_INTERVAL_SECS")
-        .unwrap_or_else(|_| "21600".to_owned())
-        .parse::<u64>()
-        .map_err(|error| {
-            anyhow::anyhow!("invalid WAVEFLOW_PODCAST_REFRESH_INTERVAL_SECS: {error}")
-        })?;
-    let max_episode_bytes = parse_positive_env("WAVEFLOW_PODCAST_MAX_EPISODE_BYTES", 1u64 << 30)?;
-    let quota_bytes = parse_positive_env("WAVEFLOW_PODCAST_QUOTA_BYTES", 20u64 << 30)?;
-    if max_episode_bytes > quota_bytes {
-        anyhow::bail!(
-            "WAVEFLOW_PODCAST_MAX_EPISODE_BYTES cannot exceed WAVEFLOW_PODCAST_QUOTA_BYTES"
-        );
-    }
-    Ok(PodcastSettings {
-        enabled: parse_bool_env("WAVEFLOW_PODCASTS", false)?,
-        // Never more often than every five minutes: a refresh fetches every
-        // channel, and an interval of one second would be a crawler.
-        refresh_interval: (refresh_secs > 0).then(|| Duration::from_secs(refresh_secs.max(300))),
-        allow_http: parse_bool_env("WAVEFLOW_PODCAST_ALLOW_HTTP", true)?,
-        max_feed_bytes: parse_positive_env("WAVEFLOW_PODCAST_MAX_FEED_BYTES", 16usize << 20)?,
-        max_episode_bytes,
-        quota_bytes,
-        feed_timeout: Duration::from_secs(parse_positive_env(
-            "WAVEFLOW_PODCAST_FEED_TIMEOUT_SECS",
-            20u64,
-        )?),
-        download_timeout: Duration::from_secs(parse_positive_env(
-            "WAVEFLOW_PODCAST_DOWNLOAD_TIMEOUT_SECS",
-            1_800u64,
-        )?),
-        dir: data_dir.join("podcasts"),
-        addresses: crate::portrait::AddressPolicy::Public,
-    })
-}
-
-fn parse_env<T>(name: &str, default: &str) -> anyhow::Result<T>
-where
-    T: std::str::FromStr,
-    T::Err: std::fmt::Display,
-{
-    std::env::var(name)
-        .unwrap_or_else(|_| default.to_owned())
-        .parse()
-        .map_err(|error| anyhow::anyhow!("invalid {name}: {error}"))
-}
-
-/// A flag an operator either set on purpose or did not set at all.
-///
-/// A spelling this does not recognise is refused rather than read as `false`.
-/// Every silent fallback in this file is a bug waiting to be filed against
-/// something else, and this one especially: `WAVEFLOW_SCROBBLE_ALLOW_PLAINTEXT`
-/// guards whether a personal token may cross a network in clear, so an operator
-/// who typed `True ` or `on` must be told, not quietly overruled.
-fn parse_bool_env(name: &str, default: bool) -> anyhow::Result<bool> {
-    let Ok(raw) = std::env::var(name) else {
-        return Ok(default);
-    };
-    match raw.trim().to_ascii_lowercase().as_str() {
-        "" => Ok(default),
-        "1" | "true" | "yes" | "on" => Ok(true),
-        "0" | "false" | "no" | "off" => Ok(false),
-        other => anyhow::bail!("invalid {name}: expected a boolean, found {other:?}"),
-    }
-}
-
-/// `WAVEFLOW_LINK_ROOTS`: absolute folders, separated as `PATH` is.
-///
-/// Absolute because a relative one would be read against whatever directory
-/// the server happens to start in, which is not a decision about the file
-/// system an operator means to make. Not canonicalised here: a root on a
-/// mount that is not there yet must not stop the boot, so the scan resolves
-/// each one when it runs and skips one it cannot.
-fn parse_link_roots(raw: Option<std::ffi::OsString>) -> anyhow::Result<Vec<PathBuf>> {
-    let Some(raw) = raw else {
-        return Ok(Vec::new());
-    };
-    let mut roots = Vec::new();
-    for root in std::env::split_paths(&raw) {
-        if root.as_os_str().is_empty() {
-            continue;
-        }
-        if !root.is_absolute() {
-            anyhow::bail!(
-                "invalid WAVEFLOW_LINK_ROOTS: {} is not an absolute path",
-                root.display()
-            );
-        }
-        roots.push(root);
-    }
-    Ok(roots)
-}
-
-/// The acquire budget a deployment gets unless it says otherwise.
-///
-/// Named so the test fixture's longer budget can be compared against it
-/// instead of against a second copy of the number.
-const DEFAULT_DB_ACQUIRE_TIMEOUT_MS: u64 = 5_000;
-
-fn parse_positive_env<T>(name: &str, default: T) -> anyhow::Result<T>
-where
-    T: std::str::FromStr + PartialOrd + Default + Copy + std::fmt::Display,
-    T::Err: std::fmt::Display,
-{
-    let raw = std::env::var(name).unwrap_or_else(|_| default.to_string());
-    let value = raw
-        .parse::<T>()
-        .map_err(|error| anyhow::anyhow!("invalid {name}: {error}"))?;
-    if value <= T::default() {
-        anyhow::bail!("invalid {name}: must be greater than zero");
-    }
-    Ok(value)
-}
-
-/// The identity rules an instance runs under unless it says otherwise.
-///
-/// Taken verbatim from Navidrome, which is the reference these follow: a
-/// release identifier when the files carry one, otherwise the album artist,
-/// title, version and date together.
-const DEFAULT_PID_ALBUM: &str = "musicbrainz_albumid|albumartistid,album,albumversion,releasedate";
-const DEFAULT_PID_TRACK: &str = "musicbrainz_trackid|albumid,discnumber,tracknumber,title";
-const DEFAULT_PID_ARTIST: &str = "albumartistid";
-
-/// Whether a spec is allowed to name `albumid`.
-///
-/// The album's own spec is not, and neither is the artist's: both would be
-/// asking the album for an answer that depends on themselves.
-enum PidSpecKind {
-    MayNotReferenceAlbumId,
-    MayReferenceAlbumId,
-}
-
-impl PidSpecKind {
-    fn allows_album_id(&self) -> bool {
-        matches!(self, Self::MayReferenceAlbumId)
-    }
-}
-
-fn parse_pid_spec(
-    name: &str,
-    default: &str,
-    kind: PidSpecKind,
-) -> anyhow::Result<crate::pid::PidSpec> {
-    let raw = std::env::var(name).unwrap_or_else(|_| default.to_owned());
-    crate::pid::PidSpec::parse(&raw, kind.allows_album_id())
-        .map_err(|error| anyhow::anyhow!("invalid {name}: {error}"))
-}
-
-fn default_pid_spec(default: &str, kind: PidSpecKind) -> crate::pid::PidSpec {
-    crate::pid::PidSpec::parse(default, kind.allows_album_id()).expect("built-in pid spec default")
-}
-
-fn default_pid_specs() -> crate::pid::PidSpecs {
-    crate::pid::PidSpecs {
-        album: default_pid_spec(DEFAULT_PID_ALBUM, PidSpecKind::MayNotReferenceAlbumId),
-        track: default_pid_spec(DEFAULT_PID_TRACK, PidSpecKind::MayReferenceAlbumId),
-        artist: default_pid_spec(DEFAULT_PID_ARTIST, PidSpecKind::MayNotReferenceAlbumId),
-    }
-}
-
 #[cfg(test)]
-mod tests {
-    use super::normalize_public_url;
-    use super::parse_metadata_providers;
-    use super::parse_proxy_addresses;
-    use super::DEFAULT_DB_ACQUIRE_TIMEOUT_MS;
-    use super::{parse_destinations, DEFAULT_SCROBBLE_DESTINATION};
-    use super::{validate_canvas, CanvasLimits};
-    use super::{validate_uploads, UploadLimits};
-    use std::time::Duration;
-
-    fn workable() -> UploadLimits {
-        UploadLimits {
-            max_file_bytes: 1024 * 1024,
-            library_quota_bytes: 4 * 1024 * 1024,
-            chunk_bytes: 64 * 1024,
-            batch_limit: 8,
-            sessions_per_user: 2,
-            session_ttl: Duration::from_secs(3600),
-        }
-    }
-
-    /// RFC-017 decision 2: addresses and blocks alike, and a typo refuses to boot.
-    #[test]
-    fn trusted_proxies_are_read_strictly() {
-        assert!(parse_proxy_addresses("").unwrap().is_empty());
-        let proxies = parse_proxy_addresses(" 10.0.0.0/8, 192.168.1.5 , ::1 ").unwrap();
-        assert_eq!(proxies.len(), 3);
-        assert!(proxies[0].contains(&"10.1.2.3".parse::<std::net::IpAddr>().unwrap()));
-        assert!(proxies[1].contains(&"192.168.1.5".parse::<std::net::IpAddr>().unwrap()));
-        assert!(!proxies[1].contains(&"192.168.1.6".parse::<std::net::IpAddr>().unwrap()));
-        let mapped = parse_proxy_addresses("::ffff:10.0.0.5").unwrap();
-        assert!(mapped[0].contains(&"10.0.0.5".parse::<std::net::IpAddr>().unwrap()));
-        assert!(parse_proxy_addresses("10.0.0.0/33").is_err());
-        assert!(parse_proxy_addresses("proxy.local").is_err());
-    }
-
-    /// RFC-011 decision 3: empty is off, and every typo refuses to boot rather
-    /// than starting enrichment narrower than the operator wrote.
-    #[test]
-    fn metadata_providers_are_read_strictly() {
-        use crate::enrichment::Provider;
-
-        assert_eq!(parse_metadata_providers("", false, false).unwrap(), []);
-        assert_eq!(parse_metadata_providers(" , ", false, false).unwrap(), []);
-        assert_eq!(
-            parse_metadata_providers(" lastfm ", true, false).unwrap(),
-            [Provider::LastFm]
-        );
-        // No key ships in the binary: naming the provider without one is a
-        // misconfiguration, not a quiet off.
-        assert!(parse_metadata_providers("lastfm", false, false).is_err());
-        assert!(parse_metadata_providers("lastfm,lastfm", true, false).is_err());
-        assert!(parse_metadata_providers("last.fm", true, false).is_err());
-        // Deezer asks for no key, so none is required of it.
-        assert_eq!(
-            parse_metadata_providers("lastfm, deezer", true, false).unwrap(),
-            [Provider::LastFm, Provider::Deezer]
-        );
-        assert_eq!(
-            parse_metadata_providers("deezer", false, false).unwrap(),
-            [Provider::Deezer]
-        );
-        // TheAudioDB asks for a key of its own (RFC-014 decision 1), and the
-        // Last.fm one does not stand in for it.
-        assert!(parse_metadata_providers("theaudiodb", true, false).is_err());
-        assert_eq!(
-            parse_metadata_providers("deezer, theaudiodb", false, true).unwrap(),
-            [Provider::Deezer, Provider::TheAudioDb]
-        );
-    }
-
-    /// RFC-024 decision 1: the list is the switch, and a typo refuses to boot
-    /// rather than leaving lyrics quietly off.
-    #[test]
-    fn lyrics_providers_are_read_strictly() {
-        use crate::lrclib::LyricsProvider;
-
-        assert_eq!(super::parse_lyrics_providers("").unwrap(), []);
-        assert_eq!(super::parse_lyrics_providers(" , ").unwrap(), []);
-        assert_eq!(
-            super::parse_lyrics_providers(" lrclib ").unwrap(),
-            [LyricsProvider::Lrclib]
-        );
-        assert!(super::parse_lyrics_providers("lrclib,lrclib").is_err());
-        assert!(super::parse_lyrics_providers("lrclib.net").is_err());
-        // An artist provider is not a lyrics provider.
-        assert!(super::parse_lyrics_providers("lastfm").is_err());
-    }
-
-    #[test]
-    fn upload_limits_that_contradict_each_other_are_refused() {
-        assert!(validate_uploads(&workable()).is_ok());
-
-        // A fragment bigger than the largest file it could belong to.
-        let mut oversized_chunk = workable();
-        oversized_chunk.chunk_bytes = oversized_chunk.max_file_bytes + 1;
-        assert!(validate_uploads(&oversized_chunk).is_err());
-
-        // A file bigger than the whole library may hold.
-        let mut oversized_file = workable();
-        oversized_file.max_file_bytes = oversized_file.library_quota_bytes + 1;
-        assert!(validate_uploads(&oversized_file).is_err());
-
-        // And a fragment this platform could not turn into a body ceiling. The
-        // fallback for that conversion must never be "no ceiling", so the value
-        // has to be refused before it reaches one.
-        if usize::try_from(i64::MAX).is_err() {
-            let mut unrepresentable = workable();
-            unrepresentable.chunk_bytes = i64::MAX;
-            unrepresentable.max_file_bytes = i64::MAX;
-            unrepresentable.library_quota_bytes = i64::MAX;
-            assert!(validate_uploads(&unrepresentable).is_err());
-        }
-    }
-
-    #[test]
-    fn canvas_limits_that_contradict_each_other_are_refused() {
-        let workable = CanvasLimits {
-            max_bytes: 256 * 1024,
-            max_duration_secs: 15,
-            library_quota_bytes: 1024 * 1024,
-        };
-        assert!(validate_canvas(&workable).is_ok());
-
-        // A single canvas larger than the whole library may hold: the first one
-        // placed would be refused by a quota it can never fit under, which is a
-        // misconfiguration rather than a verdict.
-        let mut oversized = workable;
-        oversized.max_bytes = oversized.library_quota_bytes + 1;
-        assert!(validate_canvas(&oversized).is_err());
-
-        // And a ceiling this platform cannot represent, for the same reason the
-        // upload chunk size is refused: every fallback for a ceiling is wrong.
-        if usize::try_from(i64::MAX).is_err() {
-            let unrepresentable = CanvasLimits {
-                max_bytes: i64::MAX,
-                max_duration_secs: 15,
-                library_quota_bytes: i64::MAX,
-            };
-            assert!(validate_canvas(&unrepresentable).is_err());
-        }
-    }
-
-    #[test]
-    fn public_url_is_reduced_to_a_safe_http_origin() {
-        assert_eq!(
-            normalize_public_url("https://music.example.com:8443/").unwrap(),
-            "https://music.example.com:8443"
-        );
-        for invalid in [
-            "ftp://music.example.com",
-            "https://user:secret@music.example.com",
-            "https://music.example.com/waveflow",
-            "https://music.example.com?token=secret",
-        ] {
-            assert!(normalize_public_url(invalid).is_err(), "{invalid}");
-        }
-    }
-
-    /// A destination that cannot be used is never quoted back.
-    ///
-    /// `validate_destination` refuses a URL carrying credentials, so the value
-    /// this error branch is most likely to be holding is precisely the one that
-    /// must not be printed — and a startup error goes to a log, a terminal, and
-    /// whatever a person pastes into an issue. The repository's rule about
-    /// secrets has no exception for an error path.
-    ///
-    /// It used to live in `tests/scrobbling.rs` against `initialize`, which is
-    /// where the guard used to be. Named destinations moved the refusal here,
-    /// to the reading of the variable, and the test follows the guard rather
-    /// than staying where it was and passing for another reason.
-    #[test]
-    fn a_refused_destination_is_never_quoted_back_with_its_credentials() {
-        // A private host, so the plaintext rule lets this through and the
-        // credential rule is what refuses it. That is the path carrying a
-        // password.
-        let refused = parse_destinations(
-            crate::services::ScrobbleProvider::Maloja,
-            "WAVEFLOW_SCROBBLE_MALOJA_URL",
-            "house=http://wf-user:hunter2@10.0.0.2",
-            true,
-        )
-        .expect_err("a destination carrying credentials must be refused");
-        let said = format!("{refused:#}");
-
-        // **Named, never quoted.** An earlier version of this loop put the
-        // secret and the whole error into the assertion message, and CodeQL was
-        // right to call that a cleartext write of a credential — in the one
-        // test whose entire subject is that credentials must not be written.
-        // What a failure here needs to say is *which* part came back, not the
-        // part itself.
-        for (part, secret) in [
-            ("the password", "hunter2"),
-            ("the account", "wf-user"),
-            ("the host", "10.0.0.2"),
-        ] {
-            assert!(
-                !said.contains(secret),
-                "the startup error quoted {part} back from the destination"
-            );
-        }
-        // And it still says enough to be fixed by the person who typed it:
-        // which variable, which name, and what was wrong with it. Printing
-        // `said` is safe here and only here — the loop above has just
-        // established that it carries none of the three.
-        assert!(
-            said.contains("credentials"),
-            "the error must name the fault: {said}"
-        );
-        assert!(
-            said.contains("house") && said.contains("WAVEFLOW_SCROBBLE_MALOJA_URL"),
-            "the error must name the entry that is wrong: {said}"
-        );
-
-        // **And a password containing `=` does not become the name.** The first
-        // version of the parser split on the first `=` wherever it fell, so
-        // this entry became the name `http://wf-user:pa` and the address
-        // `ss@10.0.0.2` — and the name is what the refusal quotes back. Half a
-        // password in a startup log, from the one paragraph that promises the
-        // opposite. Nothing about the shape of this entry is unusual; `=` is an
-        // ordinary character in a generated password.
-        let refused = parse_destinations(
-            crate::services::ScrobbleProvider::Maloja,
-            "WAVEFLOW_SCROBBLE_MALOJA_URL",
-            "http://wf-user:pa=ss@10.0.0.2",
-            true,
-        )
-        .expect_err("a destination carrying credentials must be refused");
-        let said = format!("{refused:#}");
-        for (part, secret) in [
-            ("the password", "pa=ss"),
-            ("part of the password", "pa"),
-            ("the account", "wf-user"),
-            ("the host", "10.0.0.2"),
-        ] {
-            assert!(
-                !said.contains(secret),
-                "the startup error quoted {part} back from the destination"
-            );
-        }
-        assert!(
-            said.contains("credentials"),
-            "the error must still name the fault"
-        );
-    }
-
-    /// A mistyped *name* is still reported by name.
-    ///
-    /// The guard above reads an entry as a bare address whenever the text
-    /// before the `=` could not be a name. That must not swallow the ordinary
-    /// typo it exists beside: a name with a space in it carries neither `:` nor
-    /// `/`, so it is still a name, and the operator is told which one.
-    #[test]
-    fn a_mistyped_name_is_still_named_in_the_refusal() {
-        let refused = parse_destinations(
-            crate::services::ScrobbleProvider::Maloja,
-            "WAVEFLOW_SCROBBLE_MALOJA_URL",
-            "al ice=https://host/alice",
-            false,
-        )
-        .expect_err("a name with a space must be refused");
-        let said = format!("{refused:#}");
-        assert!(said.contains("al ice"), "{said}");
-    }
-
-    /// Two spellings of one machine are one destination.
-    ///
-    /// The trailing slash is the one an editor adds without anybody deciding
-    /// to, and a fingerprint that moved with it would break every link on a
-    /// server at the first restart after a configuration tidy-up.
-    #[test]
-    fn a_trailing_slash_does_not_move_a_destination() {
-        let bare = parse_destinations(
-            crate::services::ScrobbleProvider::Maloja,
-            "WAVEFLOW_SCROBBLE_MALOJA_URL",
-            "https://host/maloja",
-            false,
-        )
-        .expect("a valid destination");
-        let slashed = parse_destinations(
-            crate::services::ScrobbleProvider::Maloja,
-            "WAVEFLOW_SCROBBLE_MALOJA_URL",
-            "https://host/maloja/",
-            false,
-        )
-        .expect("a valid destination");
-        assert_eq!(bare[0].fingerprint, slashed[0].fingerprint);
-
-        // And the path is *part* of the identity, unlike an origin. Two tenants
-        // on one host are two destinations, and giving them one fingerprint
-        // would let the identity guard wave through the likeliest move there
-        // is.
-        let other_tenant = parse_destinations(
-            crate::services::ScrobbleProvider::Maloja,
-            "WAVEFLOW_SCROBBLE_MALOJA_URL",
-            "https://host/maloja-two",
-            false,
-        )
-        .expect("a valid destination");
-        assert_ne!(bare[0].fingerprint, other_tenant[0].fingerprint);
-    }
-
-    /// A recipient may carry several instances, and neither name nor address
-    /// may repeat.
-    #[test]
-    fn a_recipient_carries_several_instances_each_named_once() {
-        let declared = parse_destinations(
-            crate::services::ScrobbleProvider::Maloja,
-            "WAVEFLOW_SCROBBLE_MALOJA_URL",
-            "alice=https://host/alice, bob=https://host/bob",
-            false,
-        )
-        .expect("two instances");
-        assert_eq!(declared.len(), 2);
-        assert_eq!(declared[0].name, "alice");
-        assert_eq!(declared[1].name, "bob");
-
-        // A bare URL is the shorthand for one instance called `default`, so the
-        // two spellings produce the same row and adding a second instance later
-        // does not rename the first.
-        let shorthand = parse_destinations(
-            crate::services::ScrobbleProvider::Maloja,
-            "WAVEFLOW_SCROBBLE_MALOJA_URL",
-            "https://host/alice",
-            false,
-        )
-        .expect("one instance");
-        assert_eq!(shorthand[0].name, DEFAULT_SCROBBLE_DESTINATION);
-
-        // Two names for one machine would give a member two links to keep in
-        // step with one profile, and each would look like a separate
-        // destination in every counter.
-        assert!(parse_destinations(
-            crate::services::ScrobbleProvider::Maloja,
-            "WAVEFLOW_SCROBBLE_MALOJA_URL",
-            "alice=https://host/alice, ALICE=https://host/alice/",
-            false,
-        )
-        .is_err());
-
-        // And one name for two machines is not a configuration either.
-        assert!(parse_destinations(
-            crate::services::ScrobbleProvider::Maloja,
-            "WAVEFLOW_SCROBBLE_MALOJA_URL",
-            "alice=https://host/alice, alice=https://host/bob",
-            false,
-        )
-        .is_err());
-    }
-
-    /// A name that cannot be a path segment is refused where it is written.
-    #[test]
-    fn a_destination_name_is_bounded_by_what_crosses_a_path() {
-        for refused in [
-            ".",
-            "..",
-            "al ice",
-            "alice/bob",
-            "alice%2f",
-            "",
-            &"a".repeat(65),
-        ] {
-            assert!(
-                parse_destinations(
-                    crate::services::ScrobbleProvider::Maloja,
-                    "WAVEFLOW_SCROBBLE_MALOJA_URL",
-                    &format!("{refused}=https://host/alice"),
-                    false,
-                )
-                .is_err(),
-                "{refused:?} must not become a path segment"
-            );
-        }
-        for accepted in ["alice", "a-b_c.d", "ALICE2", &"a".repeat(64)] {
-            assert!(
-                parse_destinations(
-                    crate::services::ScrobbleProvider::Maloja,
-                    "WAVEFLOW_SCROBBLE_MALOJA_URL",
-                    &format!("{accepted}=https://host/alice"),
-                    false,
-                )
-                .is_ok(),
-                "{accepted:?} must be usable"
-            );
-        }
-    }
-
-    /// The test fixture waits longer for a cold database than a deployment.
-    ///
-    /// `Database::open` creates the file and establishes the connection the
-    /// migrations run on, and a test target boots one whole server per test,
-    /// so several cold databases are created at once on a machine that is
-    /// also compiling. Three targets — uploads, media, scrobbling — have each
-    /// failed that acquire on the Windows runner at different times, naming
-    /// whichever test was unlucky and looking like three unrelated flakes.
-    ///
-    /// Pinned because the repair is one literal wide: a later tidy-up that
-    /// gives the fixture the production budget back restores a lottery whose
-    /// losing ticket is drawn in a different file every time.
-    #[test]
-    fn the_test_fixture_waits_longer_for_a_cold_database_than_a_deployment() {
-        let fixture = super::Config::for_data_dir(std::path::PathBuf::from("data"));
-        let deployment = Duration::from_millis(DEFAULT_DB_ACQUIRE_TIMEOUT_MS);
-        assert!(
-            fixture.db_acquire_timeout > deployment,
-            "the fixture waits {:?}, a deployment {deployment:?} — a test boots a server per \
-             test and must not inherit a budget tuned for one warm server",
-            fixture.db_acquire_timeout
-        );
-    }
-}
+mod tests;
diff --git a/src/config/pid.rs b/src/config/pid.rs
new file mode 100644
index 00000000..fa5310f5
--- /dev/null
+++ b/src/config/pid.rs
@@ -0,0 +1,49 @@
+//! The identity specs: the defaults, and which of them may name `albumid`.
+
+/// The identity rules an instance runs under unless it says otherwise.
+///
+/// Taken verbatim from Navidrome, which is the reference these follow: a
+/// release identifier when the files carry one, otherwise the album artist,
+/// title, version and date together.
+pub(super) const DEFAULT_PID_ALBUM: &str =
+    "musicbrainz_albumid|albumartistid,album,albumversion,releasedate";
+pub(super) const DEFAULT_PID_TRACK: &str =
+    "musicbrainz_trackid|albumid,discnumber,tracknumber,title";
+pub(super) const DEFAULT_PID_ARTIST: &str = "albumartistid";
+
+/// Whether a spec is allowed to name `albumid`.
+///
+/// The album's own spec is not, and neither is the artist's: both would be
+/// asking the album for an answer that depends on themselves.
+pub(super) enum PidSpecKind {
+    MayNotReferenceAlbumId,
+    MayReferenceAlbumId,
+}
+
+impl PidSpecKind {
+    fn allows_album_id(&self) -> bool {
+        matches!(self, Self::MayReferenceAlbumId)
+    }
+}
+
+pub(super) fn parse_pid_spec(
+    name: &str,
+    default: &str,
+    kind: PidSpecKind,
+) -> anyhow::Result<crate::pid::PidSpec> {
+    let raw = std::env::var(name).unwrap_or_else(|_| default.to_owned());
+    crate::pid::PidSpec::parse(&raw, kind.allows_album_id())
+        .map_err(|error| anyhow::anyhow!("invalid {name}: {error}"))
+}
+
+fn default_pid_spec(default: &str, kind: PidSpecKind) -> crate::pid::PidSpec {
+    crate::pid::PidSpec::parse(default, kind.allows_album_id()).expect("built-in pid spec default")
+}
+
+pub(super) fn default_pid_specs() -> crate::pid::PidSpecs {
+    crate::pid::PidSpecs {
+        album: default_pid_spec(DEFAULT_PID_ALBUM, PidSpecKind::MayNotReferenceAlbumId),
+        track: default_pid_spec(DEFAULT_PID_TRACK, PidSpecKind::MayReferenceAlbumId),
+        artist: default_pid_spec(DEFAULT_PID_ARTIST, PidSpecKind::MayNotReferenceAlbumId),
+    }
+}
diff --git a/src/config/podcasts.rs b/src/config/podcasts.rs
new file mode 100644
index 00000000..3b7d1412
--- /dev/null
+++ b/src/config/podcasts.rs
@@ -0,0 +1,111 @@
+//! Podcasts, and the remote artwork that podcast covers and station images
+//! are fetched under (RFC-025).
+
+use std::{path::PathBuf, time::Duration};
+
+use super::env::{parse_bool_env, parse_positive_env};
+
+/// Podcasts (RFC-025 decisions 7 to 12).
+///
+/// **Off by default, and an upgrade leaves it off**: subscribing to a feed is
+/// outbound traffic to a host a person typed, and nothing of the kind happens
+/// until an operator says so. With the switch off, no feed is fetched, no
+/// episode is downloaded, and `podcastRole` is false for everyone; what was
+/// stored while it was on stays readable, and a downloaded episode stays
+/// playable from disk.
+#[derive(Debug, Clone)]
+pub struct PodcastSettings {
+    /// `WAVEFLOW_PODCASTS`, off by default.
+    pub enabled: bool,
+    /// `WAVEFLOW_PODCAST_REFRESH_INTERVAL_SECS`: how often every channel is
+    /// fetched again, six hours by default; `0` for never on its own — a
+    /// refresh then happens only when somebody asks for one.
+    pub refresh_interval: Option<Duration>,
+    /// `WAVEFLOW_PODCAST_ALLOW_HTTP`: whether a feed or an enclosure may be
+    /// plain http. On by default, because a good share of podcast enclosures
+    /// are still served that way and a feed is public content; the address
+    /// rules apply either way.
+    pub allow_http: bool,
+    /// `WAVEFLOW_PODCAST_MAX_FEED_BYTES`: the largest feed read, 16 MiB.
+    pub max_feed_bytes: usize,
+    /// `WAVEFLOW_PODCAST_MAX_EPISODE_BYTES`: the largest episode stored,
+    /// 1 GiB.
+    pub max_episode_bytes: u64,
+    /// `WAVEFLOW_PODCAST_QUOTA_BYTES`: how much the downloaded episodes may
+    /// occupy together, 20 GiB.
+    pub quota_bytes: u64,
+    /// `WAVEFLOW_PODCAST_FEED_TIMEOUT_SECS`: one feed fetch, redirects
+    /// included, 20 seconds.
+    pub feed_timeout: Duration,
+    /// `WAVEFLOW_PODCAST_DOWNLOAD_TIMEOUT_SECS`: one episode download, 30
+    /// minutes.
+    pub download_timeout: Duration,
+    /// Where episodes are stored: `<data dir>/podcasts`, derived and not set.
+    pub dir: PathBuf,
+    /// Which addresses a fetch may reach. Public ones in production, always;
+    /// not an environment variable. The test suite's feeds live on loopback,
+    /// and its fixture admits loopback for them alone.
+    pub addresses: crate::portrait::AddressPolicy,
+}
+
+/// Remote artwork: the cover a podcast feed names, and the image an account
+/// gives a radio station (RFC-025, amended).
+///
+/// **On by default**, unlike podcasts, because nothing here happens on its own:
+/// a station image is fetched once when an account sets or changes one, and a
+/// podcast cover only while `WAVEFLOW_PODCASTS` is on and a channel is
+/// subscribed or refreshed. Off, an address is still stored and nothing is
+/// fetched; covers already stored stay shown.
+#[derive(Debug, Clone, Copy)]
+pub struct RemoteArtworkSettings {
+    /// `WAVEFLOW_REMOTE_ARTWORK`, on by default.
+    pub enabled: bool,
+    /// One image fetch, redirects included. Derived, not set: the figure the
+    /// feed fetch defaults to, for a body the size of a cover.
+    pub timeout: Duration,
+    /// Which addresses a fetch may reach, as for podcasts: public ones in
+    /// production, always, and loopback as well for the test suite's hosts.
+    pub addresses: crate::portrait::AddressPolicy,
+}
+
+/// The podcast switch and its bounds (RFC-025 decision 7).
+///
+/// Every bound refuses zero at startup, as the other bounds here do; the
+/// interval is the exception, because zero is how "never on its own" is said.
+pub(super) fn parse_podcast_settings(
+    data_dir: &std::path::Path,
+) -> anyhow::Result<PodcastSettings> {
+    let refresh_secs = std::env::var("WAVEFLOW_PODCAST_REFRESH_INTERVAL_SECS")
+        .unwrap_or_else(|_| "21600".to_owned())
+        .parse::<u64>()
+        .map_err(|error| {
+            anyhow::anyhow!("invalid WAVEFLOW_PODCAST_REFRESH_INTERVAL_SECS: {error}")
+        })?;
+    let max_episode_bytes = parse_positive_env("WAVEFLOW_PODCAST_MAX_EPISODE_BYTES", 1u64 << 30)?;
+    let quota_bytes = parse_positive_env("WAVEFLOW_PODCAST_QUOTA_BYTES", 20u64 << 30)?;
+    if max_episode_bytes > quota_bytes {
+        anyhow::bail!(
+            "WAVEFLOW_PODCAST_MAX_EPISODE_BYTES cannot exceed WAVEFLOW_PODCAST_QUOTA_BYTES"
+        );
+    }
+    Ok(PodcastSettings {
+        enabled: parse_bool_env("WAVEFLOW_PODCASTS", false)?,
+        // Never more often than every five minutes: a refresh fetches every
+        // channel, and an interval of one second would be a crawler.
+        refresh_interval: (refresh_secs > 0).then(|| Duration::from_secs(refresh_secs.max(300))),
+        allow_http: parse_bool_env("WAVEFLOW_PODCAST_ALLOW_HTTP", true)?,
+        max_feed_bytes: parse_positive_env("WAVEFLOW_PODCAST_MAX_FEED_BYTES", 16usize << 20)?,
+        max_episode_bytes,
+        quota_bytes,
+        feed_timeout: Duration::from_secs(parse_positive_env(
+            "WAVEFLOW_PODCAST_FEED_TIMEOUT_SECS",
+            20u64,
+        )?),
+        download_timeout: Duration::from_secs(parse_positive_env(
+            "WAVEFLOW_PODCAST_DOWNLOAD_TIMEOUT_SECS",
+            1_800u64,
+        )?),
+        dir: data_dir.join("podcasts"),
+        addresses: crate::portrait::AddressPolicy::Public,
+    })
+}
diff --git a/src/config/scrobbling.rs b/src/config/scrobbling.rs
new file mode 100644
index 00000000..390875d9
--- /dev/null
+++ b/src/config/scrobbling.rs
@@ -0,0 +1,250 @@
+//! Scrobbling as the deployment sees it (RFC-010): how the queue drains, the
+//! destinations the operator declared, and the Last.fm application.
+
+use std::time::Duration;
+
+/// How the server drains what it owes a third party. RFC-010.
+///
+/// Apart from the credentials, which belong to an account and are posed through
+/// the API — decision 9. What is left here is what belongs to the deployment:
+/// how often the queue moves, how many times a failure is worth repeating, and
+/// how long a queue may sit still before the operator should be told it has
+/// stopped.
+#[derive(Debug, Clone, Copy)]
+pub struct ScrobbleLimits {
+    /// How often the drain walks the queue.
+    pub drain_interval: Duration,
+    /// How long one submission may take before the drain stops waiting for it.
+    ///
+    /// A deployment setting rather than a constant because decision 9 says so,
+    /// and it is load-bearing: the drain is a background task, so a destination
+    /// that accepts a connection and then never answers would hold the queue
+    /// still for the life of the process — the silent failure `degraded` exists
+    /// to surface, arriving by the one route that would also stop `degraded`
+    /// from ever being computed.
+    pub request_timeout: Duration,
+    /// How many times one listen may be submitted before it is abandoned and
+    /// counted. Bounded because a queue that never empties is a fault and not a
+    /// state — decision 6.
+    pub max_attempts: u32,
+    /// How long the oldest waiting listen may be waiting before the link is
+    /// reported `degraded`. A valid token with a queue that has not moved for
+    /// hours is the silent failure a durable queue exists to make visible —
+    /// decision 12.
+    pub stale_after: Duration,
+    /// How many listens one drain pass takes. It bounds the pass, never the
+    /// request: decision 11 sends one listen per request whatever this says.
+    pub batch: usize,
+    /// How long a finished entry stays readable before the purge takes it.
+    ///
+    /// `sent`, `rejected`, `abandoned`, `cancelled` and `discarded` only.
+    /// `uncertain` is kept for as long as nobody has answered it, whatever this
+    /// says: taking away an entry that is still asking a person would be
+    /// deciding in their place, which is the one thing decision 13 refuses.
+    ///
+    /// No floor, unlike the library event feed. There, cutting the head off a
+    /// quiet library sends a device back to the snapshot; here nobody resumes a
+    /// cursor, and what a link publishes is read from `pending` and `uncertain`
+    /// rows that no purge touches.
+    pub retention_days: u32,
+}
+
+/// How many times a listen is offered before the queue gives up on it.
+///
+/// Thirty, because the waits grow to an hour and stop there: six doublings from
+/// a minute, then an hour apiece. Thirty submissions therefore span a little
+/// over **a day** of a destination being down, which is the span worth
+/// surviving — a nightly maintenance window, a regional outage, a certificate
+/// nobody renewed until morning.
+///
+/// It was eight, with a comment claiming the same day; eight delivers two hours
+/// and three minutes. The comment was the honest statement of what this is for,
+/// so the number moved to meet it rather than the sentence being trimmed to fit.
+/// Giving up early buys nothing here: abandoning a listen is a permanent hole in
+/// someone's history, and unlike a retry after an ambiguous answer it risks no
+/// duplicate at all. `the_default_attempt_cap_carries_a_listen_across_a_day_of_outage`
+/// keeps this paragraph and the arithmetic from drifting apart again.
+pub const DEFAULT_SCROBBLE_MAX_ATTEMPTS: u32 = 30;
+
+/// The name an instance takes when the operator declared only an address.
+///
+/// It is written into the link like any other name, so the shorthand and the
+/// long form produce the same rows: `WAVEFLOW_SCROBBLE_MALOJA_URL=https://…`
+/// and `…=default=https://…` are one configuration, and an operator who later
+/// adds a second instance does not invalidate the links the first one holds.
+pub const DEFAULT_SCROBBLE_DESTINATION: &str = "default";
+
+/// The Last.fm application an operator registered for this server.
+///
+/// `WAVEFLOW_SCROBBLE_LASTFM_API_KEY` and `WAVEFLOW_SCROBBLE_LASTFM_SECRET`,
+/// both or neither. Without them Last.fm is simply unavailable: RFC-010
+/// decision 4 forbids shipping any provider credential in an AGPL binary, so
+/// these belong to the deployment and to nobody else.
+///
+/// The operator also registers, at Last.fm, the callback URL their
+/// `WAVEFLOW_PUBLIC_URL` produces. Their documentation does not say whether the
+/// `cb` parameter is checked against the registered domain, and betting on a
+/// tolerance nobody promised is not a deployment step — nothing on this side
+/// can verify it either way.
+#[derive(Clone)]
+pub struct LastFmApplication {
+    pub api_key: String,
+    /// Signs every call. Written by hand below rather than derived, because a
+    /// `Config` is printed at startup under `RUST_LOG=debug` and this field is
+    /// the one thing in it that must never appear there.
+    pub secret: String,
+}
+
+impl std::fmt::Debug for LastFmApplication {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("LastFmApplication")
+            .field("api_key", &self.api_key)
+            .field("secret", &"[redacted]")
+            .finish()
+    }
+}
+
+/// One instance of one destination, as the operator declared it.
+#[derive(Debug, Clone)]
+pub struct ScrobbleDestination {
+    pub provider: crate::services::ScrobbleProvider,
+    /// What a member names in a path. Validated against the path alphabet at
+    /// boot — see `scrobblers::validate_destination_name`.
+    pub name: String,
+    /// Where it lives. Validated by `scrobblers::validate_destination`, so it
+    /// carries no credentials, no query and no fragment.
+    pub url: url::Url,
+    /// What a link keeps so it can tell this is still the same machine, even
+    /// when the name has not changed. See
+    /// `scrobblers::destination_fingerprint`.
+    pub fingerprint: String,
+}
+
+/// The instance `Config::for_data_dir` declares. See the comment there.
+pub(super) fn test_destinations() -> Vec<ScrobbleDestination> {
+    // `expect` rather than a fallible signature: the literal is right here, and
+    // a `Config` builder that could fail would push the failure into every
+    // test's first line for no gain.
+    // All three recipients, because an account cannot link a name nobody
+    // declared, and more than one test drives a queue holding two of them —
+    // a destination this process cannot reach must not hold up one it can.
+    //
+    // Declaring a destination is not registering an adapter, and the difference
+    // is what those tests stand on: a Last.fm instance with no application
+    // credentials configured is declared and adapterless, which is a shape a
+    // real deployment has too.
+    [
+        (
+            crate::services::ScrobbleProvider::ListenBrainz,
+            "http://127.0.0.1:1",
+        ),
+        (
+            crate::services::ScrobbleProvider::Maloja,
+            "http://127.0.0.1:2",
+        ),
+        (
+            crate::services::ScrobbleProvider::LastFm,
+            "http://127.0.0.1:3",
+        ),
+    ]
+    .into_iter()
+    .map(|(provider, base)| {
+        let url = crate::scrobblers::validate_destination(base, true)
+            .expect("a loopback destination nothing is listening on");
+        let fingerprint = crate::scrobblers::destination_fingerprint(&url);
+        ScrobbleDestination {
+            provider,
+            name: DEFAULT_SCROBBLE_DESTINATION.to_owned(),
+            url,
+            fingerprint,
+        }
+    })
+    .collect()
+}
+
+/// Reads one recipient's declared instances.
+///
+/// Either a bare URL — one instance, named [`DEFAULT_SCROBBLE_DESTINATION`] —
+/// or a comma-separated list of `name=url`. The two forms produce the same
+/// rows, so adding a second instance later does not rename the first.
+///
+/// **Everything here is refused at boot rather than at the first submission.**
+/// A server that starts with scrobbling quietly switched off by a typo is
+/// exactly the silent failure RFC-010 spends itself making visible. An operator
+/// who wants no adapter for a recipient says so by setting the variable empty,
+/// which is a different thing from misspelling it.
+pub(super) fn parse_destinations(
+    provider: crate::services::ScrobbleProvider,
+    variable: &str,
+    configured: &str,
+    allow_plaintext: bool,
+) -> anyhow::Result<Vec<ScrobbleDestination>> {
+    let configured = configured.trim();
+    if configured.is_empty() {
+        return Ok(Vec::new());
+    }
+    let mut destinations: Vec<ScrobbleDestination> = Vec::new();
+    for entry in configured
+        .split(',')
+        .map(str::trim)
+        .filter(|entry| !entry.is_empty())
+    {
+        // Split on the first `=` — but only when what precedes it could be a
+        // name at all.
+        //
+        // **The obvious version of this leaks a password.** It said the first
+        // `=` cannot occur inside a URL because a scheme has none, which is
+        // true of the scheme and false of everything after it:
+        // `https://wf:pa=ss@host` splits into `https://wf:pa` and `ss@host`,
+        // and the first half then fails the name check and is quoted back in
+        // the error — scheme, account and half the password, in a startup log.
+        // The paragraph below promises the URL never reaches a message, and
+        // this was the path that broke it.
+        //
+        // A name is letters, digits, `-`, `_` and `.`. Neither `:` nor `/` can
+        // appear in one, so their presence before the `=` means the separator
+        // was inside a URL, and the whole entry is read as a bare address. A
+        // mistyped *name* — `al ice=…` — has neither, so it is still reported
+        // by name, which is what an operator needs to see.
+        let named = entry
+            .split_once('=')
+            .filter(|(before, _)| !before.contains([':', '/']));
+        let (name, raw) = match named {
+            Some((name, raw)) => (name.trim(), raw.trim()),
+            None => (DEFAULT_SCROBBLE_DESTINATION, entry),
+        };
+        crate::scrobblers::validate_destination_name(name)
+            .map_err(|error| anyhow::anyhow!("invalid {variable} entry {name:?}: {error}"))?;
+        // **Never the URL itself in the message.** `validate_destination`
+        // refuses a destination carrying credentials, so the one thing this
+        // branch is most likely to be handed is the one thing that must not be
+        // printed: `http://user:secret@host` would land in a startup log, or a
+        // support paste, in full. The name and the variant say enough.
+        let url = crate::scrobblers::validate_destination(raw, allow_plaintext)
+            .map_err(|error| anyhow::anyhow!("invalid {variable} entry {name:?}: {error}"))?;
+        if destinations.iter().any(|existing| existing.name == name) {
+            anyhow::bail!("{variable} declares {name:?} twice");
+        }
+        // Two names for one machine would give a member two ways to reach the
+        // same profile and two links to keep in step, and the second would look
+        // like a different destination in every counter.
+        let fingerprint = crate::scrobblers::destination_fingerprint(&url);
+        if let Some(twin) = destinations
+            .iter()
+            .find(|existing| existing.fingerprint == fingerprint)
+        {
+            anyhow::bail!(
+                "{variable} declares {name:?} and {:?} at the same address",
+                twin.name
+            );
+        }
+        destinations.push(ScrobbleDestination {
+            provider,
+            name: name.to_owned(),
+            url,
+            fingerprint,
+        });
+    }
+    Ok(destinations)
+}
diff --git a/src/config/tests.rs b/src/config/tests.rs
new file mode 100644
index 00000000..51a85102
--- /dev/null
+++ b/src/config/tests.rs
@@ -0,0 +1,409 @@
+use super::access::normalize_public_url;
+use super::access::parse_proxy_addresses;
+use super::from_env::DEFAULT_DB_ACQUIRE_TIMEOUT_MS;
+use super::metadata::parse_metadata_providers;
+use super::{limits::validate_canvas, CanvasLimits};
+use super::{limits::validate_uploads, UploadLimits};
+use super::{scrobbling::parse_destinations, DEFAULT_SCROBBLE_DESTINATION};
+use std::time::Duration;
+
+fn workable() -> UploadLimits {
+    UploadLimits {
+        max_file_bytes: 1024 * 1024,
+        library_quota_bytes: 4 * 1024 * 1024,
+        chunk_bytes: 64 * 1024,
+        batch_limit: 8,
+        sessions_per_user: 2,
+        session_ttl: Duration::from_secs(3600),
+    }
+}
+
+/// RFC-017 decision 2: addresses and blocks alike, and a typo refuses to boot.
+#[test]
+fn trusted_proxies_are_read_strictly() {
+    assert!(parse_proxy_addresses("").unwrap().is_empty());
+    let proxies = parse_proxy_addresses(" 10.0.0.0/8, 192.168.1.5 , ::1 ").unwrap();
+    assert_eq!(proxies.len(), 3);
+    assert!(proxies[0].contains(&"10.1.2.3".parse::<std::net::IpAddr>().unwrap()));
+    assert!(proxies[1].contains(&"192.168.1.5".parse::<std::net::IpAddr>().unwrap()));
+    assert!(!proxies[1].contains(&"192.168.1.6".parse::<std::net::IpAddr>().unwrap()));
+    let mapped = parse_proxy_addresses("::ffff:10.0.0.5").unwrap();
+    assert!(mapped[0].contains(&"10.0.0.5".parse::<std::net::IpAddr>().unwrap()));
+    assert!(parse_proxy_addresses("10.0.0.0/33").is_err());
+    assert!(parse_proxy_addresses("proxy.local").is_err());
+}
+
+/// RFC-011 decision 3: empty is off, and every typo refuses to boot rather
+/// than starting enrichment narrower than the operator wrote.
+#[test]
+fn metadata_providers_are_read_strictly() {
+    use crate::enrichment::Provider;
+
+    assert_eq!(parse_metadata_providers("", false, false).unwrap(), []);
+    assert_eq!(parse_metadata_providers(" , ", false, false).unwrap(), []);
+    assert_eq!(
+        parse_metadata_providers(" lastfm ", true, false).unwrap(),
+        [Provider::LastFm]
+    );
+    // No key ships in the binary: naming the provider without one is a
+    // misconfiguration, not a quiet off.
+    assert!(parse_metadata_providers("lastfm", false, false).is_err());
+    assert!(parse_metadata_providers("lastfm,lastfm", true, false).is_err());
+    assert!(parse_metadata_providers("last.fm", true, false).is_err());
+    // Deezer asks for no key, so none is required of it.
+    assert_eq!(
+        parse_metadata_providers("lastfm, deezer", true, false).unwrap(),
+        [Provider::LastFm, Provider::Deezer]
+    );
+    assert_eq!(
+        parse_metadata_providers("deezer", false, false).unwrap(),
+        [Provider::Deezer]
+    );
+    // TheAudioDB asks for a key of its own (RFC-014 decision 1), and the
+    // Last.fm one does not stand in for it.
+    assert!(parse_metadata_providers("theaudiodb", true, false).is_err());
+    assert_eq!(
+        parse_metadata_providers("deezer, theaudiodb", false, true).unwrap(),
+        [Provider::Deezer, Provider::TheAudioDb]
+    );
+}
+
+/// RFC-024 decision 1: the list is the switch, and a typo refuses to boot
+/// rather than leaving lyrics quietly off.
+#[test]
+fn lyrics_providers_are_read_strictly() {
+    use crate::lrclib::LyricsProvider;
+
+    assert_eq!(super::metadata::parse_lyrics_providers("").unwrap(), []);
+    assert_eq!(super::metadata::parse_lyrics_providers(" , ").unwrap(), []);
+    assert_eq!(
+        super::metadata::parse_lyrics_providers(" lrclib ").unwrap(),
+        [LyricsProvider::Lrclib]
+    );
+    assert!(super::metadata::parse_lyrics_providers("lrclib,lrclib").is_err());
+    assert!(super::metadata::parse_lyrics_providers("lrclib.net").is_err());
+    // An artist provider is not a lyrics provider.
+    assert!(super::metadata::parse_lyrics_providers("lastfm").is_err());
+}
+
+#[test]
+fn upload_limits_that_contradict_each_other_are_refused() {
+    assert!(validate_uploads(&workable()).is_ok());
+
+    // A fragment bigger than the largest file it could belong to.
+    let mut oversized_chunk = workable();
+    oversized_chunk.chunk_bytes = oversized_chunk.max_file_bytes + 1;
+    assert!(validate_uploads(&oversized_chunk).is_err());
+
+    // A file bigger than the whole library may hold.
+    let mut oversized_file = workable();
+    oversized_file.max_file_bytes = oversized_file.library_quota_bytes + 1;
+    assert!(validate_uploads(&oversized_file).is_err());
+
+    // And a fragment this platform could not turn into a body ceiling. The
+    // fallback for that conversion must never be "no ceiling", so the value
+    // has to be refused before it reaches one.
+    if usize::try_from(i64::MAX).is_err() {
+        let mut unrepresentable = workable();
+        unrepresentable.chunk_bytes = i64::MAX;
+        unrepresentable.max_file_bytes = i64::MAX;
+        unrepresentable.library_quota_bytes = i64::MAX;
+        assert!(validate_uploads(&unrepresentable).is_err());
+    }
+}
+
+#[test]
+fn canvas_limits_that_contradict_each_other_are_refused() {
+    let workable = CanvasLimits {
+        max_bytes: 256 * 1024,
+        max_duration_secs: 15,
+        library_quota_bytes: 1024 * 1024,
+    };
+    assert!(validate_canvas(&workable).is_ok());
+
+    // A single canvas larger than the whole library may hold: the first one
+    // placed would be refused by a quota it can never fit under, which is a
+    // misconfiguration rather than a verdict.
+    let mut oversized = workable;
+    oversized.max_bytes = oversized.library_quota_bytes + 1;
+    assert!(validate_canvas(&oversized).is_err());
+
+    // And a ceiling this platform cannot represent, for the same reason the
+    // upload chunk size is refused: every fallback for a ceiling is wrong.
+    if usize::try_from(i64::MAX).is_err() {
+        let unrepresentable = CanvasLimits {
+            max_bytes: i64::MAX,
+            max_duration_secs: 15,
+            library_quota_bytes: i64::MAX,
+        };
+        assert!(validate_canvas(&unrepresentable).is_err());
+    }
+}
+
+#[test]
+fn public_url_is_reduced_to_a_safe_http_origin() {
+    assert_eq!(
+        normalize_public_url("https://music.example.com:8443/").unwrap(),
+        "https://music.example.com:8443"
+    );
+    for invalid in [
+        "ftp://music.example.com",
+        "https://user:secret@music.example.com",
+        "https://music.example.com/waveflow",
+        "https://music.example.com?token=secret",
+    ] {
+        assert!(normalize_public_url(invalid).is_err(), "{invalid}");
+    }
+}
+
+/// A destination that cannot be used is never quoted back.
+///
+/// `validate_destination` refuses a URL carrying credentials, so the value
+/// this error branch is most likely to be holding is precisely the one that
+/// must not be printed — and a startup error goes to a log, a terminal, and
+/// whatever a person pastes into an issue. The repository's rule about
+/// secrets has no exception for an error path.
+///
+/// It used to live in `tests/scrobbling.rs` against `initialize`, which is
+/// where the guard used to be. Named destinations moved the refusal here,
+/// to the reading of the variable, and the test follows the guard rather
+/// than staying where it was and passing for another reason.
+#[test]
+fn a_refused_destination_is_never_quoted_back_with_its_credentials() {
+    // A private host, so the plaintext rule lets this through and the
+    // credential rule is what refuses it. That is the path carrying a
+    // password.
+    let refused = parse_destinations(
+        crate::services::ScrobbleProvider::Maloja,
+        "WAVEFLOW_SCROBBLE_MALOJA_URL",
+        "house=http://wf-user:hunter2@10.0.0.2",
+        true,
+    )
+    .expect_err("a destination carrying credentials must be refused");
+    let said = format!("{refused:#}");
+
+    // **Named, never quoted.** An earlier version of this loop put the
+    // secret and the whole error into the assertion message, and CodeQL was
+    // right to call that a cleartext write of a credential — in the one
+    // test whose entire subject is that credentials must not be written.
+    // What a failure here needs to say is *which* part came back, not the
+    // part itself.
+    for (part, secret) in [
+        ("the password", "hunter2"),
+        ("the account", "wf-user"),
+        ("the host", "10.0.0.2"),
+    ] {
+        assert!(
+            !said.contains(secret),
+            "the startup error quoted {part} back from the destination"
+        );
+    }
+    // And it still says enough to be fixed by the person who typed it:
+    // which variable, which name, and what was wrong with it. Printing
+    // `said` is safe here and only here — the loop above has just
+    // established that it carries none of the three.
+    assert!(
+        said.contains("credentials"),
+        "the error must name the fault: {said}"
+    );
+    assert!(
+        said.contains("house") && said.contains("WAVEFLOW_SCROBBLE_MALOJA_URL"),
+        "the error must name the entry that is wrong: {said}"
+    );
+
+    // **And a password containing `=` does not become the name.** The first
+    // version of the parser split on the first `=` wherever it fell, so
+    // this entry became the name `http://wf-user:pa` and the address
+    // `ss@10.0.0.2` — and the name is what the refusal quotes back. Half a
+    // password in a startup log, from the one paragraph that promises the
+    // opposite. Nothing about the shape of this entry is unusual; `=` is an
+    // ordinary character in a generated password.
+    let refused = parse_destinations(
+        crate::services::ScrobbleProvider::Maloja,
+        "WAVEFLOW_SCROBBLE_MALOJA_URL",
+        "http://wf-user:pa=ss@10.0.0.2",
+        true,
+    )
+    .expect_err("a destination carrying credentials must be refused");
+    let said = format!("{refused:#}");
+    for (part, secret) in [
+        ("the password", "pa=ss"),
+        ("part of the password", "pa"),
+        ("the account", "wf-user"),
+        ("the host", "10.0.0.2"),
+    ] {
+        assert!(
+            !said.contains(secret),
+            "the startup error quoted {part} back from the destination"
+        );
+    }
+    assert!(
+        said.contains("credentials"),
+        "the error must still name the fault"
+    );
+}
+
+/// A mistyped *name* is still reported by name.
+///
+/// The guard above reads an entry as a bare address whenever the text
+/// before the `=` could not be a name. That must not swallow the ordinary
+/// typo it exists beside: a name with a space in it carries neither `:` nor
+/// `/`, so it is still a name, and the operator is told which one.
+#[test]
+fn a_mistyped_name_is_still_named_in_the_refusal() {
+    let refused = parse_destinations(
+        crate::services::ScrobbleProvider::Maloja,
+        "WAVEFLOW_SCROBBLE_MALOJA_URL",
+        "al ice=https://host/alice",
+        false,
+    )
+    .expect_err("a name with a space must be refused");
+    let said = format!("{refused:#}");
+    assert!(said.contains("al ice"), "{said}");
+}
+
+/// Two spellings of one machine are one destination.
+///
+/// The trailing slash is the one an editor adds without anybody deciding
+/// to, and a fingerprint that moved with it would break every link on a
+/// server at the first restart after a configuration tidy-up.
+#[test]
+fn a_trailing_slash_does_not_move_a_destination() {
+    let bare = parse_destinations(
+        crate::services::ScrobbleProvider::Maloja,
+        "WAVEFLOW_SCROBBLE_MALOJA_URL",
+        "https://host/maloja",
+        false,
+    )
+    .expect("a valid destination");
+    let slashed = parse_destinations(
+        crate::services::ScrobbleProvider::Maloja,
+        "WAVEFLOW_SCROBBLE_MALOJA_URL",
+        "https://host/maloja/",
+        false,
+    )
+    .expect("a valid destination");
+    assert_eq!(bare[0].fingerprint, slashed[0].fingerprint);
+
+    // And the path is *part* of the identity, unlike an origin. Two tenants
+    // on one host are two destinations, and giving them one fingerprint
+    // would let the identity guard wave through the likeliest move there
+    // is.
+    let other_tenant = parse_destinations(
+        crate::services::ScrobbleProvider::Maloja,
+        "WAVEFLOW_SCROBBLE_MALOJA_URL",
+        "https://host/maloja-two",
+        false,
+    )
+    .expect("a valid destination");
+    assert_ne!(bare[0].fingerprint, other_tenant[0].fingerprint);
+}
+
+/// A recipient may carry several instances, and neither name nor address
+/// may repeat.
+#[test]
+fn a_recipient_carries_several_instances_each_named_once() {
+    let declared = parse_destinations(
+        crate::services::ScrobbleProvider::Maloja,
+        "WAVEFLOW_SCROBBLE_MALOJA_URL",
+        "alice=https://host/alice, bob=https://host/bob",
+        false,
+    )
+    .expect("two instances");
+    assert_eq!(declared.len(), 2);
+    assert_eq!(declared[0].name, "alice");
+    assert_eq!(declared[1].name, "bob");
+
+    // A bare URL is the shorthand for one instance called `default`, so the
+    // two spellings produce the same row and adding a second instance later
+    // does not rename the first.
+    let shorthand = parse_destinations(
+        crate::services::ScrobbleProvider::Maloja,
+        "WAVEFLOW_SCROBBLE_MALOJA_URL",
+        "https://host/alice",
+        false,
+    )
+    .expect("one instance");
+    assert_eq!(shorthand[0].name, DEFAULT_SCROBBLE_DESTINATION);
+
+    // Two names for one machine would give a member two links to keep in
+    // step with one profile, and each would look like a separate
+    // destination in every counter.
+    assert!(parse_destinations(
+        crate::services::ScrobbleProvider::Maloja,
+        "WAVEFLOW_SCROBBLE_MALOJA_URL",
+        "alice=https://host/alice, ALICE=https://host/alice/",
+        false,
+    )
+    .is_err());
+
+    // And one name for two machines is not a configuration either.
+    assert!(parse_destinations(
+        crate::services::ScrobbleProvider::Maloja,
+        "WAVEFLOW_SCROBBLE_MALOJA_URL",
+        "alice=https://host/alice, alice=https://host/bob",
+        false,
+    )
+    .is_err());
+}
+
+/// A name that cannot be a path segment is refused where it is written.
+#[test]
+fn a_destination_name_is_bounded_by_what_crosses_a_path() {
+    for refused in [
+        ".",
+        "..",
+        "al ice",
+        "alice/bob",
+        "alice%2f",
+        "",
+        &"a".repeat(65),
+    ] {
+        assert!(
+            parse_destinations(
+                crate::services::ScrobbleProvider::Maloja,
+                "WAVEFLOW_SCROBBLE_MALOJA_URL",
+                &format!("{refused}=https://host/alice"),
+                false,
+            )
+            .is_err(),
+            "{refused:?} must not become a path segment"
+        );
+    }
+    for accepted in ["alice", "a-b_c.d", "ALICE2", &"a".repeat(64)] {
+        assert!(
+            parse_destinations(
+                crate::services::ScrobbleProvider::Maloja,
+                "WAVEFLOW_SCROBBLE_MALOJA_URL",
+                &format!("{accepted}=https://host/alice"),
+                false,
+            )
+            .is_ok(),
+            "{accepted:?} must be usable"
+        );
+    }
+}
+
+/// The test fixture waits longer for a cold database than a deployment.
+///
+/// `Database::open` creates the file and establishes the connection the
+/// migrations run on, and a test target boots one whole server per test,
+/// so several cold databases are created at once on a machine that is
+/// also compiling. Three targets — uploads, media, scrobbling — have each
+/// failed that acquire on the Windows runner at different times, naming
+/// whichever test was unlucky and looking like three unrelated flakes.
+///
+/// Pinned because the repair is one literal wide: a later tidy-up that
+/// gives the fixture the production budget back restores a lottery whose
+/// losing ticket is drawn in a different file every time.
+#[test]
+fn the_test_fixture_waits_longer_for_a_cold_database_than_a_deployment() {
+    let fixture = super::Config::for_data_dir(std::path::PathBuf::from("data"));
+    let deployment = Duration::from_millis(DEFAULT_DB_ACQUIRE_TIMEOUT_MS);
+    assert!(
+        fixture.db_acquire_timeout > deployment,
+        "the fixture waits {:?}, a deployment {deployment:?} — a test boots a server per \
+         test and must not inherit a budget tuned for one warm server",
+        fixture.db_acquire_timeout
+    );
+}

From 2c690c4f5c76c6b55ed61f1156064cf47f2bb1cd Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Mon, 26 Oct 2026 09:51:52 +0100
Subject: [PATCH 4/4] refactor(cli): split the command line into arguments and
 one file per command family

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 src/cli/account.rs  |  109 +++
 src/cli/args.rs     |  434 ++++++++++++
 src/cli/database.rs |   68 ++
 src/cli/key.rs      |  387 +++++++++++
 src/cli/library.rs  |  406 +++++++++++
 src/cli/mod.rs      | 1568 +------------------------------------------
 src/cli/scrobble.rs |  190 ++++++
 src/cli/tests.rs    |   22 +
 8 files changed, 1645 insertions(+), 1539 deletions(-)
 create mode 100644 src/cli/account.rs
 create mode 100644 src/cli/args.rs
 create mode 100644 src/cli/database.rs
 create mode 100644 src/cli/key.rs
 create mode 100644 src/cli/library.rs
 create mode 100644 src/cli/scrobble.rs
 create mode 100644 src/cli/tests.rs

diff --git a/src/cli/account.rs b/src/cli/account.rs
new file mode 100644
index 00000000..5956f1e6
--- /dev/null
+++ b/src/cli/account.rs
@@ -0,0 +1,109 @@
+//! Accounts and the credentials minted for them: `account`, `credential` and
+//! `token`.
+
+use anyhow::Context;
+
+use super::{
+    read_secret_env, require_admin, validate_username, CreateAccountArgs, CreateTokenArgs,
+    RevokeCredentialArgs, SetCredentialArgs,
+};
+use crate::{
+    authentication::now_ms,
+    database::{AccountRole, Database},
+    security, AppState,
+};
+
+pub(super) async fn create_account(
+    db: &Database,
+    args: CreateAccountArgs,
+    role: AccountRole,
+) -> anyhow::Result<()> {
+    validate_username(&args.username)?;
+    let password = read_secret_env(&args.password_env)?;
+    let password_hash = tokio::task::spawn_blocking(move || security::hash_password(&password))
+        .await
+        .context("password worker failed")??;
+    let id = db
+        .create_account(&args.username, &password_hash, role, now_ms())
+        .await
+        .context("create account")?;
+    println!("Created {} account {} ({id})", role.as_str(), args.username);
+    Ok(())
+}
+
+pub(super) async fn set_credential(
+    db: &Database,
+    secret_box: &security::SecretBox,
+    args: SetCredentialArgs,
+) -> anyhow::Result<()> {
+    let actor = require_admin(db, &args.actor).await?;
+    let user = db
+        .account_by_username(&args.username)
+        .await?
+        .with_context(|| format!("account not found: {}", args.username))?;
+    let password = read_secret_env(&args.password_env)?;
+    if password.len() < 12 {
+        anyhow::bail!("Subsonic password must contain at least 12 characters");
+    }
+    let encrypted = secret_box.encrypt(password.as_bytes())?;
+    let api_key = security::generate_token("wfsk_");
+    let api_key_hash = security::token_hash(&api_key);
+    db.set_subsonic_credential(actor.id, user.id, &encrypted, &api_key_hash, now_ms())
+        .await?;
+    // The API key goes to standard output on its own, and everything a person
+    // reads goes to standard error. That way `set-credential … > key` yields the
+    // key and nothing else, and an operator never has to lift a secret out of a
+    // scrollback that then keeps it. Interactively both streams still land on
+    // the same terminal, so this reads the way it always did.
+    eprintln!("Subsonic credential updated for {}", args.username);
+    eprintln!("API key (shown once, on standard output):");
+    println!("{api_key}");
+    Ok(())
+}
+
+pub(super) async fn revoke_credential(
+    db: &Database,
+    args: RevokeCredentialArgs,
+) -> anyhow::Result<()> {
+    let actor = require_admin(db, &args.actor).await?;
+    let user = db
+        .account_by_username(&args.username)
+        .await?
+        .with_context(|| format!("account not found: {}", args.username))?;
+    if !db
+        .revoke_subsonic_credential(actor.id, user.id, now_ms())
+        .await?
+    {
+        anyhow::bail!("no Subsonic credential exists for {}", args.username);
+    }
+    println!("Revoked Subsonic credential for {}", args.username);
+    Ok(())
+}
+
+/// Bootstraps a token on an instance with no administrator session yet.
+///
+/// Issuing one is also an HTTP route now, so this goes through the same
+/// domain service rather than writing the row itself: a token minted here and
+/// one minted over the API must carry the same validation and the same audit
+/// trail, which is exactly what two copies of the insert would not guarantee.
+pub(super) async fn create_token(state: &AppState, args: CreateTokenArgs) -> anyhow::Result<()> {
+    let actor = require_admin(&state.db, &args.actor).await?;
+    let (record, token) = state
+        .services
+        .create_api_token(
+            actor.id,
+            // The command line holds the whole account authority: it is a
+            // shell on the host, not a credential that could have been
+            // narrowed.
+            &[],
+            &args.username,
+            &args.name,
+            &args.scopes,
+        )
+        .await?;
+    // Standard output carries the token alone; see `set_credential` for why.
+    eprintln!("Created API token {} for {}", record.id, args.username);
+    eprintln!("Token (shown once, on standard output):");
+    println!("{token}");
+    Ok(())
+}
diff --git a/src/cli/args.rs b/src/cli/args.rs
new file mode 100644
index 00000000..8fbd6f74
--- /dev/null
+++ b/src/cli/args.rs
@@ -0,0 +1,434 @@
+//! The command line as clap reads it: every command, subcommand and argument.
+
+use std::path::PathBuf;
+
+use clap::{Args, Parser, Subcommand};
+
+#[derive(Debug, Parser)]
+#[command(name = "waveflow-server", version, about)]
+pub struct Cli {
+    #[command(subcommand)]
+    pub command: Option<Command>,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum Command {
+    /// Run the HTTP server (the default when no command is supplied).
+    Serve,
+    /// Manage local accounts.
+    Account {
+        #[command(subcommand)]
+        command: AccountCommand,
+    },
+    /// Register libraries and manage their members.
+    Library {
+        #[command(subcommand)]
+        command: LibraryCommand,
+    },
+    /// Manage per-user Subsonic credentials.
+    Credential {
+        #[command(subcommand)]
+        command: CredentialCommand,
+    },
+    /// Create long-lived native API tokens.
+    Token {
+        #[command(subcommand)]
+        command: TokenCommand,
+    },
+    /// Link an account to a scrobbling destination, or read its queue.
+    ///
+    /// The same gestures the native API offers, for an operator preparing a
+    /// server nobody has opened a browser on yet — exactly the reason the
+    /// dedicated Subsonic password has a command here too.
+    Scrobble {
+        #[command(subcommand)]
+        command: ScrobbleCommand,
+    },
+    /// Check the SQLite database integrity.
+    Database {
+        #[command(subcommand)]
+        command: DatabaseCommand,
+    },
+    /// Replace the instance key, with or without the old one in hand.
+    ///
+    /// Both run before the server opens SQLite, because the boot they exist to
+    /// unblock is the one that aborts on a mismatched pair.
+    Key {
+        #[command(subcommand)]
+        command: KeyCommand,
+    },
+}
+
+#[derive(Debug, Subcommand)]
+pub enum AccountCommand {
+    /// Create the first or an additional administrator.
+    CreateAdmin(CreateAccountArgs),
+    /// Create a regular account.
+    CreateUser(CreateAccountArgs),
+}
+
+#[derive(Debug, Args)]
+pub struct CreateAccountArgs {
+    #[arg(long)]
+    pub(super) username: String,
+    /// Environment variable containing the password. The value never appears in argv.
+    #[arg(long, default_value = "WAVEFLOW_ACCOUNT_PASSWORD")]
+    pub(super) password_env: String,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum LibraryCommand {
+    Add(AddLibraryArgs),
+    SetMember(SetMemberArgs),
+    RemoveMember(RemoveMemberArgs),
+    SetUploads(SetUploadsArgs),
+    SetCanvas(SetCanvasArgs),
+    /// Give a library a new name.
+    Rename(RenameLibraryArgs),
+    /// Point a library at a new root, then scan it. Tracks are matched by
+    /// their path relative to the root, so a tree moved intact keeps them all.
+    SetPath(SetPathArgs),
+    /// Follow symbolic links whose target stays inside the library, or stop
+    /// following them, then scan it.
+    SetLinks(SetLinksArgs),
+    /// Remove a library from the catalogue, with every track, album and
+    /// artist in it and everything that hangs off them for every member.
+    /// Nothing is removed from the disk.
+    Delete(DeleteLibraryArgs),
+    /// List the tracks whose file the scans can no longer find.
+    Unavailable(UnavailableArgs),
+    /// Purge missing tracks: out of sight at once, and removed from the
+    /// catalogue for good once the grace window (`WAVEFLOW_PURGE_GRACE_HOURS`)
+    /// has passed, or at once when it is zero.
+    Purge(PurgeArgs),
+    /// Take a purge back, for tracks still within the grace window.
+    Restore(PurgeArgs),
+    /// Watch the library for changes, or stop watching it.
+    SetWatch(SetWatchArgs),
+}
+
+#[derive(Debug, Args)]
+pub struct SetWatchArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) library_id: uuid::Uuid,
+    /// `true` to watch, `false` to leave the library to the periodic scan.
+    #[arg(long, action = clap::ArgAction::Set)]
+    pub(super) watch: bool,
+}
+
+#[derive(Debug, Args)]
+pub struct RenameLibraryArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) library_id: uuid::Uuid,
+    #[arg(long)]
+    pub(super) name: String,
+}
+
+#[derive(Debug, Args)]
+pub struct SetPathArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) library_id: uuid::Uuid,
+    #[arg(long)]
+    pub(super) path: PathBuf,
+}
+
+/// Off until an operator says otherwise: without `--follow`, links are not
+/// followed.
+#[derive(Debug, Args)]
+pub struct SetLinksArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) library_id: uuid::Uuid,
+    #[arg(long)]
+    pub(super) follow: bool,
+}
+
+#[derive(Debug, Args)]
+pub struct DeleteLibraryArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) library_id: uuid::Uuid,
+    /// The library's current name, typed out: the deletion goes ahead only
+    /// when it matches.
+    #[arg(long)]
+    pub(super) confirm: String,
+}
+
+#[derive(Debug, Args)]
+pub struct UnavailableArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) library_id: uuid::Uuid,
+}
+
+/// Exactly one of `--all` and `--track-id`.
+#[derive(Debug, Args)]
+pub struct PurgeArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) library_id: uuid::Uuid,
+    /// Every missing track of the library.
+    #[arg(long, conflicts_with = "track_id")]
+    pub(super) all: bool,
+    /// One missing track; repeat for several.
+    #[arg(long = "track-id")]
+    pub(super) track_id: Vec<uuid::Uuid>,
+}
+
+#[derive(Debug, Args)]
+pub struct AddLibraryArgs {
+    #[arg(long)]
+    pub(super) owner: String,
+    #[arg(long)]
+    pub(super) name: String,
+    #[arg(long)]
+    pub(super) path: PathBuf,
+    #[arg(long, default_value = "private")]
+    pub(super) visibility: String,
+}
+
+#[derive(Debug, Args)]
+pub struct SetMemberArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) library_id: uuid::Uuid,
+    #[arg(long)]
+    pub(super) username: String,
+    #[arg(long, default_value = "listener")]
+    pub(super) role: String,
+}
+
+/// Whether a library will receive files at all.
+///
+/// Off until an operator says otherwise: upgrading a server must not turn a
+/// read-only installation into one that grows.
+#[derive(Debug, Args)]
+pub struct SetUploadsArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) library_id: uuid::Uuid,
+    #[arg(long)]
+    pub(super) accept: bool,
+}
+
+/// Off until an operator says otherwise, and separate from the upload flag on
+/// purpose: a server that refuses to grow in audio may still take a few hundred
+/// kilobytes of video loop, which is the most common installation there is.
+#[derive(Debug, Args)]
+pub struct SetCanvasArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) library_id: uuid::Uuid,
+    #[arg(long)]
+    pub(super) accept: bool,
+}
+
+#[derive(Debug, Args)]
+pub struct RemoveMemberArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) library_id: uuid::Uuid,
+    #[arg(long)]
+    pub(super) username: String,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum CredentialCommand {
+    Set(SetCredentialArgs),
+    Revoke(RevokeCredentialArgs),
+}
+
+#[derive(Debug, Args)]
+pub struct SetCredentialArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) username: String,
+    /// Environment variable containing the dedicated Subsonic password.
+    #[arg(long, default_value = "WAVEFLOW_SUBSONIC_PASSWORD")]
+    pub(super) password_env: String,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum ScrobbleCommand {
+    /// Authorise an account at a destination, replacing any authorisation it
+    /// already had there.
+    Link(LinkScrobbleArgs),
+    /// Begin a Last.fm authorisation from a machine with no browser. Prints
+    /// the address to open and the token to bring back to `exchange`.
+    Authorize(AuthorizeLastFmArgs),
+    /// Finish one: turn the approved request token into a link.
+    Exchange(ExchangeLastFmArgs),
+    /// Withdraw it. Listens already queued under it stay queued under it and
+    /// are never sent to whatever is linked next.
+    Unlink(UnlinkScrobbleArgs),
+    /// What each of an account's links is doing.
+    Status(ScrobbleStatusArgs),
+}
+
+#[derive(Debug, Args)]
+pub struct LinkScrobbleArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) username: String,
+    /// `listenbrainz`, `maloja` or `lastfm`.
+    #[arg(long)]
+    pub(super) provider: String,
+    /// Which declared instance of it. Named rather than defaulted: an operator
+    /// running two Maloja instances must say which one this account submits to,
+    /// and a silent default would pick one for them.
+    #[arg(long)]
+    pub(super) destination: String,
+    /// Environment variable containing the token. The value never appears in
+    /// argv, for the same reason the account password does not: a shell history
+    /// and a process list are both readable by people this credential is not
+    /// for.
+    #[arg(long, default_value = "WAVEFLOW_SCROBBLE_TOKEN")]
+    pub(super) token_env: String,
+}
+
+/// Last.fm hands out no secret a person can paste, so `link` has nothing to be
+/// given for it. These two are `link` for that recipient, split where the
+/// person has to leave and come back.
+#[derive(Debug, Args)]
+pub struct AuthorizeLastFmArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) username: String,
+    /// Which declared Last.fm instance, for the reason `link` takes one.
+    #[arg(long)]
+    pub(super) destination: String,
+}
+
+#[derive(Debug, Args)]
+pub struct ExchangeLastFmArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) username: String,
+    #[arg(long)]
+    pub(super) destination: String,
+    /// Environment variable holding the token `authorize` printed. Out of
+    /// `argv` for the reason `link`'s secret is: a shell history and a process
+    /// list are both readable by people this is not for, and whoever exchanges
+    /// this token first is who the session ends up belonging to.
+    #[arg(long, default_value = ExchangeLastFmArgs::TOKEN_ENV)]
+    pub(super) token_env: String,
+}
+
+impl ExchangeLastFmArgs {
+    /// Named once, because `authorize` prints it and this declares it — and a
+    /// default spelled in two places is a default that eventually disagrees
+    /// with the instructions for using it.
+    pub(super) const TOKEN_ENV: &'static str = "WAVEFLOW_LASTFM_TOKEN";
+}
+
+#[derive(Debug, Args)]
+pub struct UnlinkScrobbleArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) username: String,
+    #[arg(long)]
+    pub(super) provider: String,
+    /// Which declared instance of it, for the same reason `link` takes one.
+    #[arg(long)]
+    pub(super) destination: String,
+}
+
+#[derive(Debug, Args)]
+pub struct ScrobbleStatusArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) username: String,
+}
+
+#[derive(Debug, Args)]
+pub struct RevokeCredentialArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) username: String,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum TokenCommand {
+    Create(CreateTokenArgs),
+}
+
+#[derive(Debug, Args)]
+pub struct CreateTokenArgs {
+    #[arg(long)]
+    pub(super) actor: String,
+    #[arg(long)]
+    pub(super) username: String,
+    #[arg(long)]
+    pub(super) name: String,
+    #[arg(long, value_delimiter = ',')]
+    pub(super) scopes: Vec<String>,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum DatabaseCommand {
+    Check,
+    /// Create a coherent SQLite + instance-key backup bundle.
+    Backup(BackupArgs),
+    /// Restore a backup bundle before opening SQLite.
+    Restore(RestoreArgs),
+    /// Read every file again on the next scan of every library, skipping
+    /// nothing (RFC-018): for a file rewritten in place with its size and
+    /// modification time both kept, which an ordinary scan does not open.
+    RescanFull,
+}
+
+#[derive(Debug, Args)]
+pub struct BackupArgs {
+    #[arg(long)]
+    pub output: PathBuf,
+}
+
+#[derive(Debug, Args)]
+pub struct RestoreArgs {
+    #[arg(long)]
+    pub input: PathBuf,
+}
+
+/// Two commands rather than one command and a flag.
+///
+/// They are not two ways of doing the same thing: `rotate` carries every
+/// encrypted value onto the new key, `adopt` deletes the ones that can no
+/// longer be read. Naming them apart is what keeps the second from being one
+/// mistyped flag away from the first — and `adopt` refuses outright on a
+/// database whose key is sitting next to it, since that is a rotation.
+#[derive(Debug, Subcommand)]
+pub enum KeyCommand {
+    /// Mint a new instance key and move every encrypted value onto it.
+    Rotate(KeyArgs),
+    /// Take a database over under a new key, discarding what the old one protected.
+    Adopt(KeyArgs),
+}
+
+#[derive(Debug, Args)]
+pub struct KeyArgs {
+    /// Do the work. Without it the command reads the database, prints what the
+    /// change costs, and stops.
+    #[arg(long)]
+    pub confirm: bool,
+}
diff --git a/src/cli/database.rs b/src/cli/database.rs
new file mode 100644
index 00000000..263b6140
--- /dev/null
+++ b/src/cli/database.rs
@@ -0,0 +1,68 @@
+//! `database backup` and `database restore`: the database and its key, as one
+//! bundle.
+
+use super::{BackupArgs, RestoreArgs};
+use crate::{database::Database, security, AppState};
+
+pub(super) async fn backup(state: &AppState, args: BackupArgs) -> anyhow::Result<()> {
+    if args.output.exists() {
+        anyhow::bail!("backup output already exists: {}", args.output.display());
+    }
+    tokio::fs::create_dir_all(&args.output).await?;
+    let database = args.output.join("waveflow.db");
+    state.db.backup_to(&database).await?;
+    tokio::fs::copy(&state.instance_key_path, args.output.join("instance.key")).await?;
+    if !Database::check_file(&database).await? {
+        anyhow::bail!("created backup failed integrity check");
+    }
+    let backup_key = tokio::fs::read(args.output.join("instance.key")).await?;
+    if !Database::check_file_instance_key(&database, &security::bytes_hash(&backup_key)).await? {
+        anyhow::bail!("created backup database and instance.key do not match");
+    }
+    println!("Backup created at {}", args.output.display());
+    Ok(())
+}
+
+pub async fn restore(config: &crate::Config, args: RestoreArgs) -> anyhow::Result<()> {
+    let source_db = args.input.join("waveflow.db");
+    let source_key = args.input.join("instance.key");
+    if !Database::check_file(&source_db).await? {
+        anyhow::bail!("backup SQLite integrity check failed");
+    }
+    let source_key_bytes = tokio::fs::read(&source_key).await?;
+    if source_key_bytes.len() != 32 {
+        anyhow::bail!("backup instance.key must contain exactly 32 bytes");
+    }
+    if !Database::check_file_instance_key(&source_db, &security::bytes_hash(&source_key_bytes))
+        .await?
+    {
+        anyhow::bail!("backup database and instance.key do not match");
+    }
+    tokio::fs::create_dir_all(&config.data_dir).await?;
+    let suffix = uuid::Uuid::new_v4();
+    let staged_db = config.data_dir.join(format!(".restore-{suffix}.db"));
+    let staged_key = config.data_dir.join(format!(".restore-{suffix}.key"));
+    tokio::fs::copy(&source_db, &staged_db).await?;
+    tokio::fs::copy(&source_key, &staged_key).await?;
+    if !Database::check_file(&staged_db).await? {
+        anyhow::bail!("staged SQLite restore failed integrity check");
+    }
+    let recovery = config.data_dir.join(format!(
+        "pre-restore-{}",
+        chrono::Utc::now().timestamp_millis()
+    ));
+    tokio::fs::create_dir_all(&recovery).await?;
+    if config.database_path.exists() {
+        tokio::fs::rename(&config.database_path, recovery.join("waveflow.db")).await?;
+    }
+    if config.instance_key_path.exists() {
+        tokio::fs::rename(&config.instance_key_path, recovery.join("instance.key")).await?;
+    }
+    tokio::fs::rename(&staged_db, &config.database_path).await?;
+    tokio::fs::rename(&staged_key, &config.instance_key_path).await?;
+    println!(
+        "Backup restored; previous files are recoverable from {}",
+        recovery.display()
+    );
+    Ok(())
+}
diff --git a/src/cli/key.rs b/src/cli/key.rs
new file mode 100644
index 00000000..a1039d65
--- /dev/null
+++ b/src/cli/key.rs
@@ -0,0 +1,387 @@
+//! `key rotate` and `key adopt`: replacing the instance key, with or without
+//! the old one in hand, after copying the pair aside.
+
+use std::path::{Path, PathBuf};
+
+use anyhow::Context;
+use sqlx::Connection;
+
+use super::{KeyArgs, KeyCommand};
+use crate::{
+    authentication::now_ms,
+    database::{Database, KeyMaterial, Rekey, SchemaState},
+    security,
+};
+
+pub async fn key(config: &crate::Config, command: KeyCommand) -> anyhow::Result<()> {
+    match command {
+        KeyCommand::Rotate(args) => rotate_key(config, args).await,
+        KeyCommand::Adopt(args) => adopt_key(config, args).await,
+    }
+}
+
+/// The key file as it stands, or nothing where there is no file.
+///
+/// Unvalidated on purpose. `rotate` has to open the thing and answers for it
+/// itself; `adopt` only ever compares a fingerprint, and a file of the wrong
+/// length cannot match one. Refusing it here would turn away exactly the
+/// operator `adopt` exists for — the one holding something that is no longer
+/// a key.
+fn read_instance_key(config: &crate::Config) -> anyhow::Result<Option<Vec<u8>>> {
+    match std::fs::read(&config.instance_key_path) {
+        Ok(bytes) => Ok(Some(bytes)),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(error) => Err(error.into()),
+    }
+}
+
+/// Which of the two commands is speaking.
+///
+/// Wording only. What each one *does* is the `Rekey` it hands to
+/// [`install_new_key`]; this decides nothing, and exists so the two inventories
+/// sit side by side instead of drifting apart in two copies.
+#[derive(Clone, Copy)]
+enum Intent {
+    Rotate,
+    Adopt,
+}
+
+/// The database, held alone — and not migrated.
+///
+/// The migration belongs to the half that has been confirmed. A reading says
+/// it changes nothing, and applying a migration is a change: it rewrites
+/// `_sqlx_migrations` and whatever the migration itself does, on a database
+/// the operator has not yet agreed to touch. [`Database::schema_state`] is
+/// asked instead, and each command answers for what it finds.
+async fn open_for_key_change(
+    config: &crate::Config,
+) -> anyhow::Result<(sqlx::SqliteConnection, SchemaState)> {
+    let mut connection =
+        Database::open_alone(&config.database_path, config.sqlite_busy_timeout).await?;
+    let schema = Database::schema_state(&mut connection).await?;
+    if schema == SchemaState::Empty {
+        anyhow::bail!(
+            "{} holds no WaveFlow schema; start the server once and it will create one",
+            config.database_path.display()
+        );
+    }
+    Ok((connection, schema))
+}
+
+async fn rotate_key(config: &crate::Config, args: KeyArgs) -> anyhow::Result<()> {
+    let Some(old_bytes) = read_instance_key(config)? else {
+        anyhow::bail!(
+            "there is no {} to rotate from; if it is gone for good, `key adopt` takes the database over under a new one",
+            config.instance_key_path.display()
+        );
+    };
+    let old_key = security::SecretBox::from_key_bytes(&old_bytes).with_context(|| {
+        format!(
+            "{} is not a usable key; if the real one is gone, `key adopt` takes the database over under a new one",
+            config.instance_key_path.display()
+        )
+    })?;
+    let (mut connection, schema) = open_for_key_change(config).await?;
+    if let Some(stored) = Database::stored_key_fingerprint(&mut connection).await? {
+        if !security::constant_time_bytes_eq(&stored, &security::bytes_hash(&old_bytes)) {
+            anyhow::bail!(
+                "the key beside this database is not the one it was bound to; restore the matching pair, or `key adopt` if the real one is gone"
+            );
+        }
+    }
+    if !args.confirm {
+        return report_reading(&mut connection, schema, Intent::Rotate, config).await;
+    }
+    let recovery = copy_the_pair_aside(config, &mut connection).await?;
+    Database::migrate_on(&mut connection).await?;
+    let material = Database::key_material(&mut connection).await?;
+    print_inventory(Intent::Rotate, &config.database_path, &material);
+    let moved = install_new_key(config, connection, Rekey::Reencrypt(&old_key)).await?;
+    println!(
+        "Done. {} Subsonic credential(s) and {} scrobbling link(s) moved to the new key; {} share(s) re-addressed.",
+        moved.subsonic_credentials, moved.scrobble_links, moved.shares
+    );
+    report_done(&recovery);
+    Ok(())
+}
+
+async fn adopt_key(config: &crate::Config, args: KeyArgs) -> anyhow::Result<()> {
+    let present = read_instance_key(config)?;
+    let (mut connection, schema) = open_for_key_change(config).await?;
+    let stored = Database::stored_key_fingerprint(&mut connection).await?;
+    if let (Some(bytes), Some(stored)) = (&present, &stored) {
+        if security::constant_time_bytes_eq(stored, &security::bytes_hash(bytes)) {
+            anyhow::bail!(
+                "this database already opens with the key beside it; `key rotate` replaces it without losing anything"
+            );
+        }
+    }
+    if !args.confirm {
+        return report_reading(&mut connection, schema, Intent::Adopt, config).await;
+    }
+    let recovery = copy_the_pair_aside(config, &mut connection).await?;
+    Database::migrate_on(&mut connection).await?;
+    let material = Database::key_material(&mut connection).await?;
+    print_inventory(Intent::Adopt, &config.database_path, &material);
+    let moved = install_new_key(config, connection, Rekey::Discard).await?;
+    println!(
+        "Done. {} Subsonic credential(s) and {} scrobbling link(s) deleted, with {} queued listen(s); {} share(s) re-addressed.",
+        moved.subsonic_credentials, moved.scrobble_links, moved.queued_listens, moved.shares
+    );
+    report_done(&recovery);
+    Ok(())
+}
+
+/// What the command answers when it has not been told to go ahead.
+///
+/// A database behind this binary gets no inventory, and that is the honest
+/// answer rather than a missing feature: counting means reading tables a
+/// pending migration may not have created yet, and creating them is the change
+/// this half promises not to make.
+async fn report_reading(
+    connection: &mut sqlx::SqliteConnection,
+    schema: SchemaState,
+    intent: Intent,
+    config: &crate::Config,
+) -> anyhow::Result<()> {
+    if let SchemaState::Behind(pending) = schema {
+        println!(
+            "{pending} migration(s) are pending on {}.",
+            config.database_path.display()
+        );
+        println!("Applying them is a change, and this half makes none, so there is no inventory");
+        println!("to give yet. Re-run with --confirm: the pair is copied aside as it stands, the");
+        println!("schema is brought up to date, and only then is the key replaced.");
+        return Ok(());
+    }
+    let material = Database::key_material(connection).await?;
+    print_inventory(intent, &config.database_path, &material);
+    println!("Nothing has been changed. Re-run with --confirm.");
+    Ok(())
+}
+
+fn print_inventory(intent: Intent, database: &Path, material: &KeyMaterial) {
+    match intent {
+        Intent::Rotate => {
+            println!("Rotating the instance key of {}.", database.display());
+            println!();
+            println!(
+                "  {} Subsonic credential(s) — moved to the new key; password and API key both keep working",
+                material.subsonic_credentials
+            );
+            println!(
+                "  {} scrobbling link(s) — moved to the new key, unchanged",
+                material.scrobble_links
+            );
+            println!(
+                "  {} share(s) — kept, but every public URL changes",
+                material.shares
+            );
+        }
+        Intent::Adopt => {
+            println!("Adopting {} under a new instance key.", database.display());
+            println!();
+            println!("The old key is gone, so nothing sealed under it can be carried over:");
+            println!();
+            // The API key is not encrypted — it is a SHA-256 hash, which no key
+            // change touches — but it shares the row with the password that is,
+            // and the columns are `NOT NULL`. So the row goes whole, and the
+            // operator who reads "password" and thinks only of a password finds
+            // their clients locked out too.
+            println!(
+                "  {} Subsonic credential(s) — deleted, password and `wfsk_` API key together; `credential set` mints a new pair to hand to each client",
+                material.subsonic_credentials
+            );
+            println!(
+                "  {} scrobbling link(s) — deleted, and the {} queued listen(s) behind them",
+                material.scrobble_links, material.queued_listens
+            );
+            println!(
+                "  {} share(s) — kept, but every public URL changes",
+                material.shares
+            );
+            println!();
+            println!("Everything else is untouched: every account and its web password, the whole");
+            println!("catalogue, favourites, ratings, playlists, queues, history and bookmarks.");
+        }
+    }
+    println!();
+}
+
+/// Puts a file on disk, rather than in the page cache.
+///
+/// Opened differently on the two platforms, and neither spelling works on
+/// both. Windows refuses `FlushFileBuffers` on a handle with no write access
+/// and answers "Access is denied" to a call only asking for durability —
+/// measured, after three tests failed on it. Unix allows `fsync` on a
+/// read-only descriptor, and has to be asked that way: `fs::copy` carries the
+/// source's permissions over, so a hardened `instance.key` at mode 0400 makes
+/// its own copy unopenable for writing, and demanding write access here would
+/// turn a sensible precaution into a server that cannot rotate its key.
+async fn sync_file(path: &Path) -> std::io::Result<()> {
+    #[cfg(unix)]
+    {
+        tokio::fs::File::open(path).await?.sync_all().await
+    }
+    #[cfg(not(unix))]
+    {
+        tokio::fs::OpenOptions::new()
+            .write(true)
+            .open(path)
+            .await?
+            .sync_all()
+            .await
+    }
+}
+
+/// Puts a *directory entry* on disk — a file created, or renamed into place.
+///
+/// Writing a file and synchronising it says nothing about the directory that
+/// now claims to hold it, and the event these two commands guard against is
+/// exactly the one that does not ask politely: a machine that stops between
+/// the database committing to a new key and the file holding that key
+/// becoming real.
+///
+/// Unix only, and not an oversight: a Windows directory cannot be opened as a
+/// file to be synchronised, and `fs::rename` there goes through `MoveFileEx`,
+/// which is atomic but carries no equivalent promise. Nothing in this
+/// repository can test any of it — a power cut is not an inversion — so it is
+/// written for the property rather than for a test, and said so here.
+async fn sync_directory(path: &Path) -> std::io::Result<()> {
+    #[cfg(unix)]
+    {
+        tokio::fs::File::open(path).await?.sync_all().await?;
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = path;
+    }
+    Ok(())
+}
+
+/// The pair as this command found it, before a single statement touches it.
+///
+/// Before the migration as well as before the key, which is the whole reason
+/// it is its own step: a copy taken afterwards would be a database at a schema
+/// the operator never ran, and restoring it would not undo what they asked to
+/// undo. `database restore` leaves the same kind of directory behind.
+async fn copy_the_pair_aside(
+    config: &crate::Config,
+    connection: &mut sqlx::SqliteConnection,
+) -> anyhow::Result<PathBuf> {
+    let recovery = config
+        .data_dir
+        .join(format!("pre-key-{}", chrono::Utc::now().timestamp_millis()));
+    tokio::fs::create_dir_all(&recovery).await?;
+    let saved = recovery.join("waveflow.db");
+    let saved = saved
+        .to_str()
+        .ok_or_else(|| anyhow::anyhow!("the recovery path is not valid UTF-8"))?;
+    sqlx::query("VACUUM INTO ?")
+        .bind(saved)
+        .execute(&mut *connection)
+        .await
+        .map_err(|error| anyhow::anyhow!("could not write the recovery copy: {error}"))?;
+    sync_file(Path::new(saved)).await?;
+    if config.instance_key_path.exists() {
+        let saved_key = recovery.join("instance.key");
+        tokio::fs::copy(&config.instance_key_path, &saved_key).await?;
+        sync_file(&saved_key).await?;
+    }
+    // The two files, and then the directory that is supposed to contain them.
+    // This happens before anything is changed, so a failure here is a refusal
+    // rather than a half-finished operation — which is the right way round for
+    // the one copy the operator would reach for.
+    sync_directory(&recovery).await?;
+    Ok(recovery)
+}
+
+/// Moves the values, then the key file — and answers with what was moved.
+///
+/// Not with what was predicted a moment earlier: the inventory comes from
+/// reading the tables, this comes from the statements that touched them, and a
+/// line printed from the second is the only one reporting the operation rather
+/// than the plan.
+async fn install_new_key(
+    config: &crate::Config,
+    mut connection: sqlx::SqliteConnection,
+    plan: Rekey<'_>,
+) -> anyhow::Result<KeyMaterial> {
+    // Staged rather than written in place. The key file is the last thing to
+    // move: one that arrived before the commit would name a database that
+    // never changed.
+    let staged = config
+        .data_dir
+        .join(format!(".key-{}.tmp", uuid::Uuid::new_v4()));
+    let new_bytes = security::SecretBox::create_instance_key(&staged)?;
+    let new_key = security::SecretBox::from_key_bytes(&new_bytes)?;
+    // Two files now exist in the data directory that nothing has yet promised
+    // will still be there: the `pre-key-…` directory and this staged key. The
+    // copy made each of *its* entries durable, and neither made durable the
+    // entry naming it. So the data directory is synchronised here — after the
+    // staged key exists and before the commit below, because after the commit
+    // is too late: a machine stopping in that window would come back with a
+    // database bound to a new key, no file holding it, and no copy to go back
+    // to. Which is the whole of what this command exists to prevent, arrived
+    // at by the command itself.
+    sync_directory(&config.data_dir).await?;
+    let moved = match Database::rekey(
+        &mut connection,
+        plan,
+        &new_key,
+        &security::bytes_hash(&new_bytes),
+        now_ms(),
+    )
+    .await
+    {
+        Ok(moved) => moved,
+        Err(error) => {
+            tokio::fs::remove_file(&staged).await.ok();
+            return Err(error);
+        }
+    };
+    // Releases the exclusive lock and checkpoints the write-ahead log, so the
+    // database is settled on disk before the other half of the pair moves.
+    //
+    // Past the commit above, a failure here is not a failed operation but an
+    // unfinished one: the database already answers to the new key, and the
+    // only thing missing is the file. So the error says where that file is,
+    // rather than leaving an operator with a server that will not start and
+    // nothing naming the thing that would start it.
+    let unfinished = || {
+        format!(
+            "the database is already bound to the new key; move {} onto {} to finish",
+            staged.display(),
+            config.instance_key_path.display()
+        )
+    };
+    connection.close().await.with_context(unfinished)?;
+    tokio::fs::rename(&staged, &config.instance_key_path)
+        .await
+        .with_context(unfinished)?;
+    // The rename is atomic; the directory entry it made is not durable until
+    // the directory itself is synchronised. Reported rather than returned as
+    // an error: the change is complete by now, and failing here would hide the
+    // recovery path the caller is about to print — which is the one thing an
+    // operator would need next.
+    if let Some(parent) = config.instance_key_path.parent() {
+        if let Err(error) = sync_directory(parent).await {
+            eprintln!(
+                "warning: {} is in place but its directory could not be synchronised ({error}); take a backup before anything else",
+                config.instance_key_path.display()
+            );
+        }
+    }
+    Ok(moved)
+}
+
+fn report_done(recovery: &Path) {
+    println!(
+        "The previous pair is recoverable from {}",
+        recovery.display()
+    );
+    println!("Start the server; it opens on the new key.");
+    // The command exists because somebody lost a key. Saying this at the one
+    // moment they are looking at a new one costs a line.
+    println!("Then take a fresh `database backup`: the new key is as unrecoverable as the last.");
+}
diff --git a/src/cli/library.rs b/src/cli/library.rs
new file mode 100644
index 00000000..bc6bd0f5
--- /dev/null
+++ b/src/cli/library.rs
@@ -0,0 +1,406 @@
+//! `library`: registering libraries, changing them through the domain
+//! services, managing their members, and waiting out the scans that follow.
+
+use std::str::FromStr;
+
+use anyhow::Context;
+
+use super::{
+    require_admin, AddLibraryArgs, DeleteLibraryArgs, PurgeArgs, RemoveMemberArgs,
+    RenameLibraryArgs, SetCanvasArgs, SetLinksArgs, SetMemberArgs, SetPathArgs, SetUploadsArgs,
+    SetWatchArgs, UnavailableArgs,
+};
+use crate::{
+    authentication::now_ms,
+    catalog::LibraryRecord,
+    database::{Database, LibraryRole, LibraryVisibility},
+    AppState,
+};
+
+pub(super) async fn add_library(state: &AppState, args: AddLibraryArgs) -> anyhow::Result<()> {
+    let owner = state
+        .db
+        .account_by_username(&args.owner)
+        .await?
+        .with_context(|| format!("account not found: {}", args.owner))?;
+    let metadata = std::fs::symlink_metadata(&args.path)
+        .with_context(|| format!("library path is unavailable: {}", args.path.display()))?;
+    if metadata.file_type().is_symlink() {
+        anyhow::bail!("library root cannot be a symbolic link");
+    }
+    if !metadata.is_dir() {
+        anyhow::bail!("library path must be a directory");
+    }
+    let canonical = std::fs::canonicalize(&args.path)?;
+    let visibility = LibraryVisibility::from_str(&args.visibility)?;
+    let id = state
+        .db
+        .create_library(owner.id, &args.name, &canonical, visibility, now_ms())
+        .await
+        .context("register library")?;
+    state.scanner.libraries_changed();
+    println!("Registered library {} ({id})", args.name);
+    let scan_id = state
+        .scanner
+        .trigger(
+            LibraryRecord {
+                id,
+                name: args.name,
+                root_path: canonical,
+            },
+            Some(owner.id),
+            "library_added",
+        )
+        .await?;
+    loop {
+        let job = state
+            .db
+            .scan_job_for_user(owner.id, scan_id)
+            .await?
+            .context("new library scan disappeared")?;
+        match job.status.as_str() {
+            "completed" => {
+                println!(
+                    "Initial scan complete: {} added, {} errors",
+                    job.added, job.errors
+                );
+                break;
+            }
+            "failed" => anyhow::bail!(
+                "initial scan failed: {}",
+                job.message.unwrap_or_else(|| "unknown error".into())
+            ),
+            _ => tokio::time::sleep(std::time::Duration::from_millis(50)).await,
+        }
+    }
+    Ok(())
+}
+
+/// What a refused library operation says on a terminal. The services answer
+/// in their own vocabulary; an operator needs a sentence.
+fn library_refusal(error: crate::services::ServiceError, library_id: uuid::Uuid) -> anyhow::Error {
+    use crate::services::ServiceError;
+    match error {
+        ServiceError::NotFound | ServiceError::Forbidden => {
+            anyhow::anyhow!("library not found: {library_id}")
+        }
+        ServiceError::Conflict => anyhow::anyhow!(
+            "library {library_id} is being scanned, or another library already has that path; \
+             try again once the scan is over"
+        ),
+        ServiceError::Invalid => anyhow::anyhow!("the request was refused as invalid"),
+        other => anyhow::anyhow!(other),
+    }
+}
+
+/// Waits for a scan this command queued, and prints how it ended. The process
+/// is about to exit, and the scan is a task of this process: leaving it would
+/// kill it halfway.
+async fn wait_for_scan(state: &AppState, scan_id: uuid::Uuid) -> anyhow::Result<()> {
+    loop {
+        let job = state
+            .db
+            .scan_job(scan_id)
+            .await?
+            .context("the scan disappeared")?;
+        match job.status.as_str() {
+            "completed" => {
+                println!(
+                    "Scan complete: {} added, {} updated, {} moved, {} missing, {} errors",
+                    job.added, job.updated, job.moved, job.unavailable, job.errors
+                );
+                return Ok(());
+            }
+            "failed" => anyhow::bail!(
+                "scan failed: {}",
+                job.message.unwrap_or_else(|| "unknown error".into())
+            ),
+            _ => tokio::time::sleep(std::time::Duration::from_millis(50)).await,
+        }
+    }
+}
+
+pub(super) async fn rename_library(
+    state: &AppState,
+    args: RenameLibraryArgs,
+) -> anyhow::Result<()> {
+    let actor = require_admin(&state.db, &args.actor).await?;
+    state
+        .services
+        .update_library(
+            crate::services::LibraryActor::operator(actor.id),
+            args.library_id,
+            crate::services::LibraryUpdate {
+                name: Some(args.name.clone()),
+                ..Default::default()
+            },
+        )
+        .await
+        .map_err(|error| library_refusal(error, args.library_id))?;
+    println!(
+        "Library {} is now named {}",
+        args.library_id,
+        args.name.trim()
+    );
+    Ok(())
+}
+
+pub(super) async fn set_library_path(state: &AppState, args: SetPathArgs) -> anyhow::Result<()> {
+    let actor = require_admin(&state.db, &args.actor).await?;
+    let updated = state
+        .services
+        .update_library(
+            crate::services::LibraryActor::operator(actor.id),
+            args.library_id,
+            crate::services::LibraryUpdate {
+                path: Some(args.path.to_string_lossy().into_owned()),
+                ..Default::default()
+            },
+        )
+        .await
+        .map_err(|error| match error {
+            crate::services::ServiceError::Invalid => anyhow::anyhow!(
+                "library path must be an existing directory and not a symbolic link: {}",
+                args.path.display()
+            ),
+            other => library_refusal(other, args.library_id),
+        })?;
+    match updated.scan_id {
+        Some(scan_id) => {
+            println!("Library {} moved; scanning it", args.library_id);
+            wait_for_scan(state, scan_id).await
+        }
+        None => {
+            println!("Library {} already has that path", args.library_id);
+            Ok(())
+        }
+    }
+}
+
+pub(super) async fn set_library_links(state: &AppState, args: SetLinksArgs) -> anyhow::Result<()> {
+    let actor = require_admin(&state.db, &args.actor).await?;
+    let updated = state
+        .services
+        .update_library(
+            crate::services::LibraryActor::operator(actor.id),
+            args.library_id,
+            crate::services::LibraryUpdate {
+                follow_links: Some(args.follow),
+                ..Default::default()
+            },
+        )
+        .await
+        .map_err(|error| library_refusal(error, args.library_id))?;
+    println!(
+        "Library {} {} symbolic links",
+        args.library_id,
+        if args.follow {
+            "follows"
+        } else {
+            "does not follow"
+        }
+    );
+    match updated.scan_id {
+        Some(scan_id) => wait_for_scan(state, scan_id).await,
+        None => Ok(()),
+    }
+}
+
+pub(super) async fn delete_library(
+    state: &AppState,
+    args: DeleteLibraryArgs,
+) -> anyhow::Result<()> {
+    let actor = require_admin(&state.db, &args.actor).await?;
+    let deleted = state
+        .services
+        .delete_library(
+            crate::services::LibraryActor::operator(actor.id),
+            args.library_id,
+            &args.confirm,
+        )
+        .await
+        .map_err(|error| match error {
+            crate::services::ServiceError::Invalid => {
+                anyhow::anyhow!("--confirm must be the library's current name; nothing was deleted")
+            }
+            other => library_refusal(other, args.library_id),
+        })?;
+    println!(
+        "Deleted library {}: {} tracks, {} albums, {} artists removed from the catalogue; \
+         no file was touched",
+        args.library_id, deleted.tracks, deleted.albums, deleted.artists
+    );
+    Ok(())
+}
+
+pub(super) async fn list_unavailable(
+    state: &AppState,
+    args: UnavailableArgs,
+) -> anyhow::Result<()> {
+    let actor = require_admin(&state.db, &args.actor).await?;
+    let mut offset = 0;
+    loop {
+        let page = crate::services::BrowsePage::new(Some(offset), Some(200))
+            .map_err(|error| library_refusal(error, args.library_id))?;
+        let listed = state
+            .services
+            .unavailable_tracks(
+                crate::services::LibraryActor::operator(actor.id),
+                args.library_id,
+                page,
+            )
+            .await
+            .map_err(|error| library_refusal(error, args.library_id))?;
+        if offset == 0 {
+            println!("{} missing track(s)", listed.total);
+        }
+        for track in &listed.tracks {
+            println!(
+                "{}\t{}\t{} playlist entries, {} favourites, {} plays",
+                track.id, track.relative_path, track.playlist_entries, track.favorites, track.plays
+            );
+        }
+        if listed.tracks.len() < 200 {
+            return Ok(());
+        }
+        offset += 200;
+    }
+}
+
+pub(super) async fn purge_unavailable(state: &AppState, args: PurgeArgs) -> anyhow::Result<()> {
+    let actor = require_admin(&state.db, &args.actor).await?;
+    if !args.all && args.track_id.is_empty() {
+        anyhow::bail!("name the tracks to purge with --track-id, or pass --all");
+    }
+    let outcome = state
+        .services
+        .purge_unavailable_tracks(
+            crate::services::LibraryActor::operator(actor.id),
+            args.library_id,
+            crate::services::PurgeRequest {
+                track_ids: (!args.all).then_some(args.track_id),
+                all: args.all,
+            },
+        )
+        .await
+        .map_err(|error| library_refusal(error, args.library_id))?;
+    match outcome.restorable_until {
+        Some(until) => println!(
+            "Purged {} missing track(s); restorable until {until} (epoch ms) with `library restore`",
+            outcome.purged
+        ),
+        None => println!("Purged {} missing track(s)", outcome.purged),
+    }
+    Ok(())
+}
+
+pub(super) async fn restore_purged(state: &AppState, args: PurgeArgs) -> anyhow::Result<()> {
+    let actor = require_admin(&state.db, &args.actor).await?;
+    if !args.all && args.track_id.is_empty() {
+        anyhow::bail!("name the tracks to restore with --track-id, or pass --all");
+    }
+    let outcome = state
+        .services
+        .restore_purged_tracks(
+            crate::services::LibraryActor::operator(actor.id),
+            args.library_id,
+            crate::services::PurgeRequest {
+                track_ids: (!args.all).then_some(args.track_id),
+                all: args.all,
+            },
+        )
+        .await
+        .map_err(|error| library_refusal(error, args.library_id))?;
+    println!("Restored {} purged track(s)", outcome.restored);
+    Ok(())
+}
+
+pub(super) async fn set_library_watch(state: &AppState, args: SetWatchArgs) -> anyhow::Result<()> {
+    let actor = require_admin(&state.db, &args.actor).await?;
+    state
+        .services
+        .update_library(
+            crate::services::LibraryActor::operator(actor.id),
+            args.library_id,
+            crate::services::LibraryUpdate {
+                watch: Some(args.watch),
+                ..Default::default()
+            },
+        )
+        .await
+        .map_err(|error| library_refusal(error, args.library_id))?;
+    println!(
+        "Library {} is {}",
+        args.library_id,
+        if args.watch {
+            "watched for changes"
+        } else {
+            "left to the periodic scan"
+        }
+    );
+    Ok(())
+}
+
+pub(super) async fn set_member(db: &Database, args: SetMemberArgs) -> anyhow::Result<()> {
+    let actor = require_admin(db, &args.actor).await?;
+    let member = db
+        .account_by_username(&args.username)
+        .await?
+        .with_context(|| format!("account not found: {}", args.username))?;
+    let role = LibraryRole::from_str(&args.role)?;
+    if role == LibraryRole::Owner {
+        anyhow::bail!("library ownership cannot be transferred with set-member");
+    }
+    db.add_library_member(actor.id, args.library_id, member.id, role, now_ms())
+        .await?;
+    println!("Updated member {} on {}", args.username, args.library_id);
+    Ok(())
+}
+
+pub(super) async fn set_uploads(db: &Database, args: SetUploadsArgs) -> anyhow::Result<()> {
+    let actor = require_admin(db, &args.actor).await?;
+    if !db
+        .set_library_accepts_uploads(actor.id, args.library_id, args.accept, now_ms())
+        .await?
+    {
+        anyhow::bail!("library not found: {}", args.library_id);
+    }
+    println!(
+        "Library {} {} uploads",
+        args.library_id,
+        if args.accept { "accepts" } else { "refuses" }
+    );
+    Ok(())
+}
+
+pub(super) async fn set_canvas(db: &Database, args: SetCanvasArgs) -> anyhow::Result<()> {
+    let actor = require_admin(db, &args.actor).await?;
+    if !db
+        .set_library_accepts_canvas(actor.id, args.library_id, args.accept, now_ms())
+        .await?
+    {
+        anyhow::bail!("library not found: {}", args.library_id);
+    }
+    println!(
+        "Library {} {} canvases",
+        args.library_id,
+        if args.accept { "accepts" } else { "refuses" }
+    );
+    Ok(())
+}
+
+pub(super) async fn remove_member(db: &Database, args: RemoveMemberArgs) -> anyhow::Result<()> {
+    let actor = require_admin(db, &args.actor).await?;
+    let member = db
+        .account_by_username(&args.username)
+        .await?
+        .with_context(|| format!("account not found: {}", args.username))?;
+    if !db
+        .remove_library_member(actor.id, args.library_id, member.id, now_ms())
+        .await?
+    {
+        anyhow::bail!("membership not found or library owner cannot be removed");
+    }
+    println!("Removed member {} from {}", args.username, args.library_id);
+    Ok(())
+}
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index bd9e4cce..11d9d923 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1,452 +1,40 @@
 //! Administrative CLI used before the M4 web administration surface exists.
 
-use std::{
-    path::{Path, PathBuf},
-    str::FromStr,
+mod account;
+mod args;
+mod database;
+mod key;
+mod library;
+mod scrobble;
+
+pub use args::{
+    AccountCommand, AddLibraryArgs, AuthorizeLastFmArgs, BackupArgs, Cli, Command,
+    CreateAccountArgs, CreateTokenArgs, CredentialCommand, DatabaseCommand, DeleteLibraryArgs,
+    ExchangeLastFmArgs, KeyArgs, KeyCommand, LibraryCommand, LinkScrobbleArgs, PurgeArgs,
+    RemoveMemberArgs, RenameLibraryArgs, RestoreArgs, RevokeCredentialArgs, ScrobbleCommand,
+    ScrobbleStatusArgs, SetCanvasArgs, SetCredentialArgs, SetLinksArgs, SetMemberArgs, SetPathArgs,
+    SetUploadsArgs, SetWatchArgs, TokenCommand, UnavailableArgs, UnlinkScrobbleArgs,
 };
+pub use database::restore;
+pub use key::key;
 
 use anyhow::Context;
-use clap::{Args, Parser, Subcommand};
-use sqlx::Connection;
 
+use self::account::{create_account, create_token, revoke_credential, set_credential};
+use self::database::backup;
+use self::library::{
+    add_library, delete_library, list_unavailable, purge_unavailable, remove_member,
+    rename_library, restore_purged, set_canvas, set_library_links, set_library_path,
+    set_library_watch, set_member, set_uploads,
+};
+use self::scrobble::{
+    authorize_lastfm, exchange_lastfm, link_scrobble, scrobble_status, unlink_scrobble,
+};
 use crate::{
-    authentication::now_ms,
-    catalog::LibraryRecord,
-    database::{
-        AccountRole, Database, KeyMaterial, LibraryRole, LibraryVisibility, Rekey, SchemaState,
-    },
-    security, AppState,
+    database::{AccountRole, Database},
+    AppState,
 };
 
-#[derive(Debug, Parser)]
-#[command(name = "waveflow-server", version, about)]
-pub struct Cli {
-    #[command(subcommand)]
-    pub command: Option<Command>,
-}
-
-#[derive(Debug, Subcommand)]
-pub enum Command {
-    /// Run the HTTP server (the default when no command is supplied).
-    Serve,
-    /// Manage local accounts.
-    Account {
-        #[command(subcommand)]
-        command: AccountCommand,
-    },
-    /// Register libraries and manage their members.
-    Library {
-        #[command(subcommand)]
-        command: LibraryCommand,
-    },
-    /// Manage per-user Subsonic credentials.
-    Credential {
-        #[command(subcommand)]
-        command: CredentialCommand,
-    },
-    /// Create long-lived native API tokens.
-    Token {
-        #[command(subcommand)]
-        command: TokenCommand,
-    },
-    /// Link an account to a scrobbling destination, or read its queue.
-    ///
-    /// The same gestures the native API offers, for an operator preparing a
-    /// server nobody has opened a browser on yet — exactly the reason the
-    /// dedicated Subsonic password has a command here too.
-    Scrobble {
-        #[command(subcommand)]
-        command: ScrobbleCommand,
-    },
-    /// Check the SQLite database integrity.
-    Database {
-        #[command(subcommand)]
-        command: DatabaseCommand,
-    },
-    /// Replace the instance key, with or without the old one in hand.
-    ///
-    /// Both run before the server opens SQLite, because the boot they exist to
-    /// unblock is the one that aborts on a mismatched pair.
-    Key {
-        #[command(subcommand)]
-        command: KeyCommand,
-    },
-}
-
-#[derive(Debug, Subcommand)]
-pub enum AccountCommand {
-    /// Create the first or an additional administrator.
-    CreateAdmin(CreateAccountArgs),
-    /// Create a regular account.
-    CreateUser(CreateAccountArgs),
-}
-
-#[derive(Debug, Args)]
-pub struct CreateAccountArgs {
-    #[arg(long)]
-    username: String,
-    /// Environment variable containing the password. The value never appears in argv.
-    #[arg(long, default_value = "WAVEFLOW_ACCOUNT_PASSWORD")]
-    password_env: String,
-}
-
-#[derive(Debug, Subcommand)]
-pub enum LibraryCommand {
-    Add(AddLibraryArgs),
-    SetMember(SetMemberArgs),
-    RemoveMember(RemoveMemberArgs),
-    SetUploads(SetUploadsArgs),
-    SetCanvas(SetCanvasArgs),
-    /// Give a library a new name.
-    Rename(RenameLibraryArgs),
-    /// Point a library at a new root, then scan it. Tracks are matched by
-    /// their path relative to the root, so a tree moved intact keeps them all.
-    SetPath(SetPathArgs),
-    /// Follow symbolic links whose target stays inside the library, or stop
-    /// following them, then scan it.
-    SetLinks(SetLinksArgs),
-    /// Remove a library from the catalogue, with every track, album and
-    /// artist in it and everything that hangs off them for every member.
-    /// Nothing is removed from the disk.
-    Delete(DeleteLibraryArgs),
-    /// List the tracks whose file the scans can no longer find.
-    Unavailable(UnavailableArgs),
-    /// Purge missing tracks: out of sight at once, and removed from the
-    /// catalogue for good once the grace window (`WAVEFLOW_PURGE_GRACE_HOURS`)
-    /// has passed, or at once when it is zero.
-    Purge(PurgeArgs),
-    /// Take a purge back, for tracks still within the grace window.
-    Restore(PurgeArgs),
-    /// Watch the library for changes, or stop watching it.
-    SetWatch(SetWatchArgs),
-}
-
-#[derive(Debug, Args)]
-pub struct SetWatchArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    library_id: uuid::Uuid,
-    /// `true` to watch, `false` to leave the library to the periodic scan.
-    #[arg(long, action = clap::ArgAction::Set)]
-    watch: bool,
-}
-
-#[derive(Debug, Args)]
-pub struct RenameLibraryArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    library_id: uuid::Uuid,
-    #[arg(long)]
-    name: String,
-}
-
-#[derive(Debug, Args)]
-pub struct SetPathArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    library_id: uuid::Uuid,
-    #[arg(long)]
-    path: PathBuf,
-}
-
-/// Off until an operator says otherwise: without `--follow`, links are not
-/// followed.
-#[derive(Debug, Args)]
-pub struct SetLinksArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    library_id: uuid::Uuid,
-    #[arg(long)]
-    follow: bool,
-}
-
-#[derive(Debug, Args)]
-pub struct DeleteLibraryArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    library_id: uuid::Uuid,
-    /// The library's current name, typed out: the deletion goes ahead only
-    /// when it matches.
-    #[arg(long)]
-    confirm: String,
-}
-
-#[derive(Debug, Args)]
-pub struct UnavailableArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    library_id: uuid::Uuid,
-}
-
-/// Exactly one of `--all` and `--track-id`.
-#[derive(Debug, Args)]
-pub struct PurgeArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    library_id: uuid::Uuid,
-    /// Every missing track of the library.
-    #[arg(long, conflicts_with = "track_id")]
-    all: bool,
-    /// One missing track; repeat for several.
-    #[arg(long = "track-id")]
-    track_id: Vec<uuid::Uuid>,
-}
-
-#[derive(Debug, Args)]
-pub struct AddLibraryArgs {
-    #[arg(long)]
-    owner: String,
-    #[arg(long)]
-    name: String,
-    #[arg(long)]
-    path: PathBuf,
-    #[arg(long, default_value = "private")]
-    visibility: String,
-}
-
-#[derive(Debug, Args)]
-pub struct SetMemberArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    library_id: uuid::Uuid,
-    #[arg(long)]
-    username: String,
-    #[arg(long, default_value = "listener")]
-    role: String,
-}
-
-/// Whether a library will receive files at all.
-///
-/// Off until an operator says otherwise: upgrading a server must not turn a
-/// read-only installation into one that grows.
-#[derive(Debug, Args)]
-pub struct SetUploadsArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    library_id: uuid::Uuid,
-    #[arg(long)]
-    accept: bool,
-}
-
-/// Off until an operator says otherwise, and separate from the upload flag on
-/// purpose: a server that refuses to grow in audio may still take a few hundred
-/// kilobytes of video loop, which is the most common installation there is.
-#[derive(Debug, Args)]
-pub struct SetCanvasArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    library_id: uuid::Uuid,
-    #[arg(long)]
-    accept: bool,
-}
-
-#[derive(Debug, Args)]
-pub struct RemoveMemberArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    library_id: uuid::Uuid,
-    #[arg(long)]
-    username: String,
-}
-
-#[derive(Debug, Subcommand)]
-pub enum CredentialCommand {
-    Set(SetCredentialArgs),
-    Revoke(RevokeCredentialArgs),
-}
-
-#[derive(Debug, Args)]
-pub struct SetCredentialArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    username: String,
-    /// Environment variable containing the dedicated Subsonic password.
-    #[arg(long, default_value = "WAVEFLOW_SUBSONIC_PASSWORD")]
-    password_env: String,
-}
-
-#[derive(Debug, Subcommand)]
-pub enum ScrobbleCommand {
-    /// Authorise an account at a destination, replacing any authorisation it
-    /// already had there.
-    Link(LinkScrobbleArgs),
-    /// Begin a Last.fm authorisation from a machine with no browser. Prints
-    /// the address to open and the token to bring back to `exchange`.
-    Authorize(AuthorizeLastFmArgs),
-    /// Finish one: turn the approved request token into a link.
-    Exchange(ExchangeLastFmArgs),
-    /// Withdraw it. Listens already queued under it stay queued under it and
-    /// are never sent to whatever is linked next.
-    Unlink(UnlinkScrobbleArgs),
-    /// What each of an account's links is doing.
-    Status(ScrobbleStatusArgs),
-}
-
-#[derive(Debug, Args)]
-pub struct LinkScrobbleArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    username: String,
-    /// `listenbrainz`, `maloja` or `lastfm`.
-    #[arg(long)]
-    provider: String,
-    /// Which declared instance of it. Named rather than defaulted: an operator
-    /// running two Maloja instances must say which one this account submits to,
-    /// and a silent default would pick one for them.
-    #[arg(long)]
-    destination: String,
-    /// Environment variable containing the token. The value never appears in
-    /// argv, for the same reason the account password does not: a shell history
-    /// and a process list are both readable by people this credential is not
-    /// for.
-    #[arg(long, default_value = "WAVEFLOW_SCROBBLE_TOKEN")]
-    token_env: String,
-}
-
-/// Last.fm hands out no secret a person can paste, so `link` has nothing to be
-/// given for it. These two are `link` for that recipient, split where the
-/// person has to leave and come back.
-#[derive(Debug, Args)]
-pub struct AuthorizeLastFmArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    username: String,
-    /// Which declared Last.fm instance, for the reason `link` takes one.
-    #[arg(long)]
-    destination: String,
-}
-
-#[derive(Debug, Args)]
-pub struct ExchangeLastFmArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    username: String,
-    #[arg(long)]
-    destination: String,
-    /// Environment variable holding the token `authorize` printed. Out of
-    /// `argv` for the reason `link`'s secret is: a shell history and a process
-    /// list are both readable by people this is not for, and whoever exchanges
-    /// this token first is who the session ends up belonging to.
-    #[arg(long, default_value = ExchangeLastFmArgs::TOKEN_ENV)]
-    token_env: String,
-}
-
-impl ExchangeLastFmArgs {
-    /// Named once, because `authorize` prints it and this declares it — and a
-    /// default spelled in two places is a default that eventually disagrees
-    /// with the instructions for using it.
-    const TOKEN_ENV: &'static str = "WAVEFLOW_LASTFM_TOKEN";
-}
-
-#[derive(Debug, Args)]
-pub struct UnlinkScrobbleArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    username: String,
-    #[arg(long)]
-    provider: String,
-    /// Which declared instance of it, for the same reason `link` takes one.
-    #[arg(long)]
-    destination: String,
-}
-
-#[derive(Debug, Args)]
-pub struct ScrobbleStatusArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    username: String,
-}
-
-#[derive(Debug, Args)]
-pub struct RevokeCredentialArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    username: String,
-}
-
-#[derive(Debug, Subcommand)]
-pub enum TokenCommand {
-    Create(CreateTokenArgs),
-}
-
-#[derive(Debug, Args)]
-pub struct CreateTokenArgs {
-    #[arg(long)]
-    actor: String,
-    #[arg(long)]
-    username: String,
-    #[arg(long)]
-    name: String,
-    #[arg(long, value_delimiter = ',')]
-    scopes: Vec<String>,
-}
-
-#[derive(Debug, Subcommand)]
-pub enum DatabaseCommand {
-    Check,
-    /// Create a coherent SQLite + instance-key backup bundle.
-    Backup(BackupArgs),
-    /// Restore a backup bundle before opening SQLite.
-    Restore(RestoreArgs),
-    /// Read every file again on the next scan of every library, skipping
-    /// nothing (RFC-018): for a file rewritten in place with its size and
-    /// modification time both kept, which an ordinary scan does not open.
-    RescanFull,
-}
-
-#[derive(Debug, Args)]
-pub struct BackupArgs {
-    #[arg(long)]
-    pub output: PathBuf,
-}
-
-#[derive(Debug, Args)]
-pub struct RestoreArgs {
-    #[arg(long)]
-    pub input: PathBuf,
-}
-
-/// Two commands rather than one command and a flag.
-///
-/// They are not two ways of doing the same thing: `rotate` carries every
-/// encrypted value onto the new key, `adopt` deletes the ones that can no
-/// longer be read. Naming them apart is what keeps the second from being one
-/// mistyped flag away from the first — and `adopt` refuses outright on a
-/// database whose key is sitting next to it, since that is a rotation.
-#[derive(Debug, Subcommand)]
-pub enum KeyCommand {
-    /// Mint a new instance key and move every encrypted value onto it.
-    Rotate(KeyArgs),
-    /// Take a database over under a new key, discarding what the old one protected.
-    Adopt(KeyArgs),
-}
-
-#[derive(Debug, Args)]
-pub struct KeyArgs {
-    /// Do the work. Without it the command reads the database, prints what the
-    /// change costs, and stops.
-    #[arg(long)]
-    pub confirm: bool,
-}
-
 pub async fn execute(command: Command, state: &AppState) -> anyhow::Result<()> {
     let db = &state.db;
     match command {
@@ -523,1081 +111,6 @@ pub async fn execute(command: Command, state: &AppState) -> anyhow::Result<()> {
     }
 }
 
-pub async fn key(config: &crate::Config, command: KeyCommand) -> anyhow::Result<()> {
-    match command {
-        KeyCommand::Rotate(args) => rotate_key(config, args).await,
-        KeyCommand::Adopt(args) => adopt_key(config, args).await,
-    }
-}
-
-/// The key file as it stands, or nothing where there is no file.
-///
-/// Unvalidated on purpose. `rotate` has to open the thing and answers for it
-/// itself; `adopt` only ever compares a fingerprint, and a file of the wrong
-/// length cannot match one. Refusing it here would turn away exactly the
-/// operator `adopt` exists for — the one holding something that is no longer
-/// a key.
-fn read_instance_key(config: &crate::Config) -> anyhow::Result<Option<Vec<u8>>> {
-    match std::fs::read(&config.instance_key_path) {
-        Ok(bytes) => Ok(Some(bytes)),
-        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
-        Err(error) => Err(error.into()),
-    }
-}
-
-/// Which of the two commands is speaking.
-///
-/// Wording only. What each one *does* is the `Rekey` it hands to
-/// [`install_new_key`]; this decides nothing, and exists so the two inventories
-/// sit side by side instead of drifting apart in two copies.
-#[derive(Clone, Copy)]
-enum Intent {
-    Rotate,
-    Adopt,
-}
-
-/// The database, held alone — and not migrated.
-///
-/// The migration belongs to the half that has been confirmed. A reading says
-/// it changes nothing, and applying a migration is a change: it rewrites
-/// `_sqlx_migrations` and whatever the migration itself does, on a database
-/// the operator has not yet agreed to touch. [`Database::schema_state`] is
-/// asked instead, and each command answers for what it finds.
-async fn open_for_key_change(
-    config: &crate::Config,
-) -> anyhow::Result<(sqlx::SqliteConnection, SchemaState)> {
-    let mut connection =
-        Database::open_alone(&config.database_path, config.sqlite_busy_timeout).await?;
-    let schema = Database::schema_state(&mut connection).await?;
-    if schema == SchemaState::Empty {
-        anyhow::bail!(
-            "{} holds no WaveFlow schema; start the server once and it will create one",
-            config.database_path.display()
-        );
-    }
-    Ok((connection, schema))
-}
-
-async fn rotate_key(config: &crate::Config, args: KeyArgs) -> anyhow::Result<()> {
-    let Some(old_bytes) = read_instance_key(config)? else {
-        anyhow::bail!(
-            "there is no {} to rotate from; if it is gone for good, `key adopt` takes the database over under a new one",
-            config.instance_key_path.display()
-        );
-    };
-    let old_key = security::SecretBox::from_key_bytes(&old_bytes).with_context(|| {
-        format!(
-            "{} is not a usable key; if the real one is gone, `key adopt` takes the database over under a new one",
-            config.instance_key_path.display()
-        )
-    })?;
-    let (mut connection, schema) = open_for_key_change(config).await?;
-    if let Some(stored) = Database::stored_key_fingerprint(&mut connection).await? {
-        if !security::constant_time_bytes_eq(&stored, &security::bytes_hash(&old_bytes)) {
-            anyhow::bail!(
-                "the key beside this database is not the one it was bound to; restore the matching pair, or `key adopt` if the real one is gone"
-            );
-        }
-    }
-    if !args.confirm {
-        return report_reading(&mut connection, schema, Intent::Rotate, config).await;
-    }
-    let recovery = copy_the_pair_aside(config, &mut connection).await?;
-    Database::migrate_on(&mut connection).await?;
-    let material = Database::key_material(&mut connection).await?;
-    print_inventory(Intent::Rotate, &config.database_path, &material);
-    let moved = install_new_key(config, connection, Rekey::Reencrypt(&old_key)).await?;
-    println!(
-        "Done. {} Subsonic credential(s) and {} scrobbling link(s) moved to the new key; {} share(s) re-addressed.",
-        moved.subsonic_credentials, moved.scrobble_links, moved.shares
-    );
-    report_done(&recovery);
-    Ok(())
-}
-
-async fn adopt_key(config: &crate::Config, args: KeyArgs) -> anyhow::Result<()> {
-    let present = read_instance_key(config)?;
-    let (mut connection, schema) = open_for_key_change(config).await?;
-    let stored = Database::stored_key_fingerprint(&mut connection).await?;
-    if let (Some(bytes), Some(stored)) = (&present, &stored) {
-        if security::constant_time_bytes_eq(stored, &security::bytes_hash(bytes)) {
-            anyhow::bail!(
-                "this database already opens with the key beside it; `key rotate` replaces it without losing anything"
-            );
-        }
-    }
-    if !args.confirm {
-        return report_reading(&mut connection, schema, Intent::Adopt, config).await;
-    }
-    let recovery = copy_the_pair_aside(config, &mut connection).await?;
-    Database::migrate_on(&mut connection).await?;
-    let material = Database::key_material(&mut connection).await?;
-    print_inventory(Intent::Adopt, &config.database_path, &material);
-    let moved = install_new_key(config, connection, Rekey::Discard).await?;
-    println!(
-        "Done. {} Subsonic credential(s) and {} scrobbling link(s) deleted, with {} queued listen(s); {} share(s) re-addressed.",
-        moved.subsonic_credentials, moved.scrobble_links, moved.queued_listens, moved.shares
-    );
-    report_done(&recovery);
-    Ok(())
-}
-
-/// What the command answers when it has not been told to go ahead.
-///
-/// A database behind this binary gets no inventory, and that is the honest
-/// answer rather than a missing feature: counting means reading tables a
-/// pending migration may not have created yet, and creating them is the change
-/// this half promises not to make.
-async fn report_reading(
-    connection: &mut sqlx::SqliteConnection,
-    schema: SchemaState,
-    intent: Intent,
-    config: &crate::Config,
-) -> anyhow::Result<()> {
-    if let SchemaState::Behind(pending) = schema {
-        println!(
-            "{pending} migration(s) are pending on {}.",
-            config.database_path.display()
-        );
-        println!("Applying them is a change, and this half makes none, so there is no inventory");
-        println!("to give yet. Re-run with --confirm: the pair is copied aside as it stands, the");
-        println!("schema is brought up to date, and only then is the key replaced.");
-        return Ok(());
-    }
-    let material = Database::key_material(connection).await?;
-    print_inventory(intent, &config.database_path, &material);
-    println!("Nothing has been changed. Re-run with --confirm.");
-    Ok(())
-}
-
-fn print_inventory(intent: Intent, database: &Path, material: &KeyMaterial) {
-    match intent {
-        Intent::Rotate => {
-            println!("Rotating the instance key of {}.", database.display());
-            println!();
-            println!(
-                "  {} Subsonic credential(s) — moved to the new key; password and API key both keep working",
-                material.subsonic_credentials
-            );
-            println!(
-                "  {} scrobbling link(s) — moved to the new key, unchanged",
-                material.scrobble_links
-            );
-            println!(
-                "  {} share(s) — kept, but every public URL changes",
-                material.shares
-            );
-        }
-        Intent::Adopt => {
-            println!("Adopting {} under a new instance key.", database.display());
-            println!();
-            println!("The old key is gone, so nothing sealed under it can be carried over:");
-            println!();
-            // The API key is not encrypted — it is a SHA-256 hash, which no key
-            // change touches — but it shares the row with the password that is,
-            // and the columns are `NOT NULL`. So the row goes whole, and the
-            // operator who reads "password" and thinks only of a password finds
-            // their clients locked out too.
-            println!(
-                "  {} Subsonic credential(s) — deleted, password and `wfsk_` API key together; `credential set` mints a new pair to hand to each client",
-                material.subsonic_credentials
-            );
-            println!(
-                "  {} scrobbling link(s) — deleted, and the {} queued listen(s) behind them",
-                material.scrobble_links, material.queued_listens
-            );
-            println!(
-                "  {} share(s) — kept, but every public URL changes",
-                material.shares
-            );
-            println!();
-            println!("Everything else is untouched: every account and its web password, the whole");
-            println!("catalogue, favourites, ratings, playlists, queues, history and bookmarks.");
-        }
-    }
-    println!();
-}
-
-/// Puts a file on disk, rather than in the page cache.
-///
-/// Opened differently on the two platforms, and neither spelling works on
-/// both. Windows refuses `FlushFileBuffers` on a handle with no write access
-/// and answers "Access is denied" to a call only asking for durability —
-/// measured, after three tests failed on it. Unix allows `fsync` on a
-/// read-only descriptor, and has to be asked that way: `fs::copy` carries the
-/// source's permissions over, so a hardened `instance.key` at mode 0400 makes
-/// its own copy unopenable for writing, and demanding write access here would
-/// turn a sensible precaution into a server that cannot rotate its key.
-async fn sync_file(path: &Path) -> std::io::Result<()> {
-    #[cfg(unix)]
-    {
-        tokio::fs::File::open(path).await?.sync_all().await
-    }
-    #[cfg(not(unix))]
-    {
-        tokio::fs::OpenOptions::new()
-            .write(true)
-            .open(path)
-            .await?
-            .sync_all()
-            .await
-    }
-}
-
-/// Puts a *directory entry* on disk — a file created, or renamed into place.
-///
-/// Writing a file and synchronising it says nothing about the directory that
-/// now claims to hold it, and the event these two commands guard against is
-/// exactly the one that does not ask politely: a machine that stops between
-/// the database committing to a new key and the file holding that key
-/// becoming real.
-///
-/// Unix only, and not an oversight: a Windows directory cannot be opened as a
-/// file to be synchronised, and `fs::rename` there goes through `MoveFileEx`,
-/// which is atomic but carries no equivalent promise. Nothing in this
-/// repository can test any of it — a power cut is not an inversion — so it is
-/// written for the property rather than for a test, and said so here.
-async fn sync_directory(path: &Path) -> std::io::Result<()> {
-    #[cfg(unix)]
-    {
-        tokio::fs::File::open(path).await?.sync_all().await?;
-    }
-    #[cfg(not(unix))]
-    {
-        let _ = path;
-    }
-    Ok(())
-}
-
-/// The pair as this command found it, before a single statement touches it.
-///
-/// Before the migration as well as before the key, which is the whole reason
-/// it is its own step: a copy taken afterwards would be a database at a schema
-/// the operator never ran, and restoring it would not undo what they asked to
-/// undo. `database restore` leaves the same kind of directory behind.
-async fn copy_the_pair_aside(
-    config: &crate::Config,
-    connection: &mut sqlx::SqliteConnection,
-) -> anyhow::Result<PathBuf> {
-    let recovery = config
-        .data_dir
-        .join(format!("pre-key-{}", chrono::Utc::now().timestamp_millis()));
-    tokio::fs::create_dir_all(&recovery).await?;
-    let saved = recovery.join("waveflow.db");
-    let saved = saved
-        .to_str()
-        .ok_or_else(|| anyhow::anyhow!("the recovery path is not valid UTF-8"))?;
-    sqlx::query("VACUUM INTO ?")
-        .bind(saved)
-        .execute(&mut *connection)
-        .await
-        .map_err(|error| anyhow::anyhow!("could not write the recovery copy: {error}"))?;
-    sync_file(Path::new(saved)).await?;
-    if config.instance_key_path.exists() {
-        let saved_key = recovery.join("instance.key");
-        tokio::fs::copy(&config.instance_key_path, &saved_key).await?;
-        sync_file(&saved_key).await?;
-    }
-    // The two files, and then the directory that is supposed to contain them.
-    // This happens before anything is changed, so a failure here is a refusal
-    // rather than a half-finished operation — which is the right way round for
-    // the one copy the operator would reach for.
-    sync_directory(&recovery).await?;
-    Ok(recovery)
-}
-
-/// Moves the values, then the key file — and answers with what was moved.
-///
-/// Not with what was predicted a moment earlier: the inventory comes from
-/// reading the tables, this comes from the statements that touched them, and a
-/// line printed from the second is the only one reporting the operation rather
-/// than the plan.
-async fn install_new_key(
-    config: &crate::Config,
-    mut connection: sqlx::SqliteConnection,
-    plan: Rekey<'_>,
-) -> anyhow::Result<KeyMaterial> {
-    // Staged rather than written in place. The key file is the last thing to
-    // move: one that arrived before the commit would name a database that
-    // never changed.
-    let staged = config
-        .data_dir
-        .join(format!(".key-{}.tmp", uuid::Uuid::new_v4()));
-    let new_bytes = security::SecretBox::create_instance_key(&staged)?;
-    let new_key = security::SecretBox::from_key_bytes(&new_bytes)?;
-    // Two files now exist in the data directory that nothing has yet promised
-    // will still be there: the `pre-key-…` directory and this staged key. The
-    // copy made each of *its* entries durable, and neither made durable the
-    // entry naming it. So the data directory is synchronised here — after the
-    // staged key exists and before the commit below, because after the commit
-    // is too late: a machine stopping in that window would come back with a
-    // database bound to a new key, no file holding it, and no copy to go back
-    // to. Which is the whole of what this command exists to prevent, arrived
-    // at by the command itself.
-    sync_directory(&config.data_dir).await?;
-    let moved = match Database::rekey(
-        &mut connection,
-        plan,
-        &new_key,
-        &security::bytes_hash(&new_bytes),
-        now_ms(),
-    )
-    .await
-    {
-        Ok(moved) => moved,
-        Err(error) => {
-            tokio::fs::remove_file(&staged).await.ok();
-            return Err(error);
-        }
-    };
-    // Releases the exclusive lock and checkpoints the write-ahead log, so the
-    // database is settled on disk before the other half of the pair moves.
-    //
-    // Past the commit above, a failure here is not a failed operation but an
-    // unfinished one: the database already answers to the new key, and the
-    // only thing missing is the file. So the error says where that file is,
-    // rather than leaving an operator with a server that will not start and
-    // nothing naming the thing that would start it.
-    let unfinished = || {
-        format!(
-            "the database is already bound to the new key; move {} onto {} to finish",
-            staged.display(),
-            config.instance_key_path.display()
-        )
-    };
-    connection.close().await.with_context(unfinished)?;
-    tokio::fs::rename(&staged, &config.instance_key_path)
-        .await
-        .with_context(unfinished)?;
-    // The rename is atomic; the directory entry it made is not durable until
-    // the directory itself is synchronised. Reported rather than returned as
-    // an error: the change is complete by now, and failing here would hide the
-    // recovery path the caller is about to print — which is the one thing an
-    // operator would need next.
-    if let Some(parent) = config.instance_key_path.parent() {
-        if let Err(error) = sync_directory(parent).await {
-            eprintln!(
-                "warning: {} is in place but its directory could not be synchronised ({error}); take a backup before anything else",
-                config.instance_key_path.display()
-            );
-        }
-    }
-    Ok(moved)
-}
-
-fn report_done(recovery: &Path) {
-    println!(
-        "The previous pair is recoverable from {}",
-        recovery.display()
-    );
-    println!("Start the server; it opens on the new key.");
-    // The command exists because somebody lost a key. Saying this at the one
-    // moment they are looking at a new one costs a line.
-    println!("Then take a fresh `database backup`: the new key is as unrecoverable as the last.");
-}
-
-async fn backup(state: &AppState, args: BackupArgs) -> anyhow::Result<()> {
-    if args.output.exists() {
-        anyhow::bail!("backup output already exists: {}", args.output.display());
-    }
-    tokio::fs::create_dir_all(&args.output).await?;
-    let database = args.output.join("waveflow.db");
-    state.db.backup_to(&database).await?;
-    tokio::fs::copy(&state.instance_key_path, args.output.join("instance.key")).await?;
-    if !Database::check_file(&database).await? {
-        anyhow::bail!("created backup failed integrity check");
-    }
-    let backup_key = tokio::fs::read(args.output.join("instance.key")).await?;
-    if !Database::check_file_instance_key(&database, &security::bytes_hash(&backup_key)).await? {
-        anyhow::bail!("created backup database and instance.key do not match");
-    }
-    println!("Backup created at {}", args.output.display());
-    Ok(())
-}
-
-pub async fn restore(config: &crate::Config, args: RestoreArgs) -> anyhow::Result<()> {
-    let source_db = args.input.join("waveflow.db");
-    let source_key = args.input.join("instance.key");
-    if !Database::check_file(&source_db).await? {
-        anyhow::bail!("backup SQLite integrity check failed");
-    }
-    let source_key_bytes = tokio::fs::read(&source_key).await?;
-    if source_key_bytes.len() != 32 {
-        anyhow::bail!("backup instance.key must contain exactly 32 bytes");
-    }
-    if !Database::check_file_instance_key(&source_db, &security::bytes_hash(&source_key_bytes))
-        .await?
-    {
-        anyhow::bail!("backup database and instance.key do not match");
-    }
-    tokio::fs::create_dir_all(&config.data_dir).await?;
-    let suffix = uuid::Uuid::new_v4();
-    let staged_db = config.data_dir.join(format!(".restore-{suffix}.db"));
-    let staged_key = config.data_dir.join(format!(".restore-{suffix}.key"));
-    tokio::fs::copy(&source_db, &staged_db).await?;
-    tokio::fs::copy(&source_key, &staged_key).await?;
-    if !Database::check_file(&staged_db).await? {
-        anyhow::bail!("staged SQLite restore failed integrity check");
-    }
-    let recovery = config.data_dir.join(format!(
-        "pre-restore-{}",
-        chrono::Utc::now().timestamp_millis()
-    ));
-    tokio::fs::create_dir_all(&recovery).await?;
-    if config.database_path.exists() {
-        tokio::fs::rename(&config.database_path, recovery.join("waveflow.db")).await?;
-    }
-    if config.instance_key_path.exists() {
-        tokio::fs::rename(&config.instance_key_path, recovery.join("instance.key")).await?;
-    }
-    tokio::fs::rename(&staged_db, &config.database_path).await?;
-    tokio::fs::rename(&staged_key, &config.instance_key_path).await?;
-    println!(
-        "Backup restored; previous files are recoverable from {}",
-        recovery.display()
-    );
-    Ok(())
-}
-
-async fn create_account(
-    db: &Database,
-    args: CreateAccountArgs,
-    role: AccountRole,
-) -> anyhow::Result<()> {
-    validate_username(&args.username)?;
-    let password = read_secret_env(&args.password_env)?;
-    let password_hash = tokio::task::spawn_blocking(move || security::hash_password(&password))
-        .await
-        .context("password worker failed")??;
-    let id = db
-        .create_account(&args.username, &password_hash, role, now_ms())
-        .await
-        .context("create account")?;
-    println!("Created {} account {} ({id})", role.as_str(), args.username);
-    Ok(())
-}
-
-async fn add_library(state: &AppState, args: AddLibraryArgs) -> anyhow::Result<()> {
-    let owner = state
-        .db
-        .account_by_username(&args.owner)
-        .await?
-        .with_context(|| format!("account not found: {}", args.owner))?;
-    let metadata = std::fs::symlink_metadata(&args.path)
-        .with_context(|| format!("library path is unavailable: {}", args.path.display()))?;
-    if metadata.file_type().is_symlink() {
-        anyhow::bail!("library root cannot be a symbolic link");
-    }
-    if !metadata.is_dir() {
-        anyhow::bail!("library path must be a directory");
-    }
-    let canonical = std::fs::canonicalize(&args.path)?;
-    let visibility = LibraryVisibility::from_str(&args.visibility)?;
-    let id = state
-        .db
-        .create_library(owner.id, &args.name, &canonical, visibility, now_ms())
-        .await
-        .context("register library")?;
-    state.scanner.libraries_changed();
-    println!("Registered library {} ({id})", args.name);
-    let scan_id = state
-        .scanner
-        .trigger(
-            LibraryRecord {
-                id,
-                name: args.name,
-                root_path: canonical,
-            },
-            Some(owner.id),
-            "library_added",
-        )
-        .await?;
-    loop {
-        let job = state
-            .db
-            .scan_job_for_user(owner.id, scan_id)
-            .await?
-            .context("new library scan disappeared")?;
-        match job.status.as_str() {
-            "completed" => {
-                println!(
-                    "Initial scan complete: {} added, {} errors",
-                    job.added, job.errors
-                );
-                break;
-            }
-            "failed" => anyhow::bail!(
-                "initial scan failed: {}",
-                job.message.unwrap_or_else(|| "unknown error".into())
-            ),
-            _ => tokio::time::sleep(std::time::Duration::from_millis(50)).await,
-        }
-    }
-    Ok(())
-}
-
-/// What a refused library operation says on a terminal. The services answer
-/// in their own vocabulary; an operator needs a sentence.
-fn library_refusal(error: crate::services::ServiceError, library_id: uuid::Uuid) -> anyhow::Error {
-    use crate::services::ServiceError;
-    match error {
-        ServiceError::NotFound | ServiceError::Forbidden => {
-            anyhow::anyhow!("library not found: {library_id}")
-        }
-        ServiceError::Conflict => anyhow::anyhow!(
-            "library {library_id} is being scanned, or another library already has that path; \
-             try again once the scan is over"
-        ),
-        ServiceError::Invalid => anyhow::anyhow!("the request was refused as invalid"),
-        other => anyhow::anyhow!(other),
-    }
-}
-
-/// Waits for a scan this command queued, and prints how it ended. The process
-/// is about to exit, and the scan is a task of this process: leaving it would
-/// kill it halfway.
-async fn wait_for_scan(state: &AppState, scan_id: uuid::Uuid) -> anyhow::Result<()> {
-    loop {
-        let job = state
-            .db
-            .scan_job(scan_id)
-            .await?
-            .context("the scan disappeared")?;
-        match job.status.as_str() {
-            "completed" => {
-                println!(
-                    "Scan complete: {} added, {} updated, {} moved, {} missing, {} errors",
-                    job.added, job.updated, job.moved, job.unavailable, job.errors
-                );
-                return Ok(());
-            }
-            "failed" => anyhow::bail!(
-                "scan failed: {}",
-                job.message.unwrap_or_else(|| "unknown error".into())
-            ),
-            _ => tokio::time::sleep(std::time::Duration::from_millis(50)).await,
-        }
-    }
-}
-
-async fn rename_library(state: &AppState, args: RenameLibraryArgs) -> anyhow::Result<()> {
-    let actor = require_admin(&state.db, &args.actor).await?;
-    state
-        .services
-        .update_library(
-            crate::services::LibraryActor::operator(actor.id),
-            args.library_id,
-            crate::services::LibraryUpdate {
-                name: Some(args.name.clone()),
-                ..Default::default()
-            },
-        )
-        .await
-        .map_err(|error| library_refusal(error, args.library_id))?;
-    println!(
-        "Library {} is now named {}",
-        args.library_id,
-        args.name.trim()
-    );
-    Ok(())
-}
-
-async fn set_library_path(state: &AppState, args: SetPathArgs) -> anyhow::Result<()> {
-    let actor = require_admin(&state.db, &args.actor).await?;
-    let updated = state
-        .services
-        .update_library(
-            crate::services::LibraryActor::operator(actor.id),
-            args.library_id,
-            crate::services::LibraryUpdate {
-                path: Some(args.path.to_string_lossy().into_owned()),
-                ..Default::default()
-            },
-        )
-        .await
-        .map_err(|error| match error {
-            crate::services::ServiceError::Invalid => anyhow::anyhow!(
-                "library path must be an existing directory and not a symbolic link: {}",
-                args.path.display()
-            ),
-            other => library_refusal(other, args.library_id),
-        })?;
-    match updated.scan_id {
-        Some(scan_id) => {
-            println!("Library {} moved; scanning it", args.library_id);
-            wait_for_scan(state, scan_id).await
-        }
-        None => {
-            println!("Library {} already has that path", args.library_id);
-            Ok(())
-        }
-    }
-}
-
-async fn set_library_links(state: &AppState, args: SetLinksArgs) -> anyhow::Result<()> {
-    let actor = require_admin(&state.db, &args.actor).await?;
-    let updated = state
-        .services
-        .update_library(
-            crate::services::LibraryActor::operator(actor.id),
-            args.library_id,
-            crate::services::LibraryUpdate {
-                follow_links: Some(args.follow),
-                ..Default::default()
-            },
-        )
-        .await
-        .map_err(|error| library_refusal(error, args.library_id))?;
-    println!(
-        "Library {} {} symbolic links",
-        args.library_id,
-        if args.follow {
-            "follows"
-        } else {
-            "does not follow"
-        }
-    );
-    match updated.scan_id {
-        Some(scan_id) => wait_for_scan(state, scan_id).await,
-        None => Ok(()),
-    }
-}
-
-async fn delete_library(state: &AppState, args: DeleteLibraryArgs) -> anyhow::Result<()> {
-    let actor = require_admin(&state.db, &args.actor).await?;
-    let deleted = state
-        .services
-        .delete_library(
-            crate::services::LibraryActor::operator(actor.id),
-            args.library_id,
-            &args.confirm,
-        )
-        .await
-        .map_err(|error| match error {
-            crate::services::ServiceError::Invalid => {
-                anyhow::anyhow!("--confirm must be the library's current name; nothing was deleted")
-            }
-            other => library_refusal(other, args.library_id),
-        })?;
-    println!(
-        "Deleted library {}: {} tracks, {} albums, {} artists removed from the catalogue; \
-         no file was touched",
-        args.library_id, deleted.tracks, deleted.albums, deleted.artists
-    );
-    Ok(())
-}
-
-async fn list_unavailable(state: &AppState, args: UnavailableArgs) -> anyhow::Result<()> {
-    let actor = require_admin(&state.db, &args.actor).await?;
-    let mut offset = 0;
-    loop {
-        let page = crate::services::BrowsePage::new(Some(offset), Some(200))
-            .map_err(|error| library_refusal(error, args.library_id))?;
-        let listed = state
-            .services
-            .unavailable_tracks(
-                crate::services::LibraryActor::operator(actor.id),
-                args.library_id,
-                page,
-            )
-            .await
-            .map_err(|error| library_refusal(error, args.library_id))?;
-        if offset == 0 {
-            println!("{} missing track(s)", listed.total);
-        }
-        for track in &listed.tracks {
-            println!(
-                "{}\t{}\t{} playlist entries, {} favourites, {} plays",
-                track.id, track.relative_path, track.playlist_entries, track.favorites, track.plays
-            );
-        }
-        if listed.tracks.len() < 200 {
-            return Ok(());
-        }
-        offset += 200;
-    }
-}
-
-async fn purge_unavailable(state: &AppState, args: PurgeArgs) -> anyhow::Result<()> {
-    let actor = require_admin(&state.db, &args.actor).await?;
-    if !args.all && args.track_id.is_empty() {
-        anyhow::bail!("name the tracks to purge with --track-id, or pass --all");
-    }
-    let outcome = state
-        .services
-        .purge_unavailable_tracks(
-            crate::services::LibraryActor::operator(actor.id),
-            args.library_id,
-            crate::services::PurgeRequest {
-                track_ids: (!args.all).then_some(args.track_id),
-                all: args.all,
-            },
-        )
-        .await
-        .map_err(|error| library_refusal(error, args.library_id))?;
-    match outcome.restorable_until {
-        Some(until) => println!(
-            "Purged {} missing track(s); restorable until {until} (epoch ms) with `library restore`",
-            outcome.purged
-        ),
-        None => println!("Purged {} missing track(s)", outcome.purged),
-    }
-    Ok(())
-}
-
-async fn restore_purged(state: &AppState, args: PurgeArgs) -> anyhow::Result<()> {
-    let actor = require_admin(&state.db, &args.actor).await?;
-    if !args.all && args.track_id.is_empty() {
-        anyhow::bail!("name the tracks to restore with --track-id, or pass --all");
-    }
-    let outcome = state
-        .services
-        .restore_purged_tracks(
-            crate::services::LibraryActor::operator(actor.id),
-            args.library_id,
-            crate::services::PurgeRequest {
-                track_ids: (!args.all).then_some(args.track_id),
-                all: args.all,
-            },
-        )
-        .await
-        .map_err(|error| library_refusal(error, args.library_id))?;
-    println!("Restored {} purged track(s)", outcome.restored);
-    Ok(())
-}
-
-async fn set_library_watch(state: &AppState, args: SetWatchArgs) -> anyhow::Result<()> {
-    let actor = require_admin(&state.db, &args.actor).await?;
-    state
-        .services
-        .update_library(
-            crate::services::LibraryActor::operator(actor.id),
-            args.library_id,
-            crate::services::LibraryUpdate {
-                watch: Some(args.watch),
-                ..Default::default()
-            },
-        )
-        .await
-        .map_err(|error| library_refusal(error, args.library_id))?;
-    println!(
-        "Library {} is {}",
-        args.library_id,
-        if args.watch {
-            "watched for changes"
-        } else {
-            "left to the periodic scan"
-        }
-    );
-    Ok(())
-}
-
-async fn set_member(db: &Database, args: SetMemberArgs) -> anyhow::Result<()> {
-    let actor = require_admin(db, &args.actor).await?;
-    let member = db
-        .account_by_username(&args.username)
-        .await?
-        .with_context(|| format!("account not found: {}", args.username))?;
-    let role = LibraryRole::from_str(&args.role)?;
-    if role == LibraryRole::Owner {
-        anyhow::bail!("library ownership cannot be transferred with set-member");
-    }
-    db.add_library_member(actor.id, args.library_id, member.id, role, now_ms())
-        .await?;
-    println!("Updated member {} on {}", args.username, args.library_id);
-    Ok(())
-}
-
-async fn set_uploads(db: &Database, args: SetUploadsArgs) -> anyhow::Result<()> {
-    let actor = require_admin(db, &args.actor).await?;
-    if !db
-        .set_library_accepts_uploads(actor.id, args.library_id, args.accept, now_ms())
-        .await?
-    {
-        anyhow::bail!("library not found: {}", args.library_id);
-    }
-    println!(
-        "Library {} {} uploads",
-        args.library_id,
-        if args.accept { "accepts" } else { "refuses" }
-    );
-    Ok(())
-}
-
-async fn set_canvas(db: &Database, args: SetCanvasArgs) -> anyhow::Result<()> {
-    let actor = require_admin(db, &args.actor).await?;
-    if !db
-        .set_library_accepts_canvas(actor.id, args.library_id, args.accept, now_ms())
-        .await?
-    {
-        anyhow::bail!("library not found: {}", args.library_id);
-    }
-    println!(
-        "Library {} {} canvases",
-        args.library_id,
-        if args.accept { "accepts" } else { "refuses" }
-    );
-    Ok(())
-}
-
-async fn remove_member(db: &Database, args: RemoveMemberArgs) -> anyhow::Result<()> {
-    let actor = require_admin(db, &args.actor).await?;
-    let member = db
-        .account_by_username(&args.username)
-        .await?
-        .with_context(|| format!("account not found: {}", args.username))?;
-    if !db
-        .remove_library_member(actor.id, args.library_id, member.id, now_ms())
-        .await?
-    {
-        anyhow::bail!("membership not found or library owner cannot be removed");
-    }
-    println!("Removed member {} from {}", args.username, args.library_id);
-    Ok(())
-}
-
-async fn set_credential(
-    db: &Database,
-    secret_box: &security::SecretBox,
-    args: SetCredentialArgs,
-) -> anyhow::Result<()> {
-    let actor = require_admin(db, &args.actor).await?;
-    let user = db
-        .account_by_username(&args.username)
-        .await?
-        .with_context(|| format!("account not found: {}", args.username))?;
-    let password = read_secret_env(&args.password_env)?;
-    if password.len() < 12 {
-        anyhow::bail!("Subsonic password must contain at least 12 characters");
-    }
-    let encrypted = secret_box.encrypt(password.as_bytes())?;
-    let api_key = security::generate_token("wfsk_");
-    let api_key_hash = security::token_hash(&api_key);
-    db.set_subsonic_credential(actor.id, user.id, &encrypted, &api_key_hash, now_ms())
-        .await?;
-    // The API key goes to standard output on its own, and everything a person
-    // reads goes to standard error. That way `set-credential … > key` yields the
-    // key and nothing else, and an operator never has to lift a secret out of a
-    // scrollback that then keeps it. Interactively both streams still land on
-    // the same terminal, so this reads the way it always did.
-    eprintln!("Subsonic credential updated for {}", args.username);
-    eprintln!("API key (shown once, on standard output):");
-    println!("{api_key}");
-    Ok(())
-}
-
-async fn revoke_credential(db: &Database, args: RevokeCredentialArgs) -> anyhow::Result<()> {
-    let actor = require_admin(db, &args.actor).await?;
-    let user = db
-        .account_by_username(&args.username)
-        .await?
-        .with_context(|| format!("account not found: {}", args.username))?;
-    if !db
-        .revoke_subsonic_credential(actor.id, user.id, now_ms())
-        .await?
-    {
-        anyhow::bail!("no Subsonic credential exists for {}", args.username);
-    }
-    println!("Revoked Subsonic credential for {}", args.username);
-    Ok(())
-}
-
-/// Bootstraps a token on an instance with no administrator session yet.
-///
-/// Issuing one is also an HTTP route now, so this goes through the same
-/// domain service rather than writing the row itself: a token minted here and
-/// one minted over the API must carry the same validation and the same audit
-/// trail, which is exactly what two copies of the insert would not guarantee.
-async fn create_token(state: &AppState, args: CreateTokenArgs) -> anyhow::Result<()> {
-    let actor = require_admin(&state.db, &args.actor).await?;
-    let (record, token) = state
-        .services
-        .create_api_token(
-            actor.id,
-            // The command line holds the whole account authority: it is a
-            // shell on the host, not a credential that could have been
-            // narrowed.
-            &[],
-            &args.username,
-            &args.name,
-            &args.scopes,
-        )
-        .await?;
-    // Standard output carries the token alone; see `set_credential` for why.
-    eprintln!("Created API token {} for {}", record.id, args.username);
-    eprintln!("Token (shown once, on standard output):");
-    println!("{token}");
-    Ok(())
-}
-
-/// The destination named on the command line.
-///
-/// Through `FromStr`, which is the same reading the API and the `CHECK`
-/// constraint use. A `ValueEnum` here would be a fifth spelling of a fact that
-/// already has four, and one test holds those four together.
-fn scrobble_provider(raw: &str) -> anyhow::Result<crate::services::ScrobbleProvider> {
-    <crate::services::ScrobbleProvider as std::str::FromStr>::from_str(raw)
-        .map_err(|_| anyhow::anyhow!("unknown destination: {raw} (listenbrainz, maloja or lastfm)"))
-}
-
-/// Through `DomainServices`, never around it.
-///
-/// The same reasoning `create_token` carries: this mutation is also an HTTP
-/// route, and a link made here must carry the validation, the sealing and the
-/// generation semantics a link made there carries. Two copies of the insert
-/// would not guarantee that.
-async fn link_scrobble(state: &AppState, args: LinkScrobbleArgs) -> anyhow::Result<()> {
-    require_admin(&state.db, &args.actor).await?;
-    let user = state
-        .db
-        .account_by_username(&args.username)
-        .await?
-        .with_context(|| format!("account not found: {}", args.username))?;
-    let provider = scrobble_provider(&args.provider)?;
-    let secret = read_secret_env(&args.token_env)?;
-    state
-        .services
-        .link_scrobble(user.id, provider, &args.destination, &secret)
-        .await?;
-    println!(
-        "Linked {} to {}/{} (any previous authorisation there is withdrawn)",
-        args.username,
-        provider.as_str(),
-        args.destination
-    );
-    Ok(())
-}
-
-/// Asks Last.fm for a request token and prints what to do with it.
-///
-/// The account is resolved before anything leaves this machine: a token minted
-/// for a username that does not exist would be a call made for nothing, and
-/// the refusal is cheaper first.
-async fn authorize_lastfm(state: &AppState, args: AuthorizeLastFmArgs) -> anyhow::Result<()> {
-    require_admin(&state.db, &args.actor).await?;
-    state
-        .db
-        .account_by_username(&args.username)
-        .await?
-        .with_context(|| format!("account not found: {}", args.username))?;
-    let approval = state
-        .services
-        .begin_lastfm_approval(&args.destination)
-        .await?;
-    // The address and the token are the same secret twice — the token is in
-    // the address's query string. Both go to standard output because that is
-    // where the operator reads them, and nowhere else: nothing here is traced.
-    println!("Open this address as {}, and approve it:", args.username);
-    println!();
-    println!("  {}", approval.authorize_url);
-    println!();
-    println!("Then put this token in {}:", ExchangeLastFmArgs::TOKEN_ENV);
-    println!();
-    println!("  {}", approval.token);
-    println!();
-    println!("…and run:");
-    println!();
-    // **Deliberately not a line to paste with the token in it.** A first
-    // version printed `WAVEFLOW_LASTFM_TOKEN=… waveflow-server scrobble exchange …`,
-    // ready to copy — and a copied command line lands in a shell history,
-    // which is one of the two things `--token-env` exists to keep this token
-    // out of. Printing a recipe that undoes the flag's own reason would have
-    // been worse than having no flag.
-    //
-    // How the variable gets set is left to the operator and their shell: a
-    // silent `read`, a password manager, a file sourced and deleted. This
-    // server has no business choosing among those, and it runs on three
-    // platforms whose answers differ.
-    println!(
-        "  waveflow-server scrobble exchange --actor {} --username {} --destination {}",
-        args.actor, args.username, args.destination
-    );
-    println!();
-    println!("The token is Last.fm's and expires on their clock; this server wrote nothing down.");
-    Ok(())
-}
-
-/// Turns an approved request token into a link.
-async fn exchange_lastfm(state: &AppState, args: ExchangeLastFmArgs) -> anyhow::Result<()> {
-    require_admin(&state.db, &args.actor).await?;
-    let user = state
-        .db
-        .account_by_username(&args.username)
-        .await?
-        .with_context(|| format!("account not found: {}", args.username))?;
-    let token = read_secret_env(&args.token_env)?;
-    state
-        .services
-        .complete_lastfm_approval(user.id, &args.destination, &token)
-        .await?;
-    println!(
-        "Linked {} to lastfm/{} (any previous authorisation there is withdrawn)",
-        args.username, args.destination
-    );
-    Ok(())
-}
-
-async fn unlink_scrobble(state: &AppState, args: UnlinkScrobbleArgs) -> anyhow::Result<()> {
-    require_admin(&state.db, &args.actor).await?;
-    let user = state
-        .db
-        .account_by_username(&args.username)
-        .await?
-        .with_context(|| format!("account not found: {}", args.username))?;
-    let provider = scrobble_provider(&args.provider)?;
-    // Saying so rather than failing: the caller asked for this account to hold
-    // no authorisation there, and it holds none. The API answers the same way.
-    if state
-        .services
-        .unlink_scrobble(user.id, provider, &args.destination)
-        .await?
-    {
-        println!(
-            "Unlinked {} from {}/{}",
-            args.username,
-            provider.as_str(),
-            args.destination
-        );
-    } else {
-        println!(
-            "{} had no link to {}/{}",
-            args.username,
-            provider.as_str(),
-            args.destination
-        );
-    }
-    Ok(())
-}
-
-async fn scrobble_status(state: &AppState, args: ScrobbleStatusArgs) -> anyhow::Result<()> {
-    require_admin(&state.db, &args.actor).await?;
-    let user = state
-        .db
-        .account_by_username(&args.username)
-        .await?
-        .with_context(|| format!("account not found: {}", args.username))?;
-    let links = state.services.scrobble_links(user.id).await?;
-    if links.is_empty() {
-        println!("{} has no scrobbling links", args.username);
-        return Ok(());
-    }
-    for link in links {
-        // Counters, never content: decision 12 governs what this prints exactly
-        // as it governs what the route publishes.
-        println!(
-            "{:<13} {:<16} {:<9} pending {:<5} retrying {:<5} uncertain {:<5} {}",
-            link.provider.as_str(),
-            link.destination,
-            link.health,
-            link.pending,
-            link.retrying,
-            link.uncertain,
-            link.last_failure.as_deref().unwrap_or("-")
-        );
-    }
-    Ok(())
-}
-
 async fn require_admin(
     db: &Database,
     username: &str,
@@ -1653,27 +166,4 @@ fn validate_username(username: &str) -> anyhow::Result<()> {
 }
 
 #[cfg(test)]
-mod tests {
-    use super::non_blank;
-
-    #[test]
-    fn a_secret_of_whitespace_is_refused_and_the_variable_is_named() {
-        for blank in ["", " ", "\n", "  \t\r\n "] {
-            let refused = non_blank("WAVEFLOW_EXAMPLE_SECRET", blank.to_owned()).unwrap_err();
-            assert!(
-                refused.to_string().contains("WAVEFLOW_EXAMPLE_SECRET"),
-                "the message has to name the variable the person must fix"
-            );
-        }
-    }
-
-    /// Returned as it was found, never trimmed.
-    ///
-    /// The same path reads account and Subsonic passwords; trimming what it
-    /// hands back would silently alter a credential that already works.
-    #[test]
-    fn a_secret_with_padding_survives_intact() {
-        let kept = non_blank("WAVEFLOW_EXAMPLE_SECRET", "  a token  ".to_owned()).unwrap();
-        assert_eq!(kept, "  a token  ");
-    }
-}
+mod tests;
diff --git a/src/cli/scrobble.rs b/src/cli/scrobble.rs
new file mode 100644
index 00000000..cf245421
--- /dev/null
+++ b/src/cli/scrobble.rs
@@ -0,0 +1,190 @@
+//! `scrobble`: linking an account to a destination, the Last.fm approval
+//! split across a browser, and reading a link's queue.
+
+use anyhow::Context;
+
+use super::{
+    read_secret_env, require_admin, AuthorizeLastFmArgs, ExchangeLastFmArgs, LinkScrobbleArgs,
+    ScrobbleStatusArgs, UnlinkScrobbleArgs,
+};
+use crate::AppState;
+
+/// The destination named on the command line.
+///
+/// Through `FromStr`, which is the same reading the API and the `CHECK`
+/// constraint use. A `ValueEnum` here would be a fifth spelling of a fact that
+/// already has four, and one test holds those four together.
+fn scrobble_provider(raw: &str) -> anyhow::Result<crate::services::ScrobbleProvider> {
+    <crate::services::ScrobbleProvider as std::str::FromStr>::from_str(raw)
+        .map_err(|_| anyhow::anyhow!("unknown destination: {raw} (listenbrainz, maloja or lastfm)"))
+}
+
+/// Through `DomainServices`, never around it.
+///
+/// The same reasoning `create_token` carries: this mutation is also an HTTP
+/// route, and a link made here must carry the validation, the sealing and the
+/// generation semantics a link made there carries. Two copies of the insert
+/// would not guarantee that.
+pub(super) async fn link_scrobble(state: &AppState, args: LinkScrobbleArgs) -> anyhow::Result<()> {
+    require_admin(&state.db, &args.actor).await?;
+    let user = state
+        .db
+        .account_by_username(&args.username)
+        .await?
+        .with_context(|| format!("account not found: {}", args.username))?;
+    let provider = scrobble_provider(&args.provider)?;
+    let secret = read_secret_env(&args.token_env)?;
+    state
+        .services
+        .link_scrobble(user.id, provider, &args.destination, &secret)
+        .await?;
+    println!(
+        "Linked {} to {}/{} (any previous authorisation there is withdrawn)",
+        args.username,
+        provider.as_str(),
+        args.destination
+    );
+    Ok(())
+}
+
+/// Asks Last.fm for a request token and prints what to do with it.
+///
+/// The account is resolved before anything leaves this machine: a token minted
+/// for a username that does not exist would be a call made for nothing, and
+/// the refusal is cheaper first.
+pub(super) async fn authorize_lastfm(
+    state: &AppState,
+    args: AuthorizeLastFmArgs,
+) -> anyhow::Result<()> {
+    require_admin(&state.db, &args.actor).await?;
+    state
+        .db
+        .account_by_username(&args.username)
+        .await?
+        .with_context(|| format!("account not found: {}", args.username))?;
+    let approval = state
+        .services
+        .begin_lastfm_approval(&args.destination)
+        .await?;
+    // The address and the token are the same secret twice — the token is in
+    // the address's query string. Both go to standard output because that is
+    // where the operator reads them, and nowhere else: nothing here is traced.
+    println!("Open this address as {}, and approve it:", args.username);
+    println!();
+    println!("  {}", approval.authorize_url);
+    println!();
+    println!("Then put this token in {}:", ExchangeLastFmArgs::TOKEN_ENV);
+    println!();
+    println!("  {}", approval.token);
+    println!();
+    println!("…and run:");
+    println!();
+    // **Deliberately not a line to paste with the token in it.** A first
+    // version printed `WAVEFLOW_LASTFM_TOKEN=… waveflow-server scrobble exchange …`,
+    // ready to copy — and a copied command line lands in a shell history,
+    // which is one of the two things `--token-env` exists to keep this token
+    // out of. Printing a recipe that undoes the flag's own reason would have
+    // been worse than having no flag.
+    //
+    // How the variable gets set is left to the operator and their shell: a
+    // silent `read`, a password manager, a file sourced and deleted. This
+    // server has no business choosing among those, and it runs on three
+    // platforms whose answers differ.
+    println!(
+        "  waveflow-server scrobble exchange --actor {} --username {} --destination {}",
+        args.actor, args.username, args.destination
+    );
+    println!();
+    println!("The token is Last.fm's and expires on their clock; this server wrote nothing down.");
+    Ok(())
+}
+
+/// Turns an approved request token into a link.
+pub(super) async fn exchange_lastfm(
+    state: &AppState,
+    args: ExchangeLastFmArgs,
+) -> anyhow::Result<()> {
+    require_admin(&state.db, &args.actor).await?;
+    let user = state
+        .db
+        .account_by_username(&args.username)
+        .await?
+        .with_context(|| format!("account not found: {}", args.username))?;
+    let token = read_secret_env(&args.token_env)?;
+    state
+        .services
+        .complete_lastfm_approval(user.id, &args.destination, &token)
+        .await?;
+    println!(
+        "Linked {} to lastfm/{} (any previous authorisation there is withdrawn)",
+        args.username, args.destination
+    );
+    Ok(())
+}
+
+pub(super) async fn unlink_scrobble(
+    state: &AppState,
+    args: UnlinkScrobbleArgs,
+) -> anyhow::Result<()> {
+    require_admin(&state.db, &args.actor).await?;
+    let user = state
+        .db
+        .account_by_username(&args.username)
+        .await?
+        .with_context(|| format!("account not found: {}", args.username))?;
+    let provider = scrobble_provider(&args.provider)?;
+    // Saying so rather than failing: the caller asked for this account to hold
+    // no authorisation there, and it holds none. The API answers the same way.
+    if state
+        .services
+        .unlink_scrobble(user.id, provider, &args.destination)
+        .await?
+    {
+        println!(
+            "Unlinked {} from {}/{}",
+            args.username,
+            provider.as_str(),
+            args.destination
+        );
+    } else {
+        println!(
+            "{} had no link to {}/{}",
+            args.username,
+            provider.as_str(),
+            args.destination
+        );
+    }
+    Ok(())
+}
+
+pub(super) async fn scrobble_status(
+    state: &AppState,
+    args: ScrobbleStatusArgs,
+) -> anyhow::Result<()> {
+    require_admin(&state.db, &args.actor).await?;
+    let user = state
+        .db
+        .account_by_username(&args.username)
+        .await?
+        .with_context(|| format!("account not found: {}", args.username))?;
+    let links = state.services.scrobble_links(user.id).await?;
+    if links.is_empty() {
+        println!("{} has no scrobbling links", args.username);
+        return Ok(());
+    }
+    for link in links {
+        // Counters, never content: decision 12 governs what this prints exactly
+        // as it governs what the route publishes.
+        println!(
+            "{:<13} {:<16} {:<9} pending {:<5} retrying {:<5} uncertain {:<5} {}",
+            link.provider.as_str(),
+            link.destination,
+            link.health,
+            link.pending,
+            link.retrying,
+            link.uncertain,
+            link.last_failure.as_deref().unwrap_or("-")
+        );
+    }
+    Ok(())
+}
diff --git a/src/cli/tests.rs b/src/cli/tests.rs
new file mode 100644
index 00000000..522f0240
--- /dev/null
+++ b/src/cli/tests.rs
@@ -0,0 +1,22 @@
+use super::non_blank;
+
+#[test]
+fn a_secret_of_whitespace_is_refused_and_the_variable_is_named() {
+    for blank in ["", " ", "\n", "  \t\r\n "] {
+        let refused = non_blank("WAVEFLOW_EXAMPLE_SECRET", blank.to_owned()).unwrap_err();
+        assert!(
+            refused.to_string().contains("WAVEFLOW_EXAMPLE_SECRET"),
+            "the message has to name the variable the person must fix"
+        );
+    }
+}
+
+/// Returned as it was found, never trimmed.
+///
+/// The same path reads account and Subsonic passwords; trimming what it
+/// hands back would silently alter a credential that already works.
+#[test]
+fn a_secret_with_padding_survives_intact() {
+    let kept = non_blank("WAVEFLOW_EXAMPLE_SECRET", "  a token  ".to_owned()).unwrap();
+    assert_eq!(kept, "  a token  ");
+}