From 6f3e7b8741bbe8fdacc98cfb200c7753c6ee168a Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Tue, 13 Oct 2026 20:14:03 +0200
Subject: [PATCH 1/5] feat(server): a way back from a lost or compromised
 instance key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`key rotate` carries every sealed value onto a new key; `key adopt` takes a
database over when the old one is gone, discarding what only it could read.
Two commands rather than one and a flag, because the second destroys exactly
what the first preserves — and `adopt` refuses outright when the key beside
the database still opens it, since that is a rotation and a rotation costs
nothing.

Both run before the boot they exist to unblock, since that boot is the one
that aborts on a mismatched pair. Both take the database exclusively —
`locking_mode=EXCLUSIVE` and an immediate `BEGIN EXCLUSIVE`, which a running
server's open connections refuse, and which then stays held for the whole
operation rather than being a check with a gap after it. Both count what the
change costs from the tables, print it, and change nothing until `--confirm`.
The previous pair goes into `data/pre-key-<ms>` first, the way `database
restore` already does, and the new key file is renamed into place only once
the transaction has committed.

Shares are the part the manual procedure in the operations guide got wrong. A
share token is *derived* from the instance key rather than stored, so a key
change that leaves `token_hash` alone does not re-address the share, it
strands it: the hash is one no later key can produce, and the owner is shown
a URL that answers 404. Both commands recompute those hashes, which is what
makes "shares survive, with a new URL" true rather than hoped for.

The scrobbling queue is the part an operator would not predict. `scrobble_outbox`
hangs off `scrobble_link` by `ON DELETE CASCADE`, so discarding the links
discards the listens behind them — counted and printed for that reason, and
`rekey` asks for `PRAGMA foreign_keys = ON` itself rather than trusting the
caller, because `migrate_on` leaves it off and a cascade that did not fire
leaves no error, only rows.

`migrate_on` is extracted from `migrate` so both paths run one migration
routine: the commands write rows, and writing rows into a schema older than
the binary is how a repair becomes damage — `scrobble_link` does not exist
before 2.0.0-beta.1.

Fourteen inversions, each made to fail on the assertion that names it. One of
them passed at first: the fixture seeded one of everything, so an assertion on
the printed counts held with two of its four fields swapped. The fixture now
seeds four different numbers.

Closes #221

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 README.md                               |   2 +-
 docs/operations.md                      |  62 ++-
 docs/rfcs/RFC-002-waveflow-server-v2.md |   2 +-
 src/cli.rs                              | 254 ++++++++++-
 src/database.rs                         | 338 +++++++++++++-
 src/main.rs                             |   3 +
 src/security.rs                         |  32 +-
 tests/cli.rs                            | 567 ++++++++++++++++++++++++
 8 files changed, 1219 insertions(+), 41 deletions(-)

diff --git a/README.md b/README.md
index 72b3a6d5..efc1164e 100644
--- a/README.md
+++ b/README.md
@@ -111,7 +111,7 @@ Point any Subsonic client at `http://your-host:4533` with that username and pass
 | **Scrobbling** | ListenBrainz, Last.fm and Maloja, each a named instance, behind a durable queue that survives a restart, retries once and honours `Retry-After` | [RFC-010](docs/rfcs/RFC-010-external-scrobbling.md) |
 | **Web player** | React 19 client compiled into the binary — complete player and administration surface, authenticated artwork, Media Session, preloading, keyboard controls, 14 localized themes, English and French, responsive | — |
 | **Security** | Argon2id passwords, tokens stored only as SHA-256 hashes, the dedicated Subsonic password encrypted with ChaCha20-Poly1305 under a local instance key, stream tickets so `<audio src>` needs no header, origin validation and CSRF protection for browsers | [operations](docs/operations.md) |
-| **Operations** | Single-file SQLite in WAL with one process-wide writer, immutable checksummed migrations, coherent backup and restore of the database/key pair, `/health` and `/ready`, JSON logging that never records a query string or a token | [operations](docs/operations.md) |
+| **Operations** | Single-file SQLite in WAL with one process-wide writer, immutable checksummed migrations, coherent backup and restore of the database/key pair and a way back from a lost or compromised key, `/health` and `/ready`, JSON logging that never records a query string or a token | [operations](docs/operations.md) |
 
 ## Documentation
 
diff --git a/docs/operations.md b/docs/operations.md
index e65564bd..d0669bc7 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -37,47 +37,65 @@ Almost everything is unaffected, because almost nothing is encrypted:
 | Lost, and re-entered by hand | Survives untouched |
 | --- | --- |
 | The dedicated Subsonic password of every account | Every account, and its web password — Argon2id, never encrypted |
-| Every external scrobbling link (Last.fm, ListenBrainz, Maloja) | The whole catalogue: tracks, albums, artists, libraries and their members |
+| Every external scrobbling link (Last.fm, ListenBrainz, Maloja), and the listens queued behind it | The whole catalogue: tracks, albums, artists, libraries and their members |
 | | Favourites, ratings, playlists, play queues, listening history, bookmarks |
 
 Shares are kept but **their public URLs change**: a share token is derived from
 the instance key rather than stored, so every link handed out under the old key
-stops resolving.
+stops resolving. The commands below recompute the stored hash under the new
+key, which is what keeps the share reachable at its new address instead of
+stranding it at an old one nobody can produce again.
 
 Stream tickets are sealed under the key too. They last an hour and are minted on
 demand, so nothing has to be done about them — but it is also why a leaked key
 matters even when almost nothing is encrypted under it: whoever holds one can
 mint a ticket for any track they can address.
 
-### The procedure
+### Two commands, because there are two situations
 
-There is no command for this yet
-([#221](https://github.com/InstaZDLL/waveflow-server/issues/221)). Until there
-is, it is two writes and a deleted file, with the server **stopped**:
+They are named apart rather than separated by a flag, because one preserves
+exactly what the other destroys.
 
-```sql
--- Values only the old key could read. They are unreadable now, not damaged.
-DELETE FROM subsonic_credential;
-DELETE FROM scrobble_link;
--- Release the fingerprint. The next start binds whatever key it finds.
-DELETE FROM instance_metadata;
+Both run with the server **stopped** — they take the database exclusively and
+refuse a database another process is holding — and both are a reading until you say
+otherwise: without `--confirm` they count what the change costs, print it, and
+change nothing.
+
+**The old key is in hand**, and you want a different one — it leaked, or it is
+simply time:
+
+```bash
+waveflow-server key rotate             # what it would cost
+waveflow-server key rotate --confirm
 ```
 
+Every encrypted value is read with the old key and written back under the new
+one. Nothing is lost at all; the share URLs change and that is the whole of it.
+
+**The old key is gone**, and nothing can be carried over:
+
 ```bash
-rm data/instance.key
+waveflow-server key adopt
+waveflow-server key adopt --confirm
 ```
 
-Start the server. It generates a fresh 32-byte key, binds its SHA-256 fingerprint
-to the database, and comes up on the catalogue you already had. Then re-set the
-Subsonic password of each account with `credential set`, and re-link any
-scrobbling destination.
+The Subsonic passwords and the scrobbling links go, the queued listens with
+them, and a fresh key is bound to the catalogue you already had. `adopt`
+refuses outright when the key beside the database still opens it: that is a
+rotation, and a rotation costs nothing.
 
-**Take a copy of `data/` before you begin.** The three deletions are not
-reversible, and a mistyped table name is a restore away from being someone's
-evening.
+Both move the previous pair into a timestamped `data/pre-key-…` directory
+before touching anything, the way `database restore` does. Afterwards, re-set
+the Subsonic password of each account with `credential set`, and re-link any
+scrobbling destination.
 
-Verified end to end on a real instance: 164 tracks, 130 albums, 160 artists, one
-account and one library came back untouched under a new key.
+**Not by hand.** Deleting `subsonic_credential`, `scrobble_link` and
+`instance_metadata` in SQL — which is what this page documented before the
+commands existed, and what was verified end to end on a real instance of 164
+tracks, 130 albums and 160 artists — does bring the catalogue back under a new
+key. What it also does is strand every share: the stored token hash was
+computed from the old key, no later key can produce it again, and the owner is
+shown a URL that answers 404. That is the difference the commands carry.
 
 ## One path whose query string must not reach your proxy's log
 
diff --git a/docs/rfcs/RFC-002-waveflow-server-v2.md b/docs/rfcs/RFC-002-waveflow-server-v2.md
index 4a49958a..7b4f94a6 100644
--- a/docs/rfcs/RFC-002-waveflow-server-v2.md
+++ b/docs/rfcs/RFC-002-waveflow-server-v2.md
@@ -28,7 +28,7 @@ Libraries are private or shared through explicit owner, manager and listener mem
 
 WaveFlow accounts are local. Web passwords use Argon2id. Access, refresh and API tokens are random opaque values stored only as SHA-256 hashes. Refresh tokens rotate on use and sessions belong to revocable devices.
 
-Every user may have a separate Subsonic app password. It is never the web password. Compatibility with token-and-salt authentication requires reversible verification, so the app password is encrypted with ChaCha20-Poly1305 under a random local instance key. The database and key must be backed up together. SQLite stores only a SHA-256 fingerprint of that key; boot, backup verification and restore reject mismatched pairs before exposing or replacing data.
+Every user may have a separate Subsonic app password. It is never the web password. Compatibility with token-and-salt authentication requires reversible verification, so the app password is encrypted with ChaCha20-Poly1305 under a random local instance key. The database and key must be backed up together. SQLite stores only a SHA-256 fingerprint of that key; boot, backup verification and restore reject mismatched pairs before exposing or replacing data. A restored bundle is the cheap way out of a mismatch and not the only one: `key rotate` carries every sealed value onto a new key, `key adopt` discards what a key that is gone sealed and binds a fresh one, and both re-derive the share tokens the key names rather than leaving them stranded.
 
 ### Playback
 
diff --git a/src/cli.rs b/src/cli.rs
index 75b04a35..1f6e76a8 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1,14 +1,18 @@
 //! Administrative CLI used before the M4 web administration surface exists.
 
-use std::{path::PathBuf, str::FromStr};
+use std::{
+    path::{Path, PathBuf},
+    str::FromStr,
+};
 
 use anyhow::Context;
 use clap::{Args, Parser, Subcommand};
+use sqlx::Connection;
 
 use crate::{
     authentication::now_ms,
     catalog::LibraryRecord,
-    database::{AccountRole, Database, LibraryRole, LibraryVisibility},
+    database::{AccountRole, Database, KeyMaterial, LibraryRole, LibraryVisibility, Rekey},
     security, AppState,
 };
 
@@ -57,6 +61,14 @@ pub enum Command {
         #[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)]
@@ -306,6 +318,29 @@ pub struct RestoreArgs {
     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 {
@@ -349,7 +384,222 @@ pub async fn execute(command: Command, state: &AppState) -> anyhow::Result<()> {
                 anyhow::bail!("restore must run before server initialization")
             }
         },
+        Command::Key { .. } => {
+            anyhow::bail!("a key change must run before server initialization")
+        }
+    }
+}
+
+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()),
+    }
+}
+
+/// The database, held alone and brought up to date.
+///
+/// The migration is not a side errand. This command writes rows, and writing
+/// rows into a schema older than the binary is how a repair becomes damage —
+/// `scrobble_link` does not exist before 2.0.0-beta.1, and an operator who
+/// lost a key is often the same one who just replaced a container image. It is
+/// also exactly what the next boot would do.
+///
+/// `migrate_on` leaves foreign keys off on the connection it is handed, and
+/// nothing here puts them back: `Database::rekey` asks for them itself,
+/// because it is the one caller whose correctness depends on them. A second
+/// `PRAGMA` here would be one no inversion could tell from its absence.
+async fn open_for_key_change(config: &crate::Config) -> anyhow::Result<sqlx::SqliteConnection> {
+    let mut connection =
+        Database::open_alone(&config.database_path, config.sqlite_busy_timeout).await?;
+    Database::migrate_on(&mut connection).await?;
+    Ok(connection)
+}
+
+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 = 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"
+            );
+        }
+    }
+    let material = Database::key_material(&mut connection).await?;
+    println!(
+        "Rotating the instance key of {}.",
+        config.database_path.display()
+    );
+    println!();
+    println!(
+        "  {} Subsonic password(s) — moved to the new key, unchanged for their owners",
+        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
+    );
+    println!();
+    if !args.confirm {
+        println!("Nothing has been changed. Re-run with --confirm.");
+        return Ok(());
+    }
+    let (moved, recovery) = replace_key(config, connection, Rekey::Reencrypt(&old_key)).await?;
+    println!(
+        "Done. {} Subsonic password(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 = 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"
+            );
+        }
+    }
+    let material = Database::key_material(&mut connection).await?;
+    println!(
+        "Adopting {} under a new instance key.",
+        config.database_path.display()
+    );
+    println!();
+    println!("The old key is gone, so nothing sealed under it can be carried over:");
+    println!();
+    println!(
+        "  {} Subsonic password(s) — deleted; re-set each with `credential set`",
+        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!();
+    if !args.confirm {
+        println!("Nothing has been changed. Re-run with --confirm.");
+        return Ok(());
     }
+    let (moved, recovery) = replace_key(config, connection, Rekey::Discard).await?;
+    println!(
+        "Done. {} Subsonic password(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 two commands do identically once the decision is made.
+///
+/// Answers with what was actually moved, not with what was predicted a moment
+/// earlier: the counts above come from reading the tables, these come from the
+/// statements that touched them, and a line printed from the second is the
+/// only one that reports the operation rather than the plan.
+async fn replace_key(
+    config: &crate::Config,
+    mut connection: sqlx::SqliteConnection,
+    plan: Rekey<'_>,
+) -> anyhow::Result<(KeyMaterial, PathBuf)> {
+    // Before anything is touched, and a coherent pair rather than a file copy:
+    // `database restore` leaves the same kind of directory behind, for the
+    // same reason. The schema in it is the one this command had to reach in
+    // order to read the database at all; everything else is as it was found.
+    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}"))?;
+    if config.instance_key_path.exists() {
+        tokio::fs::copy(&config.instance_key_path, recovery.join("instance.key")).await?;
+    }
+
+    // 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)?;
+    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.
+    connection.close().await?;
+    tokio::fs::rename(&staged, &config.instance_key_path).await?;
+    Ok((moved, recovery))
+}
+
+fn report_done(recovery: &Path) {
+    println!(
+        "Done. The previous pair is recoverable from {}",
+        recovery.display()
+    );
+    println!("Start the server; it opens on the new key.");
 }
 
 async fn backup(state: &AppState, args: BackupArgs) -> anyhow::Result<()> {
diff --git a/src/database.rs b/src/database.rs
index cec619df..f3c44c70 100644
--- a/src/database.rs
+++ b/src/database.rs
@@ -17,6 +17,32 @@ use crate::{config::Config, security::EncryptedSecret};
 
 pub static MIGRATOR: Migrator = sqlx::migrate!("./migrations-v2");
 
+/// What an instance key protects, counted from the database.
+///
+/// Four numbers rather than a sentence, because the sentence is what the
+/// documentation already carries and it is not what an operator needs at the
+/// moment of deciding. The third is the one nobody expects: discarding the
+/// scrobbling links discards the listens queued behind them.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct KeyMaterial {
+    pub subsonic_credentials: i64,
+    pub scrobble_links: i64,
+    pub queued_listens: i64,
+    pub shares: i64,
+}
+
+/// What to do with the values the previous key protected.
+///
+/// Two variants, and two commands above them rather than one command and a
+/// flag: one of these preserves exactly what the other destroys, and that is
+/// not a detail of a single operation.
+pub enum Rekey<'a> {
+    /// The old key is in hand. Every ciphertext is read and written back.
+    Reencrypt(&'a crate::security::SecretBox),
+    /// The old key is gone. Nothing can be read, so the rows go.
+    Discard,
+}
+
 #[derive(Clone)]
 pub struct Database {
     pool: SqlitePool,
@@ -348,8 +374,29 @@ impl Database {
 
     pub async fn migrate(&self) -> anyhow::Result<()> {
         let _writer = self.writer_guard().await;
-        let normalized = self
-            .normalize_legacy_crlf_migration_checksums()
+        // The connection is detached rather than returned to the pool: the
+        // migration turns foreign-key enforcement off on whatever connection
+        // it runs on, and a connection left unenforced is one every later
+        // query would inherit.
+        let mut connection = self.pool.acquire().await?.detach();
+        let outcome = Self::migrate_on(&mut connection).await;
+        connection.close().await.ok();
+        outcome
+    }
+
+    /// Every pending migration, on a connection nobody else is using.
+    ///
+    /// Two callers, and the exclusivity is what they have in common rather
+    /// than how they get it: [`Self::migrate`] detaches a connection behind
+    /// the writer gate, while the offline key commands hold the database file
+    /// itself (see [`Self::open_alone`]). An upgrade that two writers shared
+    /// would be a different thing entirely, which is why neither path runs
+    /// this on a pool.
+    ///
+    /// The caller owns the connection afterwards, foreign keys and all — see
+    /// below.
+    pub(crate) async fn migrate_on(connection: &mut SqliteConnection) -> anyhow::Result<()> {
+        let normalized = Self::normalize_legacy_crlf_migration_checksums(connection)
             .await
             .map_err(|error| {
                 anyhow::anyhow!("legacy migration checksum normalization failed: {error}")
@@ -376,14 +423,10 @@ impl Database {
         //
         // A migration file cannot turn enforcement off for itself: `PRAGMA
         // foreign_keys` is a no-op inside a transaction and every migration
-        // runs in one. So the runner does it, and answers for it below.
-        //
-        // The connection is detached rather than returned to the pool: a
-        // connection left unenforced is one every later query would inherit.
-        let mut connection = self.pool.acquire().await?.detach();
-        let outcome = Self::run_migrations_unenforced(&mut connection).await;
-        connection.close().await.ok();
-        outcome
+        // runs in one. So the runner does it, and answers for it below — and
+        // leaves it off, so a caller that keeps the connection has to put it
+        // back before writing anything a foreign key should govern.
+        Self::run_migrations_unenforced(connection).await
     }
 
     /// Runs every pending migration on a connection with foreign keys off,
@@ -425,8 +468,10 @@ impl Database {
     /// Only the checksum of the current migration with every LF converted to
     /// CRLF is accepted. Any other mismatch is left untouched for SQLx to
     /// reject normally.
-    async fn normalize_legacy_crlf_migration_checksums(&self) -> Result<u64, sqlx::Error> {
-        let mut tx = self.pool.begin().await?;
+    async fn normalize_legacy_crlf_migration_checksums(
+        connection: &mut SqliteConnection,
+    ) -> Result<u64, sqlx::Error> {
+        let mut tx = connection.begin().await?;
         let migrations_table_exists: i64 = sqlx::query_scalar(
             "SELECT EXISTS(SELECT 1 FROM sqlite_master \
              WHERE type = 'table' AND name = '_sqlx_migrations')",
@@ -550,6 +595,275 @@ impl Database {
         Ok(stored.is_some_and(|stored| stored == fingerprint))
     }
 
+    /// Opens the database for an offline operation, refusing to share it.
+    ///
+    /// `locking_mode=EXCLUSIVE` followed at once by `BEGIN EXCLUSIVE` is the
+    /// only question SQLite answers honestly here: a running server keeps
+    /// connections open against this file, and the lock cannot be taken while
+    /// one of them exists. It then stays taken until this connection closes,
+    /// so the refusal is not a check with a gap after it — it is the same lock
+    /// the work is then done under.
+    ///
+    /// That is strictly more than [`Self::writer_guard`] offers. The writer
+    /// gate keeps two tasks of *one* process apart; an offline command has one
+    /// task and a different hazard, which is the other process.
+    ///
+    /// The file must already exist. `create_if_missing` would turn "the
+    /// database is not where you said" into an empty database bound to a fresh
+    /// key, which is the one outcome worse than the error.
+    pub async fn open_alone(
+        path: &Path,
+        busy_timeout: std::time::Duration,
+    ) -> anyhow::Result<SqliteConnection> {
+        if !path.exists() {
+            anyhow::bail!("no SQLite database at {}", path.display());
+        }
+        let mut connection = SqliteConnection::connect_with(
+            &SqliteConnectOptions::new()
+                .filename(path)
+                .create_if_missing(false)
+                .foreign_keys(true)
+                .journal_mode(SqliteJournalMode::Wal)
+                .busy_timeout(busy_timeout),
+        )
+        .await
+        .map_err(|error| anyhow::anyhow!("sqlite connect failed: {error}"))?;
+        sqlx::query("PRAGMA locking_mode = EXCLUSIVE")
+            .execute(&mut connection)
+            .await
+            .map_err(|error| anyhow::anyhow!("could not ask for an exclusive lock: {error}"))?;
+        sqlx::query("BEGIN EXCLUSIVE")
+            .execute(&mut connection)
+            .await
+            .map_err(|_| {
+                anyhow::anyhow!(
+                    "{} is open in another process; stop the server before running this",
+                    path.display()
+                )
+            })?;
+        sqlx::query("COMMIT")
+            .execute(&mut connection)
+            .await
+            .map_err(|error| anyhow::anyhow!("could not take the database: {error}"))?;
+        Ok(connection)
+    }
+
+    /// The fingerprint this database was bound to, if it has been bound.
+    ///
+    /// Absent on a database no server has ever opened. Present and different
+    /// is what aborts a boot, and what tells the two key commands apart.
+    pub async fn stored_key_fingerprint(
+        connection: &mut SqliteConnection,
+    ) -> anyhow::Result<Option<Vec<u8>>> {
+        Ok(sqlx::query_scalar::<_, Vec<u8>>(
+            "SELECT key_fingerprint FROM instance_metadata WHERE singleton=1",
+        )
+        .fetch_optional(&mut *connection)
+        .await?)
+    }
+
+    /// What the instance key protects, counted rather than described.
+    ///
+    /// The operator is about to be told what a key change costs, and a count
+    /// read from their own database is the only version of that worth
+    /// printing.
+    pub async fn key_material(connection: &mut SqliteConnection) -> anyhow::Result<KeyMaterial> {
+        let count = |sql: &'static str| sqlx::query_scalar::<_, i64>(sql);
+        Ok(KeyMaterial {
+            subsonic_credentials: count("SELECT COUNT(*) FROM subsonic_credential")
+                .fetch_one(&mut *connection)
+                .await?,
+            scrobble_links: count("SELECT COUNT(*) FROM scrobble_link")
+                .fetch_one(&mut *connection)
+                .await?,
+            // Every row of the outbox hangs off a link by `ON DELETE CASCADE`,
+            // so discarding the links discards these with them. Counted
+            // because an operator told "two scrobbling links" would not guess
+            // that it also means a few hundred listens nobody has sent yet.
+            queued_listens: count("SELECT COUNT(*) FROM scrobble_outbox")
+                .fetch_one(&mut *connection)
+                .await?,
+            shares: count("SELECT COUNT(*) FROM share")
+                .fetch_one(&mut *connection)
+                .await?,
+        })
+    }
+
+    /// Moves every value the instance key governs onto a new key.
+    ///
+    /// One transaction, so a database half under one key and half under
+    /// another is not a state this can leave behind. The caller writes the new
+    /// key file only after this returns, for the same reason: a key that
+    /// arrived before the commit would name a database that never changed.
+    ///
+    /// Shares are rewritten whichever plan runs, and they are the reason this
+    /// is one function rather than two. A share token is *derived* from the
+    /// key rather than stored ([`crate::security::SecretBox::derive_share_token`]),
+    /// so after a key change the stored hash is one the new key can never
+    /// produce: the share is not merely re-addressed, it is unreachable, and
+    /// its owner is shown a URL that answers 404. Recomputing the hash is what
+    /// makes "shares survive, with a new URL" true rather than hoped for.
+    pub async fn rekey(
+        connection: &mut SqliteConnection,
+        plan: Rekey<'_>,
+        new_key: &crate::security::SecretBox,
+        new_fingerprint: &[u8],
+        now_ms: i64,
+    ) -> anyhow::Result<KeyMaterial> {
+        // Asked for here rather than taken on trust from the caller. It is a
+        // connection flag, `migrate_on` turns it off, and the delete below is
+        // the one statement whose correctness depends on it — a cascade that
+        // did not fire leaves no error, only rows. A no-op inside a
+        // transaction, so it has to come before the `begin`.
+        sqlx::query("PRAGMA foreign_keys = ON")
+            .execute(&mut *connection)
+            .await
+            .map_err(|error| anyhow::anyhow!("could not enforce foreign keys: {error}"))?;
+        let enforced = sqlx::query_scalar::<_, i64>("PRAGMA foreign_keys")
+            .fetch_one(&mut *connection)
+            .await?;
+        if enforced != 1 {
+            anyhow::bail!("foreign keys are not enforced; nothing has been changed");
+        }
+        let mut tx = connection.begin().await?;
+        let mut moved = KeyMaterial::default();
+        match plan {
+            Rekey::Reencrypt(old_key) => {
+                let credentials = sqlx::query(
+                    "SELECT user_id, password_nonce, password_ciphertext FROM subsonic_credential",
+                )
+                .fetch_all(&mut *tx)
+                .await?;
+                for row in credentials {
+                    let user_id: String = row.try_get("user_id")?;
+                    let plaintext = old_key
+                        .decrypt(
+                            row.try_get::<Vec<u8>, _>("password_nonce")?.as_slice(),
+                            row.try_get::<Vec<u8>, _>("password_ciphertext")?.as_slice(),
+                        )
+                        .map_err(|_| {
+                            anyhow::anyhow!(
+                                "a stored Subsonic password does not open with this key; \
+                                 nothing has been changed"
+                            )
+                        })?;
+                    let sealed = new_key.encrypt(&plaintext)?;
+                    sqlx::query(
+                        "UPDATE subsonic_credential \
+                         SET password_nonce=?, password_ciphertext=?, updated_at=? \
+                         WHERE user_id=?",
+                    )
+                    .bind(sealed.nonce.as_slice())
+                    .bind(&sealed.ciphertext)
+                    .bind(now_ms)
+                    .bind(&user_id)
+                    .execute(&mut *tx)
+                    .await?;
+                    moved.subsonic_credentials += 1;
+                }
+
+                // The `unlinked` generations included: they keep their
+                // ciphertext, and a past authorisation left unreadable would
+                // be a row this server can no longer account for.
+                let links = sqlx::query(
+                    "SELECT id, credential_nonce, credential_ciphertext FROM scrobble_link",
+                )
+                .fetch_all(&mut *tx)
+                .await?;
+                for row in links {
+                    let id: String = row.try_get("id")?;
+                    let plaintext = old_key
+                        .decrypt(
+                            row.try_get::<Vec<u8>, _>("credential_nonce")?.as_slice(),
+                            row.try_get::<Vec<u8>, _>("credential_ciphertext")?
+                                .as_slice(),
+                        )
+                        .map_err(|_| {
+                            anyhow::anyhow!(
+                                "a stored scrobbling secret does not open with this key; \
+                                 nothing has been changed"
+                            )
+                        })?;
+                    let sealed = new_key.encrypt(&plaintext)?;
+                    sqlx::query(
+                        "UPDATE scrobble_link \
+                         SET credential_nonce=?, credential_ciphertext=?, updated_at=? \
+                         WHERE id=?",
+                    )
+                    .bind(sealed.nonce.as_slice())
+                    .bind(&sealed.ciphertext)
+                    .bind(now_ms)
+                    .bind(&id)
+                    .execute(&mut *tx)
+                    .await?;
+                    moved.scrobble_links += 1;
+                }
+            }
+            Rekey::Discard => {
+                // The outbox goes with the links, by `ON DELETE CASCADE`
+                // rather than by a statement here — which only holds with
+                // enforcement on, and `migrate_on` leaves it off. Counted
+                // before the delete and asserted against afterwards, because
+                // a cascade that silently did not fire would leave the number
+                // printed to the operator as the only trace of it.
+                moved.queued_listens = sqlx::query_scalar::<_, i64>(
+                    "SELECT COUNT(*) FROM scrobble_outbox \
+                     WHERE link_id IN (SELECT id FROM scrobble_link)",
+                )
+                .fetch_one(&mut *tx)
+                .await?;
+                moved.subsonic_credentials = sqlx::query("DELETE FROM subsonic_credential")
+                    .execute(&mut *tx)
+                    .await?
+                    .rows_affected() as i64;
+                moved.scrobble_links = sqlx::query("DELETE FROM scrobble_link")
+                    .execute(&mut *tx)
+                    .await?
+                    .rows_affected() as i64;
+                let orphans = sqlx::query_scalar::<_, i64>("SELECT COUNT(*) FROM scrobble_outbox")
+                    .fetch_one(&mut *tx)
+                    .await?;
+                if orphans > 0 {
+                    anyhow::bail!(
+                        "{orphans} queued listen(s) outlived the links they belong to; \
+                         foreign keys were not enforced and nothing has been changed"
+                    );
+                }
+            }
+        }
+
+        for id in sqlx::query_scalar::<_, String>("SELECT id FROM share")
+            .fetch_all(&mut *tx)
+            .await?
+        {
+            let share = Uuid::parse_str(&id)
+                .map_err(|_| anyhow::anyhow!("a share carries an identifier that is not a UUID"))?;
+            let token = new_key.derive_share_token(share);
+            // `updated_at` is left alone on purpose. The share did not change;
+            // the key that names it did, and bumping the column would hand
+            // every synchronising client a modification with no journal entry
+            // behind it.
+            sqlx::query("UPDATE share SET token_hash=? WHERE id=?")
+                .bind(crate::security::token_hash(&token).as_slice())
+                .bind(&id)
+                .execute(&mut *tx)
+                .await?;
+            moved.shares += 1;
+        }
+
+        sqlx::query(
+            "INSERT INTO instance_metadata (singleton, key_fingerprint, created_at) \
+             VALUES (1, ?, ?) \
+             ON CONFLICT (singleton) DO UPDATE SET key_fingerprint = excluded.key_fingerprint",
+        )
+        .bind(new_fingerprint)
+        .bind(now_ms)
+        .execute(&mut *tx)
+        .await?;
+        tx.commit().await?;
+        Ok(moved)
+    }
+
     pub fn pool(&self) -> &SqlitePool {
         &self.pool
     }
diff --git a/src/main.rs b/src/main.rs
index e093b27c..82ab6e9a 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -14,6 +14,9 @@ async fn main() -> anyhow::Result<()> {
         Some(cli::Command::Database {
             command: cli::DatabaseCommand::Restore(args),
         }) => cli::restore(&config, args).await,
+        // Both of these run on a database the boot would refuse, so they run
+        // instead of the boot rather than after it.
+        Some(cli::Command::Key { command }) => cli::key(&config, command).await,
         command => {
             let state = waveflow_server::initialize(&config).await?;
             match command {
diff --git a/src/security.rs b/src/security.rs
index fb2dd75c..2a7f6960 100644
--- a/src/security.rs
+++ b/src/security.rs
@@ -26,6 +26,8 @@ pub enum SecurityError {
     PasswordVerify,
     #[error("instance key must contain exactly 32 bytes")]
     InvalidInstanceKey,
+    #[error("an instance key already occupies that path")]
+    InstanceKeyExists,
     #[error("system randomness is unavailable")]
     Random,
     #[error("secret encryption failed")]
@@ -65,6 +67,23 @@ impl SecretBox {
         Self::from_key_bytes(&key)
     }
 
+    /// A fresh instance key, written where nothing stands yet.
+    ///
+    /// [`Self::load_or_create`] mints one as a side effect of finding none,
+    /// which is right for a boot and wrong for a key replacement: there the new
+    /// key is staged beside the old one and renamed over it only once the
+    /// database has committed. That caller needs the minting asked for
+    /// deliberately, and needs to be told when the file it staged was not
+    /// actually written by this call.
+    pub fn create_instance_key(path: &Path) -> Result<[u8; INSTANCE_KEY_BYTES], SecurityError> {
+        let mut bytes = [0u8; INSTANCE_KEY_BYTES];
+        fill_random(&mut bytes)?;
+        if !write_new_secret_file(path, &bytes)? {
+            return Err(SecurityError::InstanceKeyExists);
+        }
+        Ok(bytes)
+    }
+
     pub fn from_key_bytes(key: &[u8]) -> Result<Self, SecurityError> {
         let key: [u8; INSTANCE_KEY_BYTES] = key
             .try_into()
@@ -166,7 +185,14 @@ pub fn token_matches(token: &str, expected_hash: &[u8]) -> bool {
     actual.as_slice().ct_eq(expected_hash).into()
 }
 
-fn write_new_secret_file(path: &Path, bytes: &[u8]) -> Result<(), SecurityError> {
+/// Writes a secret file nobody else owns, answering whether this call created
+/// it.
+///
+/// `false` means the path was already taken. [`SecretBox::load_or_create`]
+/// treats that as a race it lost and re-reads the winner's key;
+/// [`SecretBox::create_instance_key`] treats it as a refusal, because it is
+/// staging a file that must not exist.
+fn write_new_secret_file(path: &Path, bytes: &[u8]) -> Result<bool, SecurityError> {
     if let Some(parent) = path.parent() {
         std::fs::create_dir_all(parent)?;
     }
@@ -183,9 +209,9 @@ fn write_new_secret_file(path: &Path, bytes: &[u8]) -> Result<(), SecurityError>
         Ok(mut file) => {
             file.write_all(bytes)?;
             file.sync_all()?;
-            Ok(())
+            Ok(true)
         }
-        Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => Ok(()),
+        Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => Ok(false),
         Err(error) => Err(error.into()),
     }
 }
diff --git a/tests/cli.rs b/tests/cli.rs
index 5aa2beaf..beeae786 100644
--- a/tests/cli.rs
+++ b/tests/cli.rs
@@ -597,3 +597,570 @@ async fn the_cli_authorises_last_fm_without_a_browser() {
     assert_eq!(links[0].provider.as_str(), "lastfm");
     assert_eq!(links[0].destination, "default");
 }
+
+// ---------------------------------------------------------------------------
+// Replacing the instance key
+//
+// These four run against `cli::key` rather than `cli::execute`, because that is
+// where the commands live: they answer the boot that aborts on a mismatched
+// pair, so they cannot be reached through an `AppState` the boot would never
+// have built. The suite's other CLI tests all start from one.
+//
+// Every fixture below closes the pool and drops the state before the command
+// runs. That is not tidiness: `open_alone` refuses a database another
+// connection is holding, and leaving one open is how three of these would pass
+// by refusing for the wrong reason.
+// ---------------------------------------------------------------------------
+
+/// One installation holding every value an instance key governs.
+struct Sealed {
+    owner: uuid::Uuid,
+    track: uuid::Uuid,
+    /// Drawn here rather than written in, so an assertion that it came back
+    /// cannot be met by a constant the code could have carried.
+    subsonic_password: String,
+    scrobble_secret: String,
+    share: uuid::Uuid,
+    /// The public URL as it stood under the first key.
+    share_token: String,
+}
+
+/// How many of each the fixture seeds.
+///
+/// Four different numbers, on purpose. An earlier version seeded one of
+/// everything, and an assertion on the line the command prints then held just
+/// as well with two of its four fields swapped — the inversion that found it
+/// passed. A count can only be checked against a count nothing else shares.
+const SEALED_CREDENTIALS: usize = 2;
+const SEALED_LISTENS: usize = 3;
+const SEALED_SHARES: usize = 4;
+
+async fn sealed_installation(
+    config: &waveflow_server::Config,
+    state: &waveflow_server::AppState,
+    name: &str,
+) -> Sealed {
+    let owner = inserted_account(state, name, "admin").await;
+
+    let music = config.data_dir.join(name);
+    std::fs::create_dir_all(&music).unwrap();
+    generate_audio_fixture(&music.join("sealed.flac"), "flac", "flac");
+    let root = std::fs::canonicalize(&music).unwrap();
+    let library = state
+        .db
+        .create_library(
+            owner,
+            name,
+            &root,
+            waveflow_server::database::LibraryVisibility::Private,
+            now_ms(),
+        )
+        .await
+        .unwrap();
+    run_scan(
+        state,
+        owner,
+        waveflow_server::catalog::LibraryRecord {
+            id: library,
+            name: name.into(),
+            root_path: root,
+        },
+    )
+    .await;
+    let track: uuid::Uuid =
+        sqlx::query_scalar::<_, String>("SELECT id FROM track WHERE library_id=?")
+            .bind(library.to_string())
+            .fetch_one(state.db.pool())
+            .await
+            .expect("the fixture file must have been scanned")
+            .parse()
+            .unwrap();
+
+    let subsonic_password = format!("subsonic-{}", uuid::Uuid::new_v4());
+    state
+        .services
+        .set_subsonic_credential(owner, name, &subsonic_password)
+        .await
+        .unwrap();
+    for extra in 1..SEALED_CREDENTIALS {
+        let other = format!("{name}-{extra}");
+        inserted_account(state, &other, "user").await;
+        state
+            .services
+            .set_subsonic_credential(owner, &other, &format!("subsonic-{}", uuid::Uuid::new_v4()))
+            .await
+            .unwrap();
+    }
+
+    let scrobble_secret = format!("listenbrainz-{}", uuid::Uuid::new_v4());
+    state
+        .services
+        .link_scrobble(
+            owner,
+            waveflow_server::services::ScrobbleProvider::ListenBrainz,
+            "default",
+            &scrobble_secret,
+        )
+        .await
+        .unwrap();
+    // Listens behind the link, which `ON DELETE CASCADE` takes with it. Dated
+    // apart so none of them is the same listen twice.
+    for listen in 0..SEALED_LISTENS {
+        state
+            .services
+            .scrobble(
+                owner,
+                track,
+                true,
+                Some(now_ms() - (listen as i64 + 1) * 600_000),
+            )
+            .await
+            .unwrap();
+    }
+
+    let mut share = state
+        .services
+        .create_share(owner, &[track], Some("carried over"), None)
+        .await
+        .unwrap();
+    for extra in 1..SEALED_SHARES {
+        state
+            .services
+            .create_share(owner, &[track], Some(&format!("also {extra}")), None)
+            .await
+            .unwrap();
+    }
+    let share_token = share.url_token.take().expect("a new share names its URL");
+    assert!(
+        state.services.public_share(&share_token).await.is_ok(),
+        "the fixture share must resolve before the key changes"
+    );
+    for (table, query, expected) in [
+        (
+            "subsonic_credential",
+            "SELECT COUNT(*) FROM subsonic_credential",
+            SEALED_CREDENTIALS,
+        ),
+        ("scrobble_link", "SELECT COUNT(*) FROM scrobble_link", 1),
+        (
+            "scrobble_outbox",
+            "SELECT COUNT(*) FROM scrobble_outbox",
+            SEALED_LISTENS,
+        ),
+        ("share", "SELECT COUNT(*) FROM share", SEALED_SHARES),
+    ] {
+        assert_eq!(
+            count(state, query).await as usize,
+            expected,
+            "the fixture must seed {expected} row(s) in {table}"
+        );
+    }
+
+    Sealed {
+        owner,
+        track,
+        subsonic_password,
+        scrobble_secret,
+        share: share.id,
+        share_token,
+    }
+}
+
+/// Closes every connection, so the command can take the database.
+async fn stop_server(state: waveflow_server::AppState) {
+    state.db.pool().close().await;
+    drop(state);
+}
+
+async fn count(state: &waveflow_server::AppState, query: &'static str) -> i64 {
+    sqlx::query_scalar::<_, i64>(query)
+        .fetch_one(state.db.pool())
+        .await
+        .unwrap()
+}
+
+/// The sealed scrobbling secret, read the way the drain reads it.
+///
+/// There is no public accessor for it — `due_scrobbles` is private and joins
+/// the outbox — so the row is read here and opened with the same `SecretBox`
+/// the drain would use. What is being checked is the ciphertext, not the join.
+///
+/// `None` rather than a panic when it will not open, because that is the
+/// failure a rotation that skipped this table produces, and a test must fail
+/// on the assertion that names the defect rather than on the line before it.
+async fn scrobble_secret(state: &waveflow_server::AppState) -> Option<Vec<u8>> {
+    let (nonce, ciphertext) = sqlx::query_as::<_, (Vec<u8>, Vec<u8>)>(
+        "SELECT credential_nonce, credential_ciphertext FROM scrobble_link",
+    )
+    .fetch_one(state.db.pool())
+    .await
+    .expect("the link must still be there");
+    state.secret_box.decrypt(&nonce, &ciphertext).ok()
+}
+
+/// Whether the command refused, and said why.
+///
+/// Read as a value rather than through `unwrap_err`: a command that went
+/// ahead when it should have refused must fail on the assertion that names the
+/// refusal, not on the unwrapping above it.
+fn refused_with(outcome: &anyhow::Result<()>, reason: &str) -> bool {
+    outcome
+        .as_ref()
+        .err()
+        .is_some_and(|error| error.to_string().contains(reason))
+}
+
+/// The single `pre-key-*` directory the command left behind.
+fn recovery_directory(config: &waveflow_server::Config) -> std::path::PathBuf {
+    let mut found: Vec<_> = std::fs::read_dir(&config.data_dir)
+        .unwrap()
+        .map(|entry| entry.unwrap().path())
+        .filter(|path| {
+            path.file_name()
+                .and_then(|name| name.to_str())
+                .is_some_and(|name| name.starts_with("pre-key-"))
+        })
+        .collect();
+    assert_eq!(found.len(), 1, "exactly one recovery directory: {found:?}");
+    found.pop().unwrap()
+}
+
+/// Rotation carries every secret onto the new key, and re-points the shares.
+///
+/// The share half is the one worth stating plainly. A share token is derived
+/// from the instance key rather than stored, so a key change that left
+/// `token_hash` alone would not re-address the share — it would strand it,
+/// behind a URL its owner is still shown and nobody can open. "Shares survive
+/// with a new URL" is only true because `rekey` recomputes the hash, and the
+/// two assertions below are what separate that from the wish.
+#[tokio::test]
+async fn rotating_the_key_keeps_every_secret_and_re_points_the_shares() {
+    let (_temp, config, state) = test_app().await;
+    let sealed = sealed_installation(&config, &state, "rotate-owner").await;
+    let key_before = std::fs::read(&config.instance_key_path).unwrap();
+    let queued_before = count(&state, "SELECT COUNT(*) FROM scrobble_outbox").await;
+    stop_server(state).await;
+
+    waveflow_server::cli::key(
+        &config,
+        waveflow_server::cli::KeyCommand::Rotate(waveflow_server::cli::KeyArgs { confirm: true }),
+    )
+    .await
+    .unwrap();
+
+    let key_after = std::fs::read(&config.instance_key_path).unwrap();
+    assert_ne!(key_after, key_before, "the key file was not replaced");
+    let recovery = recovery_directory(&config);
+    assert_eq!(
+        std::fs::read(recovery.join("instance.key")).ok().as_deref(),
+        Some(key_before.as_slice()),
+        "the recovery bundle must hold the key as it was"
+    );
+    assert!(
+        waveflow_server::database::Database::check_file(&recovery.join("waveflow.db"))
+            .await
+            .unwrap_or(false),
+        "the recovery copy must be a sound database"
+    );
+
+    let state = waveflow_server::initialize(&config).await.unwrap();
+    let credential = state
+        .services
+        .credential_by_username("rotate-owner")
+        .await
+        .unwrap()
+        .expect("the credential must still be there");
+    assert_eq!(
+        state
+            .services
+            .decrypt_subsonic_password(&credential)
+            .ok()
+            .as_deref(),
+        Some(sealed.subsonic_password.as_bytes()),
+        "the Subsonic password did not survive the rotation"
+    );
+    assert_eq!(
+        scrobble_secret(&state).await.as_deref(),
+        Some(sealed.scrobble_secret.as_bytes()),
+        "the scrobbling secret did not survive the rotation"
+    );
+    assert_eq!(
+        count(&state, "SELECT COUNT(*) FROM scrobble_outbox").await,
+        queued_before,
+        "rotation must not touch the queue"
+    );
+
+    let moved = state.secret_box.derive_share_token(sealed.share);
+    assert_ne!(moved, sealed.share_token, "the URL did not change");
+    assert!(
+        matches!(
+            state.services.public_share(&sealed.share_token).await,
+            Err(waveflow_server::services::ServiceError::NotFound)
+        ),
+        "a link handed out under the old key still opens"
+    );
+    let reached = state
+        .services
+        .public_share(&moved)
+        .await
+        .expect("the share must answer on its new URL");
+    assert_eq!(reached.id, sealed.share);
+    assert_eq!(
+        reached.songs.len(),
+        1,
+        "the share must still carry its track"
+    );
+}
+
+/// Adoption discards what cannot be read, and only that.
+///
+/// The queue is the part an operator would not predict: the outbox hangs off
+/// `scrobble_link` by `ON DELETE CASCADE`, which only fires with foreign keys
+/// enforced — and the migration this command runs first leaves them off.
+///
+/// Three things would have to go for a stranded queue to reach anybody: the
+/// `PRAGMA` `rekey` asks for itself, the orphan count it rolls back on, and
+/// the `foreign_key_check` the next boot runs. Removing the first fails this
+/// test on the command; removing the first two fails it on the boot below. So
+/// the count further down never gets to be the line that fails, and is kept
+/// as the statement of what an adoption leaves behind rather than as the
+/// guard — which is where the guard actually is.
+#[tokio::test]
+async fn adopting_a_database_discards_what_the_lost_key_sealed_and_nothing_else() {
+    let (_temp, config, state) = test_app().await;
+    let sealed = sealed_installation(&config, &state, "adopt-owner").await;
+    stop_server(state).await;
+    // The situation this command exists for, in its harder form: not a file
+    // that is gone but one that is no longer a key. `adopt` has to accept it
+    // — refusing to read it would refuse the operator holding it — and move
+    // it aside with the rest of the pair.
+    std::fs::write(&config.instance_key_path, [1u8; 7]).unwrap();
+
+    waveflow_server::cli::key(
+        &config,
+        waveflow_server::cli::KeyCommand::Adopt(waveflow_server::cli::KeyArgs { confirm: true }),
+    )
+    .await
+    .unwrap();
+
+    let state = waveflow_server::initialize(&config).await.unwrap();
+    assert_eq!(
+        count(&state, "SELECT COUNT(*) FROM subsonic_credential").await,
+        0,
+        "an unreadable Subsonic password was kept"
+    );
+    assert_eq!(
+        count(&state, "SELECT COUNT(*) FROM scrobble_link").await,
+        0,
+        "an unreadable scrobbling secret was kept"
+    );
+    assert_eq!(
+        count(&state, "SELECT COUNT(*) FROM scrobble_outbox").await,
+        0,
+        "the queue outlived the links it belongs to"
+    );
+
+    // Everything the key never touched.
+    assert_eq!(
+        count(&state, "SELECT COUNT(*) FROM account").await,
+        SEALED_CREDENTIALS as i64,
+        "an account was lost with the secret it held"
+    );
+    assert_eq!(count(&state, "SELECT COUNT(*) FROM track").await, 1);
+    assert_eq!(
+        count(&state, "SELECT COUNT(*) FROM share").await,
+        SEALED_SHARES as i64,
+        "a share was lost rather than re-addressed"
+    );
+    let songs = state
+        .services
+        .songs_by_ids(sealed.owner, &[sealed.track])
+        .await
+        .unwrap();
+    assert_eq!(songs.len(), 1, "the catalogue must come back untouched");
+
+    let moved = state.secret_box.derive_share_token(sealed.share);
+    assert_ne!(moved, sealed.share_token);
+    let reached = state
+        .services
+        .public_share(&moved)
+        .await
+        .expect("a share survives an adoption, with a new URL");
+    assert_eq!(reached.id, sealed.share);
+
+    let recovery = recovery_directory(&config);
+    assert_eq!(
+        std::fs::read(recovery.join("instance.key")).ok().as_deref(),
+        Some([1u8; 7].as_slice()),
+        "the unusable key was dropped instead of being moved aside"
+    );
+}
+
+/// The three situations in which a key change must not happen at all.
+#[tokio::test]
+async fn a_key_change_refuses_a_live_server_a_matching_key_and_a_foreign_one() {
+    let (_temp, config, state) = test_app().await;
+    sealed_installation(&config, &state, "refusal-owner").await;
+    let key_before = std::fs::read(&config.instance_key_path).unwrap();
+
+    // One: the server is still holding the database.
+    let refused = waveflow_server::cli::key(
+        &config,
+        waveflow_server::cli::KeyCommand::Rotate(waveflow_server::cli::KeyArgs { confirm: true }),
+    )
+    .await;
+    assert!(
+        refused_with(&refused, "open in another process"),
+        "a live server was not detected: {refused:?}"
+    );
+    stop_server(state).await;
+
+    // Two: the key is sitting beside the database, so nothing is lost and
+    // nothing may be destroyed.
+    let refused = waveflow_server::cli::key(
+        &config,
+        waveflow_server::cli::KeyCommand::Adopt(waveflow_server::cli::KeyArgs { confirm: true }),
+    )
+    .await;
+    assert!(
+        refused_with(&refused, "key rotate"),
+        "adoption did not send the operator to rotation: {refused:?}"
+    );
+
+    // Three: the key present is some other installation's.
+    std::fs::write(&config.instance_key_path, [3u8; 32]).unwrap();
+    let refused = waveflow_server::cli::key(
+        &config,
+        waveflow_server::cli::KeyCommand::Rotate(waveflow_server::cli::KeyArgs { confirm: true }),
+    )
+    .await;
+    assert!(
+        refused_with(&refused, "not the one it was bound to"),
+        "a foreign key was accepted for rotation: {refused:?}"
+    );
+
+    std::fs::write(&config.instance_key_path, &key_before).unwrap();
+    let state = waveflow_server::initialize(&config).await.unwrap();
+    assert_eq!(
+        count(&state, "SELECT COUNT(*) FROM subsonic_credential").await,
+        SEALED_CREDENTIALS as i64,
+        "a refused key change still changed something"
+    );
+}
+
+/// Without `--confirm` the command is a reading, and leaves no trace.
+#[tokio::test]
+async fn a_key_change_without_confirmation_changes_nothing() {
+    let (_temp, config, state) = test_app().await;
+    let sealed = sealed_installation(&config, &state, "dry-run-owner").await;
+    let key_before = std::fs::read(&config.instance_key_path).unwrap();
+    stop_server(state).await;
+
+    waveflow_server::cli::key(
+        &config,
+        waveflow_server::cli::KeyCommand::Rotate(waveflow_server::cli::KeyArgs { confirm: false }),
+    )
+    .await
+    .unwrap();
+
+    assert_eq!(
+        std::fs::read(&config.instance_key_path).unwrap(),
+        key_before,
+        "a reading replaced the key"
+    );
+    assert!(
+        !std::fs::read_dir(&config.data_dir).unwrap().any(|entry| {
+            entry
+                .unwrap()
+                .file_name()
+                .to_string_lossy()
+                .starts_with("pre-key-")
+        }),
+        "a reading left a recovery directory behind"
+    );
+
+    let state = waveflow_server::initialize(&config).await.unwrap();
+    assert!(
+        state
+            .services
+            .public_share(&sealed.share_token)
+            .await
+            .is_ok(),
+        "a reading moved the shares"
+    );
+    let credential = state
+        .services
+        .credential_by_username("dry-run-owner")
+        .await
+        .unwrap()
+        .expect("the credential must still be there");
+    assert_eq!(
+        state
+            .services
+            .decrypt_subsonic_password(&credential)
+            .ok()
+            .as_deref(),
+        Some(sealed.subsonic_password.as_bytes())
+    );
+}
+
+/// What the operator actually reads, reached the way they reach it.
+///
+/// Through the binary rather than through `cli::key`, because the subject here
+/// is the surface: the `key` group and its `--confirm` flag as clap parses
+/// them, and the two counts printed — the one read from the tables before the
+/// decision, and the one answered by the statements that carried it out. The
+/// in-process tests above hold what the commands *do*; nothing in them would
+/// notice `--confirm` renamed, or a count printed from the wrong field.
+#[tokio::test]
+async fn a_key_change_prints_what_it_costs_and_then_what_it_did() {
+    let (temp, config, state) = test_app().await;
+    sealed_installation(&config, &state, "printed-owner").await;
+    stop_server(state).await;
+    // Adoption refuses a key that still opens the database, so this is the
+    // situation it is for.
+    std::fs::remove_file(&config.instance_key_path).unwrap();
+
+    let reading = cli_command()
+        .current_dir(temp.path())
+        .env("WAVEFLOW_DATA_DIR", &config.data_dir)
+        .args(["key", "adopt"])
+        .output()
+        .unwrap();
+    let stdout = String::from_utf8(reading.stdout).unwrap();
+    let stderr = String::from_utf8(reading.stderr).unwrap();
+    assert!(reading.status.success(), "the reading failed: {stderr}");
+    for expected in [
+        "2 Subsonic password(s) — deleted",
+        "1 scrobbling link(s) — deleted, and the 3 queued listen(s) behind them",
+        "4 share(s) — kept, but every public URL changes",
+        "Nothing has been changed. Re-run with --confirm.",
+    ] {
+        assert!(
+            stdout.contains(expected),
+            "the reading never said {expected:?}; it said: {stdout}"
+        );
+    }
+    assert!(!config.instance_key_path.exists(), "a reading minted a key");
+
+    let done = cli_command()
+        .current_dir(temp.path())
+        .env("WAVEFLOW_DATA_DIR", &config.data_dir)
+        .args(["key", "adopt", "--confirm"])
+        .output()
+        .unwrap();
+    let stdout = String::from_utf8(done.stdout).unwrap();
+    let stderr = String::from_utf8(done.stderr).unwrap();
+    assert!(done.status.success(), "the adoption failed: {stderr}");
+    assert!(
+        stdout.contains(
+            "Done. 2 Subsonic password(s) and 1 scrobbling link(s) deleted, \
+             with 3 queued listen(s); 4 share(s) re-addressed."
+        ),
+        "the closing line did not report the operation: {stdout}"
+    );
+    assert!(
+        config.instance_key_path.exists(),
+        "the adoption left no key behind"
+    );
+}

From 9575b87c515f875537d360b9624a6323eaab9f29 Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Tue, 13 Oct 2026 20:30:22 +0200
Subject: [PATCH 2/5] fix(cli): a reading of a key change applies no migration
 either
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two findings from review, both taken.

A key change migrated before it counted — including the half that says it
changes nothing. Applying a migration rewrites `_sqlx_migrations` and runs
whatever the migration itself does, on a database the operator has not agreed
to touch. `Database::schema_state` is asked instead, and a reading of a
database behind this binary says so and stops rather than making the one
change it promised not to make. `Current` is also what lets `key_material`
count without guarding each table: it means every migration this binary
carries has run, so every table it creates is there.

With `--confirm`, the copy now precedes the migration, so what lands in
`pre-key-…` is the database as the command found it rather than one at a
schema the operator never chose to run.

Adoption deletes the Subsonic *credential*, not only its password. The `wfsk_`
API key is a SHA-256 hash no key change can touch, but it shares a `NOT NULL`
row with the password that is encrypted, so the row goes whole and every
client authenticating by API key stops with it. Now said in the inventory the
command prints and in the operations guide, with `credential set` named as
what mints the new pair to hand out.

Both halves are held by a test in `migrations`, which is the target that can
build a database behind this binary — on a current schema, a reading that
migrates and one that does not are the same reading. It asserts the recovery
copy is still at the old schema while the live database is at the new one.
Two more inversions, each failing on its own assertion.

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 CLAUDE.md           |   2 +-
 docs/operations.md  |  36 +++++--
 src/cli.rs          | 232 ++++++++++++++++++++++++++++----------------
 src/database.rs     |  46 +++++++++
 tests/cli.rs        |   4 +-
 tests/migrations.rs | 135 ++++++++++++++++++++++++++
 6 files changed, 359 insertions(+), 96 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index f04373db..d9dede4d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -44,7 +44,7 @@ bun run build                          # webapp first, then cargo — the order
 
 Tests need no service container: `test_app()` builds a `Config` over a `TempDir` and the suite drives the same router `main` serves. FFmpeg and ffprobe must be on `PATH`.
 
-The integration suite is seventeen targets under `tests/`, one per subject — `auth`, `scanner`, `identity`, `catalog`, `subsonic_contract`, `subsonic_browse`, `subsonic_fields`, `subsonic_methods`, `native_api`, `sync`, `media`, `service`, `cli`, `scrobbling`, `uploads`, `canvas`, `migrations` — nearly all of them sharing `tests/support/mod.rs`. `migrations` is the exception and deliberately so: every other target starts from `test_app()`, which builds its database from nothing, and that is exactly the path an upgrade does not take. It seeds a database at each **released** schema, boots the server on it, and reads the rows back through the services. `autotests = false`, so each is a target only because `Cargo.toml` declares it: a new file under `tests/` is compiled by nothing until a `[[test]]` entry names it, and the count above is worth checking against that list rather than trusted. `support/mod.rs` is the exception that proves it — shared module code, declared nowhere, a target never. File a new test by the surface it exercises, and check that by what it calls rather than by what its name says.
+The integration suite is seventeen targets under `tests/`, one per subject — `auth`, `scanner`, `identity`, `catalog`, `subsonic_contract`, `subsonic_browse`, `subsonic_fields`, `subsonic_methods`, `native_api`, `sync`, `media`, `service`, `cli`, `scrobbling`, `uploads`, `canvas`, `migrations` — nearly all of them sharing `tests/support/mod.rs`. `migrations` is the exception and deliberately so: every other target starts from `test_app()`, which builds its database from nothing, and that is exactly the path an upgrade does not take. It seeds a database at each **released** schema, boots the server on it, and reads the rows back through the services — and it is where anything else that needs a database *behind* this binary belongs, such as proving that a key change reads without migrating and copies the pair aside before it does. `autotests = false`, so each is a target only because `Cargo.toml` declares it: a new file under `tests/` is compiled by nothing until a `[[test]]` entry names it, and the count above is worth checking against that list rather than trusted. `support/mod.rs` is the exception that proves it — shared module code, declared nowhere, a target never. File a new test by the surface it exercises, and check that by what it calls rather than by what its name says.
 
 `cargo build` works without a client build — `build.rs` embeds a placeholder page when `webapp/dist` is absent. A real `vite build` overwrites it.
 
diff --git a/docs/operations.md b/docs/operations.md
index d0669bc7..9b107666 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -32,14 +32,23 @@ unrecoverable, or when it must be replaced because it leaked.
 
 ### What you lose, and what you keep
 
-Almost everything is unaffected, because almost nothing is encrypted:
+This is the **adoption** case below, where the key is genuinely gone. A
+rotation, where you still hold it, loses nothing from the left-hand column.
+
+Almost everything is unaffected either way, because almost nothing is
+encrypted:
 
 | Lost, and re-entered by hand | Survives untouched |
 | --- | --- |
-| The dedicated Subsonic password of every account | Every account, and its web password — Argon2id, never encrypted |
+| The Subsonic credential of every account — the dedicated password **and** the `wfsk_` API key beside it | Every account, and its web password — Argon2id, never encrypted |
 | Every external scrobbling link (Last.fm, ListenBrainz, Maloja), and the listens queued behind it | The whole catalogue: tracks, albums, artists, libraries and their members |
 | | Favourites, ratings, playlists, play queues, listening history, bookmarks |
 
+The API key is not encrypted — it is stored as a SHA-256 hash, which no key
+change can touch — but it shares its row with the password that is, and the
+columns are `NOT NULL`. So the row goes whole. `credential set` mints a new
+password **and** a new API key, and both have to reach the client.
+
 Shares are kept but **their public URLs change**: a share token is derived from
 the instance key rather than stored, so every link handed out under the old key
 stops resolving. The commands below recompute the stored hash under the new
@@ -56,10 +65,12 @@ mint a ticket for any track they can address.
 They are named apart rather than separated by a flag, because one preserves
 exactly what the other destroys.
 
-Both run with the server **stopped** — they take the database exclusively and
-refuse a database another process is holding — and both are a reading until you say
-otherwise: without `--confirm` they count what the change costs, print it, and
-change nothing.
+Both run with the server **stopped**: they take the database exclusively, and
+refuse one another process is holding. And both are a reading until you say
+otherwise — without `--confirm` they count what the change costs, print it,
+and change nothing at all. Not even a pending migration: if the binary carries
+migrations this database has not run, the reading says so and stops, because
+applying one is a change and this half makes none.
 
 **The old key is in hand**, and you want a different one — it leaked, or it is
 simply time:
@@ -79,15 +90,20 @@ waveflow-server key adopt
 waveflow-server key adopt --confirm
 ```
 
-The Subsonic passwords and the scrobbling links go, the queued listens with
+The Subsonic credentials and the scrobbling links go, the queued listens with
 them, and a fresh key is bound to the catalogue you already had. `adopt`
 refuses outright when the key beside the database still opens it: that is a
 rotation, and a rotation costs nothing.
 
 Both move the previous pair into a timestamped `data/pre-key-…` directory
-before touching anything, the way `database restore` does. Afterwards, re-set
-the Subsonic password of each account with `credential set`, and re-link any
-scrobbling destination.
+before touching anything — before any pending migration as well as before the
+key, so what is in there is the database as the command found it. The way
+`database restore` does.
+
+Afterwards, re-set the Subsonic credential of each account with
+`credential set` and hand each client its new password and API key, re-link
+any scrobbling destination, and **take a fresh backup**: the new key is exactly
+as unrecoverable as the one you just replaced.
 
 **Not by hand.** Deleting `subsonic_credential`, `scrobble_link` and
 `instance_metadata` in SQL — which is what this page documented before the
diff --git a/src/cli.rs b/src/cli.rs
index 1f6e76a8..02dcea00 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -12,7 +12,9 @@ use sqlx::Connection;
 use crate::{
     authentication::now_ms,
     catalog::LibraryRecord,
-    database::{AccountRole, Database, KeyMaterial, LibraryRole, LibraryVisibility, Rekey},
+    database::{
+        AccountRole, Database, KeyMaterial, LibraryRole, LibraryVisibility, Rekey, SchemaState,
+    },
     security, AppState,
 };
 
@@ -412,23 +414,37 @@ fn read_instance_key(config: &crate::Config) -> anyhow::Result<Option<Vec<u8>>>
     }
 }
 
-/// The database, held alone and brought up to date.
+/// Which of the two commands is speaking.
 ///
-/// The migration is not a side errand. This command writes rows, and writing
-/// rows into a schema older than the binary is how a repair becomes damage —
-/// `scrobble_link` does not exist before 2.0.0-beta.1, and an operator who
-/// lost a key is often the same one who just replaced a container image. It is
-/// also exactly what the next boot would do.
+/// 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.
 ///
-/// `migrate_on` leaves foreign keys off on the connection it is handed, and
-/// nothing here puts them back: `Database::rekey` asks for them itself,
-/// because it is the one caller whose correctness depends on them. A second
-/// `PRAGMA` here would be one no inversion could tell from its absence.
-async fn open_for_key_change(config: &crate::Config) -> anyhow::Result<sqlx::SqliteConnection> {
+/// 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?;
-    Database::migrate_on(&mut connection).await?;
-    Ok(connection)
+    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<()> {
@@ -444,7 +460,7 @@ async fn rotate_key(config: &crate::Config, args: KeyArgs) -> anyhow::Result<()>
             config.instance_key_path.display()
         )
     })?;
-    let mut connection = open_for_key_change(config).await?;
+    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!(
@@ -452,32 +468,16 @@ async fn rotate_key(config: &crate::Config, args: KeyArgs) -> anyhow::Result<()>
             );
         }
     }
-    let material = Database::key_material(&mut connection).await?;
-    println!(
-        "Rotating the instance key of {}.",
-        config.database_path.display()
-    );
-    println!();
-    println!(
-        "  {} Subsonic password(s) — moved to the new key, unchanged for their owners",
-        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
-    );
-    println!();
     if !args.confirm {
-        println!("Nothing has been changed. Re-run with --confirm.");
-        return Ok(());
+        return report_reading(&mut connection, schema, Intent::Rotate, config).await;
     }
-    let (moved, recovery) = replace_key(config, connection, Rekey::Reencrypt(&old_key)).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 password(s) and {} scrobbling link(s) moved to the new key; {} share(s) re-addressed.",
+        "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);
@@ -486,7 +486,7 @@ async fn rotate_key(config: &crate::Config, args: KeyArgs) -> anyhow::Result<()>
 
 async fn adopt_key(config: &crate::Config, args: KeyArgs) -> anyhow::Result<()> {
     let present = read_instance_key(config)?;
-    let mut connection = open_for_key_change(config).await?;
+    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)) {
@@ -495,58 +495,108 @@ async fn adopt_key(config: &crate::Config, args: KeyArgs) -> anyhow::Result<()>
             );
         }
     }
-    let material = Database::key_material(&mut connection).await?;
-    println!(
-        "Adopting {} under a new instance key.",
-        config.database_path.display()
-    );
-    println!();
-    println!("The old key is gone, so nothing sealed under it can be carried over:");
-    println!();
-    println!(
-        "  {} Subsonic password(s) — deleted; re-set each with `credential set`",
-        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!();
     if !args.confirm {
-        println!("Nothing has been changed. Re-run with --confirm.");
-        return Ok(());
+        return report_reading(&mut connection, schema, Intent::Adopt, config).await;
     }
-    let (moved, recovery) = replace_key(config, connection, Rekey::Discard).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 password(s) and {} scrobbling link(s) deleted, with {} queued listen(s); {} share(s) re-addressed.",
+        "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 two commands do identically once the decision is made.
+/// What the command answers when it has not been told to go ahead.
 ///
-/// Answers with what was actually moved, not with what was predicted a moment
-/// earlier: the counts above come from reading the tables, these come from the
-/// statements that touched them, and a line printed from the second is the
-/// only one that reports the operation rather than the plan.
-async fn replace_key(
+/// 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,
-    mut connection: sqlx::SqliteConnection,
-    plan: Rekey<'_>,
-) -> anyhow::Result<(KeyMaterial, PathBuf)> {
-    // Before anything is touched, and a coherent pair rather than a file copy:
-    // `database restore` leaves the same kind of directory behind, for the
-    // same reason. The schema in it is the one this command had to reach in
-    // order to read the database at all; everything else is as it was found.
+) -> 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!();
+}
+
+/// 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()));
@@ -557,13 +607,26 @@ async fn replace_key(
         .ok_or_else(|| anyhow::anyhow!("the recovery path is not valid UTF-8"))?;
     sqlx::query("VACUUM INTO ?")
         .bind(saved)
-        .execute(&mut connection)
+        .execute(&mut *connection)
         .await
         .map_err(|error| anyhow::anyhow!("could not write the recovery copy: {error}"))?;
     if config.instance_key_path.exists() {
         tokio::fs::copy(&config.instance_key_path, recovery.join("instance.key")).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.
@@ -591,15 +654,18 @@ async fn replace_key(
     // database is settled on disk before the other half of the pair moves.
     connection.close().await?;
     tokio::fs::rename(&staged, &config.instance_key_path).await?;
-    Ok((moved, recovery))
+    Ok(moved)
 }
 
 fn report_done(recovery: &Path) {
     println!(
-        "Done. The previous pair is recoverable from {}",
+        "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<()> {
diff --git a/src/database.rs b/src/database.rs
index f3c44c70..d60c5667 100644
--- a/src/database.rs
+++ b/src/database.rs
@@ -17,6 +17,22 @@ use crate::{config::Config, security::EncryptedSecret};
 
 pub static MIGRATOR: Migrator = sqlx::migrate!("./migrations-v2");
 
+/// What this binary's migrations find in a database.
+///
+/// Asked before anything is applied, because the key commands promise a
+/// reading that changes nothing and applying a migration is a change. It is
+/// also what lets [`Database::key_material`] count without guarding each
+/// table: `Current` means every migration this binary carries has run, so
+/// every table it creates is there.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SchemaState {
+    /// No migration has run. The file is not a WaveFlow database yet.
+    Empty,
+    /// Every migration this binary carries has run.
+    Current,
+    /// This binary carries migrations the database has not run.
+    Behind(usize),
+}
 /// What an instance key protects, counted from the database.
 ///
 /// Four numbers rather than a sentence, because the sentence is what the
@@ -648,6 +664,36 @@ impl Database {
         Ok(connection)
     }
 
+    /// Where this database stands against the migrations this binary carries.
+    pub async fn schema_state(connection: &mut SqliteConnection) -> anyhow::Result<SchemaState> {
+        let has_table = sqlx::query_scalar::<_, i64>(
+            "SELECT EXISTS(SELECT 1 FROM sqlite_master \
+             WHERE type = 'table' AND name = '_sqlx_migrations')",
+        )
+        .fetch_one(&mut *connection)
+        .await?;
+        if has_table == 0 {
+            return Ok(SchemaState::Empty);
+        }
+        let applied = sqlx::query_scalar::<_, i64>(
+            "SELECT version FROM _sqlx_migrations WHERE success = TRUE",
+        )
+        .fetch_all(&mut *connection)
+        .await?;
+        if applied.is_empty() {
+            return Ok(SchemaState::Empty);
+        }
+        let pending = MIGRATOR
+            .iter()
+            .filter(|migration| !applied.contains(&migration.version))
+            .count();
+        Ok(if pending == 0 {
+            SchemaState::Current
+        } else {
+            SchemaState::Behind(pending)
+        })
+    }
+
     /// The fingerprint this database was bound to, if it has been bound.
     ///
     /// Absent on a database no server has ever opened. Present and different
diff --git a/tests/cli.rs b/tests/cli.rs
index beeae786..f1fc7359 100644
--- a/tests/cli.rs
+++ b/tests/cli.rs
@@ -1131,7 +1131,7 @@ async fn a_key_change_prints_what_it_costs_and_then_what_it_did() {
     let stderr = String::from_utf8(reading.stderr).unwrap();
     assert!(reading.status.success(), "the reading failed: {stderr}");
     for expected in [
-        "2 Subsonic password(s) — deleted",
+        "2 Subsonic credential(s) — deleted, password and `wfsk_` API key together",
         "1 scrobbling link(s) — deleted, and the 3 queued listen(s) behind them",
         "4 share(s) — kept, but every public URL changes",
         "Nothing has been changed. Re-run with --confirm.",
@@ -1154,7 +1154,7 @@ async fn a_key_change_prints_what_it_costs_and_then_what_it_did() {
     assert!(done.status.success(), "the adoption failed: {stderr}");
     assert!(
         stdout.contains(
-            "Done. 2 Subsonic password(s) and 1 scrobbling link(s) deleted, \
+            "Done. 2 Subsonic credential(s) and 1 scrobbling link(s) deleted, \
              with 3 queued listen(s); 4 share(s) re-addressed."
         ),
         "the closing line did not report the operation: {stdout}"
diff --git a/tests/migrations.rs b/tests/migrations.rs
index 83e91475..b9a80a4d 100644
--- a/tests/migrations.rs
+++ b/tests/migrations.rs
@@ -24,6 +24,7 @@
 //! recognise.
 
 use sqlx::migrate::Migrate;
+use sqlx::Connection;
 use sqlx::SqliteConnection;
 use waveflow_server::database::Database;
 use waveflow_server::database::MIGRATOR;
@@ -414,3 +415,137 @@ async fn every_released_schema_upgrades_with_the_rows_it_was_holding() {
         assert_eq!(top[0].title, "Zenith", "{tag}");
     }
 }
+
+/// A key change reads without migrating, and copies before it does.
+///
+/// Here rather than beside the other key tests in `cli.rs` for the reason this
+/// whole target exists: `test_app()` builds a current schema, and on a current
+/// schema a reading that migrates and one that does not are the same reading.
+/// Only a database *behind* the binary can tell them apart, and building one
+/// is what this file already knows how to do.
+///
+/// Two promises, both of which only a lagging schema can hold to account:
+///
+/// - **a reading changes nothing**, so `key rotate` without `--confirm` must
+///   leave `_sqlx_migrations` exactly as it found it — applying a migration is
+///   a change, whatever else it is;
+/// - **the recovery copy is the database as found**, so it must still be at
+///   the old schema after the confirmed run brought the live one forward. A
+///   copy taken afterwards would restore the operator to a schema they never
+///   chose to run.
+#[tokio::test]
+async fn a_key_change_reads_without_migrating_and_copies_before_it_migrates() {
+    let total = MIGRATOR.iter().count();
+    let (tag, baseline) = RELEASED_SCHEMAS[RELEASED_SCHEMAS.len() - 1];
+    let temp = tempfile::tempdir().expect("temporary directory");
+    let config = Config::for_data_dir(temp.path().join("data"));
+
+    let database = Database::open(&config).await.expect("open the database");
+    let mut connection = database.pool().acquire().await.expect("connection");
+    connection
+        .ensure_migrations_table(&MIGRATOR.table_name)
+        .await
+        .expect("migrations table");
+    for migration in MIGRATOR
+        .iter()
+        .filter(|migration| migration.version <= baseline)
+    {
+        connection
+            .apply(&MIGRATOR.table_name, migration)
+            .await
+            .unwrap_or_else(|error| {
+                panic!("{tag}: migration {} failed: {error}", migration.version)
+            });
+    }
+    // The pair that schema was running under. Written by hand because the only
+    // thing this test needs from it is that the two halves agree: `rotate`
+    // refuses a key the database was not bound to, and that refusal is not
+    // what is being measured here.
+    let key = [5u8; 32];
+    std::fs::write(&config.instance_key_path, key).expect("the key file");
+    sqlx::query(
+        "INSERT INTO instance_metadata (singleton, key_fingerprint, created_at) VALUES (1, ?, 0)",
+    )
+    .bind(waveflow_server::security::bytes_hash(&key).as_slice())
+    .execute(&mut *connection)
+    .await
+    .expect("bind the key");
+    let behind = count(&mut connection, "SELECT COUNT(*) FROM _sqlx_migrations").await;
+    assert!(
+        (behind as usize) < total,
+        "{tag}: the baseline applied all {total} migrations, so nothing is behind"
+    );
+    drop(connection);
+    database.pool().close().await;
+    drop(database);
+
+    // One: the reading. It is told there is an upgrade waiting, and leaves it
+    // waiting.
+    waveflow_server::cli::key(
+        &config,
+        waveflow_server::cli::KeyCommand::Rotate(waveflow_server::cli::KeyArgs { confirm: false }),
+    )
+    .await
+    .expect("a reading of a lagging database");
+    assert_eq!(
+        applied_in(&config.database_path).await,
+        behind,
+        "a reading applied a migration"
+    );
+    assert_eq!(
+        std::fs::read(&config.instance_key_path).unwrap(),
+        key,
+        "a reading replaced the key"
+    );
+
+    // Two: the change. The copy is the database as it was found.
+    waveflow_server::cli::key(
+        &config,
+        waveflow_server::cli::KeyCommand::Rotate(waveflow_server::cli::KeyArgs { confirm: true }),
+    )
+    .await
+    .expect("a confirmed rotation of a lagging database");
+    assert_ne!(
+        std::fs::read(&config.instance_key_path).unwrap(),
+        key,
+        "the rotation kept the old key"
+    );
+    let recovery = std::fs::read_dir(&config.data_dir)
+        .unwrap()
+        .map(|entry| entry.unwrap().path())
+        .find(|path| {
+            path.file_name()
+                .and_then(|name| name.to_str())
+                .is_some_and(|name| name.starts_with("pre-key-"))
+        })
+        .expect("a recovery directory");
+    assert_eq!(
+        applied_in(&recovery.join("waveflow.db")).await,
+        behind,
+        "the recovery copy was taken after the schema had already moved"
+    );
+    assert_eq!(
+        applied_in(&config.database_path).await as usize,
+        total,
+        "the rotation left migrations unapplied"
+    );
+
+    // And the pair it leaves behind is one the server opens.
+    waveflow_server::initialize(&config)
+        .await
+        .expect("the rotated pair must boot");
+}
+
+/// How many migrations a database on disk has run.
+///
+/// Opened alone and closed again between readings: the key commands take the
+/// file exclusively, and a connection this test forgot to close would make the
+/// next one fail for a reason that has nothing to do with what it asserts.
+async fn applied_in(path: &std::path::Path) -> i64 {
+    let mut connection = Database::open_alone(path, std::time::Duration::from_secs(5))
+        .await
+        .unwrap_or_else(|error| panic!("{}: {error}", path.display()));
+    let applied = count(&mut connection, "SELECT COUNT(*) FROM _sqlx_migrations").await;
+    connection.close().await.expect("close");
+    applied
+}

From c3910fa44474e987ae76363bae67ec8211eaba0c Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Tue, 13 Oct 2026 20:34:41 +0200
Subject: [PATCH 3/5] fix(cli): an unfinished key change says where the new key
 is waiting

Past the commit, a failure closing the connection or renaming the staged file
is not a failed operation but an unfinished one: the database already answers
to the new key and only the file is missing. The error now names both paths,
so the operator has the one move that finishes it rather than a server that
will not start and nothing saying why.

And a sentence in the operations guide that had lost its verb.

Both from the second review round.

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 docs/operations.md |  2 +-
 src/cli.rs         | 19 +++++++++++++++++--
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/docs/operations.md b/docs/operations.md
index 9b107666..278010ee 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -66,7 +66,7 @@ They are named apart rather than separated by a flag, because one preserves
 exactly what the other destroys.
 
 Both run with the server **stopped**: they take the database exclusively, and
-refuse one another process is holding. And both are a reading until you say
+refuse to run at all while another process is holding it. And both are a reading until you say
 otherwise — without `--confirm` they count what the change costs, print it,
 and change nothing at all. Not even a pending migration: if the binary carries
 migrations this database has not run, the reading says so and stops, because
diff --git a/src/cli.rs b/src/cli.rs
index 02dcea00..986e09fb 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -652,8 +652,23 @@ async fn install_new_key(
     };
     // 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.
-    connection.close().await?;
-    tokio::fs::rename(&staged, &config.instance_key_path).await?;
+    //
+    // 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)?;
     Ok(moved)
 }
 

From de6c2fbef489b3bfeda11eb7cabc90ce5997143c Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Tue, 13 Oct 2026 20:52:58 +0200
Subject: [PATCH 4/5] fix(cli): a key change that survives the machine stopping
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Writing a file leaves its bytes in the page cache, and creating or renaming
one leaves the directory holding a change of its own. Neither is on disk until
something asks, and the event these commands guard against is the one that
does not ask politely.

Two windows, and the second is the one that matters. The recovery copy is the
operator's way back, so its database, its key and the directory claiming to
hold them are synchronised before anything is changed — a failure there is
then a refusal rather than a half-finished operation. And after the rename
that installs the new key, the parent directory is synchronised too: the
rename is atomic, but the entry it made is not durable until the directory is,
and a machine that stops in that window leaves a database bound to a key whose
file never existed. Which is precisely the state this whole command exists to
get somebody out of.

`sync_file` opens for writing rather than read-only, which is the spelling
that first suggests itself: Windows refuses `FlushFileBuffers` on a handle
with no write access and answers "Access is denied" — measured, after three
tests failed on it. `sync_directory` is Unix-only, because a Windows directory
cannot be opened as a file to be synchronised.

Nothing here can be proved by an inversion — a power cut is not one — so it is
written for the property and says so in the doc comment rather than pretending
a test covers it. The failure after the rename is reported rather than
returned: the change is complete by then, and failing would hide the recovery
path the caller is about to print.

From the fourth review round.

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 src/cli.rs | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 62 insertions(+), 1 deletion(-)

diff --git a/src/cli.rs b/src/cli.rs
index 986e09fb..762eb7b5 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -587,6 +587,46 @@ fn print_inventory(intent: Intent, database: &Path, material: &KeyMaterial) {
     println!();
 }
 
+/// Puts a file on disk, rather than in the page cache.
+///
+/// Opened for writing rather than read-only, which is the spelling that first
+/// suggests itself: Windows refuses `FlushFileBuffers` on a handle with no
+/// write access, and answers "Access is denied" to a call that is only asking
+/// for durability.
+async fn sync_file(path: &Path) -> std::io::Result<()> {
+    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
@@ -610,9 +650,17 @@ async fn copy_the_pair_aside(
         .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() {
-        tokio::fs::copy(&config.instance_key_path, recovery.join("instance.key")).await?;
+        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)
 }
 
@@ -669,6 +717,19 @@ async fn install_new_key(
     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)
 }
 

From ab2efaa07ed1cf556bffc597473e76768c45e34c Mon Sep 17 00:00:00 2001
From: InstaZDLL <github.105mh@8shield.net>
Date: Tue, 13 Oct 2026 21:04:17 +0200
Subject: [PATCH 5/5] fix(cli): the data directory is durable before the
 commit, not after
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous commit synchronised the `pre-key-…` directory and, after the
rename, the directory holding the key. It left the window that matters open:
the *entries* naming `pre-key-…` and the staged key both live in the data
directory, and nothing made that durable until after the commit. A machine
stopping between the two came back with a database bound to a new key, no
file holding it, and no copy to go back to — the exact state this command
exists to get somebody out of, arrived at by the command itself.

The data directory is now synchronised once the staged key exists and before
`Database::rekey`, so both entries are real before anything is committed.

`sync_file` also opens read-only on Unix. `fs::copy` carries the source's
permissions over, so an `instance.key` hardened to mode 0400 produced a copy
that could not be opened for writing, and the fsync that only wanted
durability refused — turning a sensible precaution into a server that cannot
rotate its key. Unix allows fsync on a read-only descriptor; Windows does not,
and keeps the write-open it needs for `FlushFileBuffers`.

Both from the second GitHub review round.

Signed-off-by: InstaZDLL <github.105mh@8shield.net>
---
 src/cli.rs | 41 +++++++++++++++++++++++++++++++----------
 1 file changed, 31 insertions(+), 10 deletions(-)

diff --git a/src/cli.rs b/src/cli.rs
index 762eb7b5..13fbb3de 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -589,17 +589,28 @@ fn print_inventory(intent: Intent, database: &Path, material: &KeyMaterial) {
 
 /// Puts a file on disk, rather than in the page cache.
 ///
-/// Opened for writing rather than read-only, which is the spelling that first
-/// suggests itself: Windows refuses `FlushFileBuffers` on a handle with no
-/// write access, and answers "Access is denied" to a call that is only asking
-/// for durability.
+/// 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<()> {
-    tokio::fs::OpenOptions::new()
-        .write(true)
-        .open(path)
-        .await?
-        .sync_all()
-        .await
+    #[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.
@@ -683,6 +694,16 @@ async fn install_new_key(
         .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,