From 727042d46b05a74dbb956f1c1883b2f648cf0e97 Mon Sep 17 00:00:00 2001
From: Aakash N S <1560745+aakashns@users.noreply.github.com>
Date: Mon, 19 Oct 2026 15:50:11 +0700
Subject: [PATCH] Change your password in Settings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Settings has a new last row, "Change password". Enter or a click opens a
dialog with three boxes: your current password, the new one, and the new
one again. Tab moves between them, Enter goes on to the next empty one
and then changes the password, and Esc cancels. A wrong current password,
a confirmation that doesn't match, or a new password under 8 characters
is said in the dialog, which stays open. It says "Changing the password…"
while it works, then Settings says "Password changed."

Your vault is re-encrypted in place with the new password. writui backs
it up first and deletes the backup only once the vault has reopened with
the new password, passed its integrity checks and still holds exactly
what it did. If anything goes wrong, the vault is left (or put back from
the backup) as it was, and the old password keeps working. If Touch ID is
on, it's set up again for the new password on its own; if that can't be
done, Touch ID is turned off and Settings says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Cargo.lock                 |   2 +-
 Cargo.toml                 |   2 +-
 README.md                  |   7 +
 docs/DECISIONS.md          |  36 ++++
 docs/PLAN.md               |   4 +-
 docs/SPEC.md               |  32 +++-
 src/tui/change_password.rs | 321 ++++++++++++++++++++++++++++++++++
 src/tui/mod.rs             |  97 ++++++++++-
 src/tui/settings.rs        | 100 ++++++++++-
 src/tui/setup.rs           |   5 +-
 src/tui/widgets.rs         |   3 +
 src/vault/migrations.rs    |  12 +-
 src/vault/mod.rs           | 343 +++++++++++++++++++++++++++++++++++--
 13 files changed, 925 insertions(+), 39 deletions(-)
 create mode 100644 src/tui/change_password.rs

diff --git a/Cargo.lock b/Cargo.lock
index b82b665..8437f92 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2937,7 +2937,7 @@ checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
 
 [[package]]
 name = "writui"
-version = "0.19.0"
+version = "0.20.0"
 dependencies = [
  "anyhow",
  "arboard",
diff --git a/Cargo.toml b/Cargo.toml
index ad7283d..13572d9 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "writui"
-version = "0.19.0"
+version = "0.20.0"
 edition = "2024"
 description = "A terminal writing app. No nonsense. Markdown. Local. Encrypted."
 license = "MIT"
diff --git a/README.md b/README.md
index 24af518..25f2f90 100644
--- a/README.md
+++ b/README.md
@@ -128,6 +128,13 @@ fingerprint to the Mac turns it off until you next unlock with the
 password. Your vault's key, sealed so that only this Mac's Secure Enclave
 can open it after a fingerprint, is kept in `~/.config/writui/touch-id/`.
 
+To change the password, open Settings and choose "Change password": type
+your current password, then the new one twice. writui re-encrypts the
+vault with the new password, keeping a backup of it until the vault has
+reopened with the new password and passed its checks; if anything goes
+wrong, the old password keeps working. Touch ID is set up again for the
+new password on its own.
+
 - **Posts** are listed with the most recently changed first. Open one with
   Enter or a click, start a new one with `n` (or Enter: "New" is
   highlighted when the list opens). The list's shortcuts are single keys,
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index 2533f9d..6e09fc3 100644
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@ -785,3 +785,39 @@ copied in the meantime. The trade-off: "select, Cmd+C, then type over the
 selection" loses the copy (Cmd+X is the way to do that). Non-text clipboard
 contents (an image) can't be remembered, so selecting text replaces them.
 Tests use a per-thread fake clipboard rather than the real one.
+
+## Changing the password: rekey in place, checked end to end
+
+`Vault::change_password` checks the current password (Argon2 with the
+file's salt must give the open vault's key), makes a new random salt and
+the new password's key, takes a fingerprint (SHA-256 over the schema
+version and every row of every table), backs the file up next to itself
+(`writui.db.password-<time>.bak`), then runs `PRAGMA rekey` with the raw
+key and new salt. SQLCipher rewrites every page in one transaction and
+puts the new salt in the file's first 16 bytes. The change counts only
+once the vault opens from scratch just as an unlock would (salt read from
+the file, key from the new password), passes `cipher_integrity_check` and
+`integrity_check`, and has the same fingerprint; then the backup is
+deleted. (If deleting it fails, Settings names it: the old password opens
+it.)
+
+If anything fails after the backup, the old connection is closed and the
+vault reopened with the old key, checking the salt, integrity and
+fingerprint; if that doesn't pass (the rekey went through, or left a
+damaged file), any `-journal` is removed (it belongs to the failed
+change, not the backup) and the backup copied back over the vault, then
+checked the same way. Only if that fails too is the vault left closed:
+writui stops with an error naming the backup. Tests break the change
+after the rekey (a failing check, a damaged vault, a damaged vault and
+backup) through a hook, and check the old password still works each time.
+
+Rekeying in place was the creator's choice over `sqlcipher_export` into a
+new file and renaming it. A second writui open on the same vault would
+lose access when the key changes under it; nothing stops two from running
+today, and this doesn't make that worse in a way worth a lock file yet.
+
+Touch ID holds the vault's key, so after a change that went through, its
+file is made again with the new key (sealing needs no fingerprint); if
+that fails it's turned off, and Settings says so. The dialog (three boxed
+password fields, stacked) is its own small screen, `tui::change_password`,
+since the general dialog only has one plain text field.
diff --git a/docs/PLAN.md b/docs/PLAN.md
index 5a82853..df47daa 100644
--- a/docs/PLAN.md
+++ b/docs/PLAN.md
@@ -36,7 +36,8 @@ the logo, adds an Unlock button, trims the setup screen, and makes Esc on
 the list quit without asking. `0.18.0` unlocks with Touch ID on Macs
 (asked for out of order), and `0.19.0` adds the Markdown styling setting,
 list continuation and Cmd+C (also out of order; it replaces the closed
-PR #31's bold-title switch). Next:
+PR #31's bold-title switch). `0.20.0` adds Change password in Settings
+(out of order too). Next:
 
 1. **Try online** (writui.com/try), below: the creator wants it next, and
    it must work on a phone. Probably two or three PRs, in the order listed.
@@ -141,6 +142,7 @@ writui in the browser at writui.com/try, phones included (see the spec's
 ## M6 — LLM chat sidebar
 
 - [x] Settings screen, stored in the vault: author (for front matter), line width
+- [x] Change password (in Settings), with Touch ID set up again
 - [ ] More settings: what Tab types, and the rest listed in the spec
 - [ ] API keys for OpenAI + Anthropic in settings (or prompt on first open)
 - [ ] Sidebar that fits next to the editor (or takes over on narrow terminals)
diff --git a/docs/SPEC.md b/docs/SPEC.md
index a3a451d..f5bb8ac 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -239,7 +239,37 @@ in [DECISIONS.md](DECISIONS.md); the build order lives in [PLAN.md](PLAN.md).
   added, which deliberately voids it), writui says so, and the next
   password unlock sets it up again. Where it's available but off, the
   unlock screen's Overview gets one more line pointing to Settings.
-- Change password — planned (it must set Touch ID up again).
+
+  > Add a "Change password" setting. On the Settings screen it's a row
+  > like the others (with a faded line under it, e.g. "Asks for your
+  > current password, then a new one twice."). Enter or a click opens a
+  > dialog with three boxed password fields, like the setup screen's:
+  > current password, new password, confirm new password. Tab moves
+  > between them, Enter submits, Esc cancels. A wrong current password or
+  > a confirmation that doesn't match says so in the dialog and keeps the
+  > dialog open. Show a short "Changing the password…" while it works
+  > (Argon2 is slow), then "Password changed." on the Settings screen.
+  >
+  > This touches my real writing, so be careful. Re-encrypt the vault in
+  > place with SQLCipher's rekey: a new random salt and the new Argon2
+  > key. Back up the vault file first, and delete the backup only after
+  > the vault reopens with the new password and passes its integrity
+  > check. If anything fails, the old password must still work and
+  > nothing may be lost. If Touch ID is on, redo its key file for the new
+  > key (DECISIONS says this is needed), or turn Touch ID off and say so.
+
+- **Change password**: the last row of Settings. Its dialog has three
+  boxed fields (current, new, confirm new) under a reminder that there's
+  no recovery. Tab / ↑↓ move between the fields; Enter goes on to the
+  next empty one, then changes the password; Esc or "Cancel" closes it;
+  fields and buttons can be clicked. The new password needs at least 8
+  characters, like the first one. Mistakes (wrong current password, the
+  confirmation not matching, too short) are said in red in the dialog,
+  which stays open. While it works the dialog says "Changing the
+  password…"; then Settings says "Password changed." If Touch ID is on,
+  it's set up again for the new password; if that fails, Touch ID is
+  turned off and Settings says so. If the change fails, Settings says why
+  and that the old password still works.
 
 ## The screens
 
diff --git a/src/tui/change_password.rs b/src/tui/change_password.rs
new file mode 100644
index 0000000..96e230f
--- /dev/null
+++ b/src/tui/change_password.rs
@@ -0,0 +1,321 @@
+//! The "Change password" dialog, opened from Settings: three boxed
+//! password fields (the current password, the new one, and the new one
+//! again). Tab moves between them, Enter goes on to the next empty one or
+//! changes the password, Esc cancels, and the fields and buttons can be
+//! clicked.
+
+use ratatui::Frame;
+use ratatui::crossterm::event::{Event, KeyCode, MouseButton, MouseEventKind};
+use ratatui::layout::{Position, Rect};
+use ratatui::style::{Style, Stylize};
+use ratatui::text::{Line, Span};
+use ratatui::widgets::{Block, Clear, Paragraph};
+use zeroize::Zeroizing;
+
+use super::hints::{Hint, hint};
+use super::widgets::{MIN_PASSWORD_LEN, PasswordField, centered};
+
+const WIDTH: u16 = 56;
+const LABELS: [&str; 3] = ["Current password", "New password", "Confirm new password"];
+
+#[derive(Clone, Copy, PartialEq, Debug)]
+pub enum Cmd {
+    Submit,
+    NextField,
+    Cancel,
+}
+
+/// What the dialog asks for.
+pub enum Outcome {
+    /// Change the password from `current` to `new`.
+    Change {
+        current: Zeroizing<String>,
+        new: Zeroizing<String>,
+    },
+    Cancel,
+}
+
+#[derive(Default)]
+pub struct ChangePassword {
+    fields: [PasswordField; 3],
+    focus: usize,
+    error: Option<&'static str>,
+    /// Changing the password: input is ignored until it's done.
+    busy: bool,
+    field_areas: [Rect; 3],
+    /// Where the buttons were drawn, for clicks.
+    buttons: Vec<(Rect, Cmd)>,
+}
+
+impl ChangePassword {
+    pub fn set_busy(&mut self) {
+        self.busy = true;
+        self.error = None;
+    }
+
+    /// The current password typed wasn't the vault's.
+    pub fn wrong_password(&mut self) {
+        self.busy = false;
+        self.error = Some("That's not your current password.");
+        self.fields[0].clear();
+        self.focus = 0;
+    }
+
+    /// Hints for the hint bar while the dialog is open.
+    pub fn hints(&self) -> Vec<Hint<Cmd>> {
+        if self.busy {
+            return Vec::new();
+        }
+        vec![
+            hint("Enter", "change password", Cmd::Submit),
+            hint("Tab", "next field", Cmd::NextField),
+            hint("Esc", "cancel", Cmd::Cancel),
+        ]
+    }
+
+    pub fn render(&mut self, frame: &mut Frame) {
+        // A line, a blank, three boxes, the status, a blank, the buttons.
+        let (_, box_height) = super::widgets::PASSWORD_BOX;
+        let height = 2 + 3 * box_height + 3 + 2;
+        let area = centered(frame.area(), WIDTH, height);
+        let block = Block::bordered().title(" Change password ");
+        let inner = block.inner(area);
+        let inner = Rect { x: inner.x + 1, width: inner.width.saturating_sub(2), ..inner };
+        frame.render_widget(Clear, area);
+        frame.render_widget(block, area);
+
+        let note = "Forget it and the writing is gone: no recovery.";
+        frame.render_widget(Paragraph::new(note.dim()), Rect { height: 1, ..inner });
+        let mut y = inner.y + 2;
+        for (i, label) in LABELS.into_iter().enumerate() {
+            let field_area = Rect::new(inner.x, y, inner.width, box_height).intersection(inner);
+            self.field_areas[i] = field_area;
+            let focused = i == self.focus;
+            let cursor = self.fields[i].render_boxed(frame, field_area, label, focused);
+            if focused && !self.busy {
+                frame.set_cursor_position(cursor);
+            }
+            y += box_height;
+        }
+        let status = if self.busy {
+            Line::from("Changing the password…".dim())
+        } else if let Some(error) = self.error {
+            Line::from(error.red())
+        } else {
+            Line::default()
+        };
+        let status_area = Rect { y, height: 1, ..inner }.intersection(inner);
+        frame.render_widget(Paragraph::new(status), status_area);
+
+        // The buttons: Enter presses the first.
+        self.buttons.clear();
+        let mut spans = Vec::new();
+        let mut x = inner.x;
+        let buttons_y = y + 2;
+        for (i, (label, cmd)) in
+            [("Change password", Cmd::Submit), ("Cancel", Cmd::Cancel)].into_iter().enumerate()
+        {
+            if i > 0 {
+                spans.push(Span::raw("  "));
+                x += 2;
+            }
+            let text = format!("[ {label} ]");
+            let width = text.chars().count() as u16;
+            let style = if i == 0 { Style::new().reversed().bold() } else { Style::new() };
+            spans.push(Span::styled(text, style));
+            self.buttons.push((Rect::new(x, buttons_y, width, 1), cmd));
+            x += width;
+        }
+        let buttons_area = Rect { y: buttons_y, height: 1, ..inner }.intersection(inner);
+        frame.render_widget(Paragraph::new(Line::from(spans)), buttons_area);
+    }
+
+    /// Handle an event; `None` while the dialog stays open as it is.
+    pub fn handle(&mut self, event: Event) -> Option<Outcome> {
+        if self.busy {
+            return None;
+        }
+        match event {
+            Event::Key(key) => match key.code {
+                KeyCode::Enter => {
+                    // On to the next field, while there's one left to fill.
+                    match (self.focus + 1..3).find(|&i| self.fields[i].is_empty()) {
+                        Some(next) if !self.fields[self.focus].is_empty() => {
+                            self.focus = next;
+                            None
+                        }
+                        _ => self.run(Cmd::Submit),
+                    }
+                }
+                KeyCode::Esc => self.run(Cmd::Cancel),
+                KeyCode::Tab | KeyCode::Down => self.run(Cmd::NextField),
+                KeyCode::BackTab | KeyCode::Up => {
+                    self.focus = (self.focus + 2) % 3;
+                    None
+                }
+                _ => {
+                    if self.fields[self.focus].handle_key(key) {
+                        self.error = None;
+                    }
+                    None
+                }
+            },
+            Event::Paste(text) => {
+                self.fields[self.focus].paste(&text);
+                None
+            }
+            Event::Mouse(mouse) if mouse.kind == MouseEventKind::Down(MouseButton::Left) => {
+                let pos = Position::new(mouse.column, mouse.row);
+                if let Some(i) = self.field_areas.iter().position(|a| a.contains(pos)) {
+                    self.focus = i;
+                    return None;
+                }
+                let &(_, cmd) = self.buttons.iter().find(|(rect, _)| rect.contains(pos))?;
+                self.run(cmd)
+            }
+            _ => None,
+        }
+    }
+
+    /// Carry out a command from the dialog or the hint bar.
+    pub fn run(&mut self, cmd: Cmd) -> Option<Outcome> {
+        if self.busy {
+            return None;
+        }
+        match cmd {
+            Cmd::Cancel => Some(Outcome::Cancel),
+            Cmd::NextField => {
+                self.focus = (self.focus + 1) % 3;
+                None
+            }
+            Cmd::Submit => {
+                let [current, new, confirm] = &mut self.fields;
+                let (error, focus) = if current.is_empty() {
+                    ("Type your current password.", 0)
+                } else if new.len() < MIN_PASSWORD_LEN {
+                    ("Use at least 8 characters for the new password.", 1)
+                } else if new.value() != confirm.value() {
+                    confirm.clear();
+                    ("The new passwords don't match. Try confirming again.", 2)
+                } else {
+                    return Some(Outcome::Change {
+                        current: current.value().clone(),
+                        new: new.value().clone(),
+                    });
+                };
+                self.error = Some(error);
+                self.focus = focus;
+                None
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use ratatui::Terminal;
+    use ratatui::backend::TestBackend;
+    use ratatui::crossterm::event::{KeyEvent, KeyModifiers, MouseEvent};
+
+    use super::*;
+
+    fn screen(dialog: &mut ChangePassword) -> String {
+        let mut terminal = Terminal::new(TestBackend::new(80, 24)).unwrap();
+        terminal.draw(|frame| dialog.render(frame)).unwrap();
+        let buffer = terminal.backend().buffer();
+        (0..24)
+            .map(|y| (0..80).map(|x| buffer[(x, y)].symbol()).collect::<String>())
+            .collect::<Vec<_>>()
+            .join("\n")
+    }
+
+    fn press(dialog: &mut ChangePassword, code: KeyCode) -> Option<Outcome> {
+        dialog.handle(Event::Key(KeyEvent::new(code, KeyModifiers::NONE)))
+    }
+
+    fn type_text(dialog: &mut ChangePassword, text: &str) {
+        for ch in text.chars() {
+            press(dialog, KeyCode::Char(ch));
+        }
+    }
+
+    #[test]
+    fn three_boxes_with_enter_going_on_to_the_next() {
+        let mut dialog = ChangePassword::default();
+        let text = screen(&mut dialog);
+        for label in LABELS {
+            assert!(text.contains(label), "{text}");
+        }
+        assert!(text.contains("[ Change password ]") && text.contains("[ Cancel ]"), "{text}");
+        type_text(&mut dialog, "old password");
+        assert!(press(&mut dialog, KeyCode::Enter).is_none());
+        type_text(&mut dialog, "new password");
+        assert!(press(&mut dialog, KeyCode::Enter).is_none());
+        assert_eq!(dialog.focus, 2);
+        type_text(&mut dialog, "new password");
+        let Some(Outcome::Change { current, new }) = press(&mut dialog, KeyCode::Enter) else {
+            panic!("not changed")
+        };
+        assert_eq!((current.as_str(), new.as_str()), ("old password", "new password"));
+        assert!(screen(&mut dialog).contains("••••••••••••"));
+        dialog.set_busy();
+        assert!(screen(&mut dialog).contains("Changing the password…"));
+        assert!(press(&mut dialog, KeyCode::Esc).is_none());
+    }
+
+    #[test]
+    fn mistakes_are_said_in_the_dialog() {
+        let mut dialog = ChangePassword::default();
+        press(&mut dialog, KeyCode::Tab);
+        type_text(&mut dialog, "new password");
+        assert!(press(&mut dialog, KeyCode::Enter).is_none());
+        // Enter with the confirmation empty goes on to it, and then says
+        // what's missing.
+        assert_eq!(dialog.focus, 2);
+        press(&mut dialog, KeyCode::Enter);
+        assert!(screen(&mut dialog).contains("Type your current password."));
+        assert_eq!(dialog.focus, 0);
+        type_text(&mut dialog, "old password");
+        press(&mut dialog, KeyCode::Tab);
+        press(&mut dialog, KeyCode::Tab);
+        type_text(&mut dialog, "new passwork");
+        assert!(press(&mut dialog, KeyCode::Enter).is_none());
+        assert!(screen(&mut dialog).contains("The new passwords don't match."));
+        assert!(dialog.fields[2].is_empty() && dialog.focus == 2);
+        // Too short.
+        press(&mut dialog, KeyCode::BackTab);
+        for _ in 0..12 {
+            press(&mut dialog, KeyCode::Backspace);
+        }
+        type_text(&mut dialog, "short");
+        assert!(dialog.run(Cmd::Submit).is_none());
+        assert!(screen(&mut dialog).contains("Use at least 8 characters"));
+        // A wrong current password, once tried.
+        dialog.set_busy();
+        dialog.wrong_password();
+        assert!(screen(&mut dialog).contains("That's not your current password."));
+        assert!(dialog.fields[0].is_empty() && dialog.focus == 0);
+        assert!(matches!(press(&mut dialog, KeyCode::Esc), Some(Outcome::Cancel)));
+    }
+
+    #[test]
+    fn fields_and_buttons_can_be_clicked() {
+        let mut dialog = ChangePassword::default();
+        screen(&mut dialog);
+        let click = |dialog: &mut ChangePassword, rect: Rect| {
+            dialog.handle(Event::Mouse(MouseEvent {
+                kind: MouseEventKind::Down(MouseButton::Left),
+                column: rect.x + 1,
+                row: rect.y + 1.min(rect.height - 1),
+                modifiers: KeyModifiers::NONE,
+            }))
+        };
+        let third = dialog.field_areas[2];
+        assert!(click(&mut dialog, third).is_none());
+        assert_eq!(dialog.focus, 2);
+        let (submit, cancel) = (dialog.buttons[0].0, dialog.buttons[1].0);
+        assert!(click(&mut dialog, submit).is_none());
+        assert!(screen(&mut dialog).contains("Type your current password."));
+        assert!(matches!(click(&mut dialog, cancel), Some(Outcome::Cancel)));
+    }
+}
diff --git a/src/tui/mod.rs b/src/tui/mod.rs
index bb9b647..5e5b46d 100644
--- a/src/tui/mod.rs
+++ b/src/tui/mod.rs
@@ -1,5 +1,6 @@
 //! The terminal UI: terminal setup, the event loop, and switching screens.
 
+mod change_password;
 mod context_menu;
 mod dialog;
 mod editor;
@@ -33,7 +34,9 @@ use zeroize::Zeroizing;
 
 use crate::files;
 use crate::touch_id;
-use crate::vault::{ExportSettings, OpenError, Settings, Vault, title_from_first_line};
+use crate::vault::{
+    ChangeError, ExportSettings, OpenError, Settings, Vault, title_from_first_line,
+};
 
 /// What a screen asks the app to do in response to an event.
 pub enum Action {
@@ -90,6 +93,11 @@ pub enum Action {
     Lock,
     /// Turn unlocking with Touch ID on or off.
     SetTouchId(bool),
+    /// Change the vault's password.
+    ChangePassword {
+        current: Zeroizing<String>,
+        new: Zeroizing<String>,
+    },
 }
 
 /// Which post an imported file goes into.
@@ -444,6 +452,12 @@ impl App {
                 }
                 self.pending = Some(action);
             }
+            Action::ChangePassword { .. } => {
+                if let Screen::Settings(screen) = &mut self.screen {
+                    screen.changing_password();
+                }
+                self.pending = Some(action);
+            }
             Action::SetTouchId(on) => {
                 let vault = self.vault()?;
                 let result = match on {
@@ -609,10 +623,41 @@ impl App {
                 }
                 Ok(())
             }
+            Action::ChangePassword { current, new } => self.change_password(&current, &new),
             _ => self.apply(action),
         }
     }
 
+    /// Change the vault's password (see `Vault::change_password`), and set
+    /// Touch ID up again for the new key, or turn it off if that fails.
+    fn change_password(&mut self, current: &str, new: &str) -> Result<()> {
+        let vault = self.vault.as_mut().context("the vault is locked")?;
+        let old_key = vault.key().clone();
+        let result = vault.change_password(current, new);
+        // Touch ID keeps the vault's key, which has changed.
+        let mut touch_id_off = false;
+        if vault.key() != &old_key && touch_id::is_on(&self.vault_path) {
+            touch_id_off = touch_id::turn_on(&self.vault_path, vault.key()).is_err();
+            if touch_id_off {
+                let _ = touch_id::turn_off(&self.vault_path);
+            }
+        }
+        let Screen::Settings(screen) = &mut self.screen else { return Ok(()) };
+        match result {
+            Ok(None) => screen.password_changed(touch_id_off, None),
+            Ok(Some(backup)) => screen.password_changed(touch_id_off, Some(&backup)),
+            Err(ChangeError::WrongPassword) => screen.wrong_password(),
+            Err(ChangeError::Unchanged(err)) => screen.password_unchanged(format!(
+                "Couldn't change the password ({err:#}). The old one still works."
+            )),
+            // The vault is closed: there's nothing more writui can do.
+            Err(ChangeError::Broken(err)) => {
+                return Err(err.context("changing the password failed"));
+            }
+        }
+        Ok(())
+    }
+
     /// Import the file at `path` (see `Action::Import`), then open the
     /// post. If that doesn't work, says why.
     fn import(&mut self, path: &Path, into: ImportInto) -> Result<(), String> {
@@ -927,6 +972,56 @@ mod tests {
         assert_eq!((editor.post_id(), editor.text().as_str()), (id, "# x"));
     }
 
+    #[test]
+    fn the_password_is_changed_from_settings() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("writui.db");
+        let mut app = App::new(path.clone(), false);
+        app.perform(create_vault()).unwrap();
+        app.apply(Action::NewPost).unwrap();
+        app.handle(key(KeyCode::Char('x'), KeyModifiers::NONE, KeyEventKind::Press));
+        app.store_post(Leaving::Yes);
+        app.show_settings().unwrap();
+        let press = |app: &mut App, code: KeyCode| {
+            let action = app.handle(key(code, KeyModifiers::NONE, KeyEventKind::Press));
+            app.apply(action).unwrap();
+        };
+        let type_text = |app: &mut App, text: &str| {
+            text.chars().for_each(|ch| press(app, KeyCode::Char(ch)));
+        };
+        // Change password is the last row.
+        for _ in 0..10 {
+            press(&mut app, KeyCode::Down);
+        }
+        press(&mut app, KeyCode::Enter);
+        // A wrong current password: said in the dialog, nothing changed.
+        for text in ["nope", "new password", "new password"] {
+            type_text(&mut app, text);
+            press(&mut app, KeyCode::Enter);
+        }
+        let action = app.pending.take().expect("waits for a draw first");
+        app.perform(action).unwrap();
+        let Screen::Settings(screen) = &app.screen else { panic!("left settings") };
+        assert!(screen.changing_the_password());
+        // The new password is still typed in: Enter after the right
+        // current one changes it.
+        type_text(&mut app, "pw");
+        press(&mut app, KeyCode::Enter);
+        let action = app.pending.take().unwrap();
+        app.perform(action).unwrap();
+        let Screen::Settings(screen) = &app.screen else { panic!("left settings") };
+        assert!(!screen.changing_the_password());
+        assert_eq!(screen.notice(), Some("Password changed."));
+        // Only the new password opens it now, with the post still there.
+        app.lock();
+        app.perform(Action::Unlock(Zeroizing::new("pw".into()))).unwrap();
+        assert!(app.vault.is_none());
+        app.perform(Action::Unlock(Zeroizing::new("new password".into()))).unwrap();
+        let posts = app.vault.as_ref().unwrap().list_posts().unwrap();
+        assert_eq!(posts[0].title, "x");
+        assert!(matches!(app.screen, Screen::Settings(_)));
+    }
+
     #[test]
     fn caps_lock_capitalises() {
         let mut event =
diff --git a/src/tui/settings.rs b/src/tui/settings.rs
index f6f976d..6655da9 100644
--- a/src/tui/settings.rs
+++ b/src/tui/settings.rs
@@ -3,7 +3,8 @@
 //! all its options, the current one highlighted), and below it, faded,
 //! what that value does; lines separate them, and a bar on the left marks
 //! the selected one. Enter (or a click) changes it in a dialog, or switches
-//! it to its next option; ←/→ or a click on an option picks one.
+//! it to its next option; ←/→ or a click on an option picks one. The last
+//! row isn't a setting but changes the password, in its own dialog.
 
 use ratatui::Frame;
 use ratatui::crossterm::event::{Event, KeyCode, MouseButton, MouseEventKind};
@@ -13,6 +14,7 @@ use ratatui::text::{Line, Span};
 use ratatui::widgets::{ListState, Paragraph};
 
 use super::Action;
+use super::change_password::{self, ChangePassword, Outcome};
 use super::dialog::{Button, Dialog};
 use super::hints::{HintBar, hint};
 use super::widgets::{COLUMN_WIDTH, column, truncate};
@@ -32,6 +34,7 @@ enum Field {
     Styling,
     NerdFont,
     TouchId,
+    Password,
 }
 
 #[derive(Clone, Copy)]
@@ -51,6 +54,8 @@ pub struct Settings {
     state: ListState,
     /// Changing the highlighted setting.
     dialog: Option<Dialog<Cmd>>,
+    password: Option<ChangePassword>,
+    password_hints: HintBar<change_password::Cmd>,
     notice: Option<String>,
     error: Option<String>,
     rows_area: Rect,
@@ -71,12 +76,15 @@ impl Settings {
         if touch_id.is_some() {
             fields.push(Field::TouchId);
         }
+        fields.push(Field::Password);
         Settings {
             values,
             touch_id,
             fields,
             state: ListState::default().with_selected(Some(0)),
             dialog: None,
+            password: None,
+            password_hints: HintBar::default(),
             notice: None,
             error: None,
             rows_area: Rect::default(),
@@ -101,6 +109,54 @@ impl Settings {
         });
     }
 
+    /// The new password is being worked out (Argon2 is slow).
+    pub fn changing_password(&mut self) {
+        if let Some(dialog) = &mut self.password {
+            dialog.set_busy();
+        }
+    }
+
+    /// The current password typed into the dialog was wrong.
+    pub fn wrong_password(&mut self) {
+        if let Some(dialog) = &mut self.password {
+            dialog.wrong_password();
+        }
+    }
+
+    /// The password was changed. Touch ID had to be turned off if
+    /// `touch_id_off`; `backup` is a backup of the vault that couldn't be
+    /// deleted.
+    pub fn password_changed(&mut self, touch_id_off: bool, backup: Option<&std::path::Path>) {
+        self.password = None;
+        self.error = None;
+        let mut notice = String::from("Password changed.");
+        if touch_id_off {
+            self.touch_id = Some(false);
+            notice.push_str(" Touch ID is off: switch it on again to use it.");
+        }
+        if let Some(backup) = backup {
+            notice.push_str(&format!(" Delete {}: the old one opens it.", backup.display()));
+        }
+        self.notice = Some(notice);
+    }
+
+    /// Changing the password failed, saying why.
+    pub fn password_unchanged(&mut self, error: String) {
+        self.password = None;
+        self.set_error(error);
+    }
+
+    /// The Change password dialog is open.
+    #[cfg(test)]
+    pub fn changing_the_password(&self) -> bool {
+        self.password.is_some()
+    }
+
+    #[cfg(test)]
+    pub fn notice(&self) -> Option<&str> {
+        self.notice.as_deref()
+    }
+
     fn field(&self) -> Field {
         self.fields[self.state.selected().unwrap_or(0).min(self.fields.len() - 1)]
     }
@@ -112,6 +168,7 @@ impl Settings {
             Field::Styling => "Markdown styling",
             Field::NerdFont => "Nerd Font",
             Field::TouchId => "Touch ID",
+            Field::Password => "Change password",
         }
     }
 
@@ -120,7 +177,7 @@ impl Settings {
     fn options(&self, field: Field) -> Option<(Vec<&'static str>, usize)> {
         let on_off = |on: bool| (vec!["on", "off"], if on { 0 } else { 1 });
         match field {
-            Field::Author | Field::LineWidth => None,
+            Field::Author | Field::LineWidth | Field::Password => None,
             Field::Styling => Some((
                 STYLINGS.iter().map(|s| s.name()).collect(),
                 STYLINGS.iter().position(|&s| s == self.values.styling).unwrap_or(0),
@@ -135,6 +192,7 @@ impl Settings {
         match field {
             Field::Author if self.values.author.is_empty() => Span::raw("none").dim().italic(),
             Field::Author => Span::raw(self.values.author.clone()),
+            Field::Password => Span::raw(""),
             _ => Span::raw(format!("{} characters", self.values.line_width)),
         }
     }
@@ -150,7 +208,7 @@ impl Settings {
             Field::Styling => values.styling = STYLINGS[i.min(STYLINGS.len() - 1)],
             Field::NerdFont => values.nerd_font = i == 0,
             Field::TouchId => return Action::SetTouchId(i == 0),
-            Field::Author | Field::LineWidth => {}
+            Field::Author | Field::LineWidth | Field::Password => {}
         }
         self.save(values)
     }
@@ -186,6 +244,7 @@ impl Settings {
                 "Unlocks with your fingerprint when writui starts.".into()
             }
             Field::TouchId => "Unlocking takes the password.".into(),
+            Field::Password => "Asks for your current password, then a new one twice.".into(),
         }
     }
 
@@ -290,6 +349,12 @@ impl Settings {
             self.hints.render(frame, hint_area, &hints);
             return;
         }
+        if let Some(dialog) = &mut self.password {
+            dialog.render(frame);
+            let hints = dialog.hints();
+            self.password_hints.render(frame, hint_area, &hints);
+            return;
+        }
         let mut hints = match self.options(self.field()) {
             Some(_) => {
                 vec![hint("←/→", "choose", Cmd::Change), hint("Enter", "switch", Cmd::Change)]
@@ -301,6 +366,24 @@ impl Settings {
     }
 
     pub fn handle(&mut self, event: Event) -> Action {
+        if let Some(dialog) = &mut self.password {
+            let mut outcome = dialog.handle(event.clone());
+            if outcome.is_none()
+                && let Event::Mouse(mouse) = event
+                && mouse.kind == MouseEventKind::Down(MouseButton::Left)
+                && let Some(cmd) = self.password_hints.hit(mouse.column, mouse.row)
+            {
+                outcome = dialog.run(cmd);
+            }
+            return match outcome {
+                Some(Outcome::Change { current, new }) => Action::ChangePassword { current, new },
+                Some(Outcome::Cancel) => {
+                    self.password = None;
+                    Action::None
+                }
+                None => Action::None,
+            };
+        }
         if let Some(dialog) = &mut self.dialog {
             let mut cmd = dialog.handle(event.clone());
             if cmd.is_none()
@@ -372,6 +455,11 @@ impl Settings {
             Cmd::Change => match self.options(self.field()) {
                 // A few options: no need to ask, just go to the next.
                 Some((options, current)) => self.choose((current + 1) % options.len()),
+                None if self.field() == Field::Password => {
+                    self.error = None;
+                    self.password = Some(ChangePassword::default());
+                    Action::None
+                }
                 None => {
                     self.dialog = Some(self.dialog_for(self.field()));
                     Action::None
@@ -396,7 +484,7 @@ impl Settings {
                             return Action::None;
                         }
                     },
-                    Field::Styling | Field::NerdFont | Field::TouchId => {}
+                    Field::Styling | Field::NerdFont | Field::TouchId | Field::Password => {}
                 }
                 self.save(values)
             }
@@ -452,8 +540,8 @@ impl Settings {
                 .with_input("68", 3)
                 .with_text(&self.values.line_width.to_string())
             }
-            Field::Styling | Field::NerdFont | Field::TouchId => {
-                unreachable!("switched, not asked")
+            Field::Styling | Field::NerdFont | Field::TouchId | Field::Password => {
+                unreachable!("switched, not asked here")
             }
         }
     }
diff --git a/src/tui/setup.rs b/src/tui/setup.rs
index fca9a22..06be4e7 100644
--- a/src/tui/setup.rs
+++ b/src/tui/setup.rs
@@ -13,11 +13,10 @@ use ratatui::widgets::Paragraph;
 use super::Action;
 use super::hints::{HintBar, hint};
 use super::widgets::{
-    COLUMN_WIDTH, PASSWORD_BOX, PasswordField, centered, dev_password_note, overview, title,
-    truncate,
+    COLUMN_WIDTH, MIN_PASSWORD_LEN, PASSWORD_BOX, PasswordField, centered, dev_password_note,
+    overview, title, truncate,
 };
 
-const MIN_PASSWORD_LEN: usize = 8;
 const LABELS: [&str; 2] = ["Password", "Confirm password"];
 
 #[derive(Clone, Copy)]
diff --git a/src/tui/widgets.rs b/src/tui/widgets.rs
index bf2331f..d808537 100644
--- a/src/tui/widgets.rs
+++ b/src/tui/widgets.rs
@@ -12,6 +12,9 @@ use zeroize::Zeroizing;
 /// The comfortable reading/writing width, in columns.
 pub const COLUMN_WIDTH: u16 = 68;
 
+/// The shortest password a vault can have.
+pub const MIN_PASSWORD_LEN: usize = 8;
+
 /// A boxed password field: wide enough for a long password, and two fit
 /// side by side in the column.
 pub const PASSWORD_BOX: (u16, u16) = (33, 3);
diff --git a/src/vault/migrations.rs b/src/vault/migrations.rs
index 86f308a..69e5217 100644
--- a/src/vault/migrations.rs
+++ b/src/vault/migrations.rs
@@ -78,7 +78,7 @@ fn run_list(
         // A brand new vault: nothing to back up or check.
         return apply(conn, migrations, current);
     }
-    let backup = backup(path, current)?;
+    let backup = backup(path, &format!("v{current}"))?;
     match apply(conn, migrations, current).and_then(|()| verify(conn)) {
         Ok(()) => {
             // Not worth failing over: the vault itself is fine.
@@ -104,7 +104,7 @@ fn apply(conn: &mut Connection, migrations: &[&str], current: usize) -> Result<(
 
 /// SQLCipher's check that every page decrypts and is untampered (no rows
 /// when all is well), then SQLite's own structural check (a single "ok").
-fn verify(conn: &Connection) -> Result<()> {
+pub(super) fn verify(conn: &Connection) -> Result<()> {
     let cipher = pragma_rows(conn, "PRAGMA cipher_integrity_check")?;
     if !cipher.is_empty() {
         bail!("the vault failed its encryption check: {}", cipher.join("; "));
@@ -122,12 +122,12 @@ fn pragma_rows(conn: &Connection, sql: &str) -> Result<Vec<String>> {
     Ok(rows.collect::<rusqlite::Result<_>>()?)
 }
 
-/// Copy the (still encrypted) vault file next to itself, e.g.
-/// `writui.db.v1-20261003-142501.bak`.
-fn backup(path: &Path, version: usize) -> Result<PathBuf> {
+/// Copy the (still encrypted) vault file next to itself, named for what
+/// it's backed up before, e.g. `writui.db.v1-20261003-142501.bak`.
+pub(super) fn backup(path: &Path, before: &str) -> Result<PathBuf> {
     let stamp = jiff::Zoned::now().strftime("%Y%m%d-%H%M%S");
     let name = path.file_name().context("vault path has no file name")?;
-    let backup = path.with_file_name(format!("{}.v{version}-{stamp}.bak", name.to_string_lossy()));
+    let backup = path.with_file_name(format!("{}.{before}-{stamp}.bak", name.to_string_lossy()));
     fs::copy(path, &backup).with_context(|| format!("backing up vault to {}", backup.display()))?;
     Ok(backup)
 }
diff --git a/src/vault/mod.rs b/src/vault/mod.rs
index 661f85b..4a04bc9 100644
--- a/src/vault/mod.rs
+++ b/src/vault/mod.rs
@@ -6,7 +6,8 @@
 //! to produce a 256-bit key, which is handed to SQLCipher as a raw key along
 //! with the salt. SQLCipher stores that salt in the first 16 bytes of the
 //! file, so the vault stays a single self-contained file. The key itself
-//! can also open the vault (Touch ID keeps it, see `touch_id`).
+//! can also open the vault (Touch ID keeps it, see `touch_id`). Changing
+//! the password re-encrypts the file in place with a new salt and key.
 
 mod migrations;
 
@@ -18,7 +19,9 @@ use std::path::{Path, PathBuf};
 use anyhow::{Context, Result, anyhow, bail};
 use argon2::{Algorithm, Argon2, Params};
 use jiff::Timestamp;
+use rusqlite::types::ValueRef;
 use rusqlite::{Connection, ErrorCode, OpenFlags, OptionalExtension, params};
+use sha2::{Digest, Sha256};
 use zeroize::Zeroizing;
 
 const SALT_LEN: usize = 16;
@@ -41,6 +44,7 @@ pub const TITLE_PREFIX: &str = "# ";
 pub const DELETED_RETENTION_DAYS: i64 = 30;
 
 pub struct Vault {
+    path: PathBuf,
     conn: Connection,
     /// Kept while the vault is open, so Touch ID can be turned on without
     /// asking for the password again. (SQLCipher holds a copy anyway.)
@@ -76,6 +80,19 @@ impl From<rusqlite::Error> for OpenError {
     }
 }
 
+/// Why the password wasn't changed.
+#[derive(Debug)]
+pub enum ChangeError {
+    /// The current password given isn't the vault's.
+    WrongPassword,
+    /// Something went wrong, but the vault is as it was: the old password
+    /// still opens it.
+    Unchanged(anyhow::Error),
+    /// Something went wrong and the vault couldn't be put back as it was;
+    /// the error says where the backup is. The vault is closed.
+    Broken(anyhow::Error),
+}
+
 #[derive(Debug, Clone)]
 pub struct PostSummary {
     pub id: i64,
@@ -194,7 +211,7 @@ impl Vault {
         let key = derive_key(password, &salt)?;
         apply_key(&conn, &key, &salt)?;
         migrations::run(&mut conn, path)?;
-        Ok(Vault { conn, key })
+        Ok(Vault { path: path.to_path_buf(), conn, key })
     }
 
     /// Open an existing vault with its password.
@@ -206,19 +223,9 @@ impl Vault {
     /// Open an existing vault with its key, rather than the password the
     /// key comes from. A key that doesn't fit is a wrong password.
     pub fn open_with_key(path: &Path, key: Key) -> Result<Vault, OpenError> {
-        let salt = read_salt(path)?;
-        let mut conn = Connection::open_with_flags(path, OpenFlags::SQLITE_OPEN_READ_WRITE)?;
-        apply_key(&conn, &key, &salt)?;
-        // SQLCipher only notices a wrong key on the first real read.
-        match conn.query_row("SELECT count(*) FROM sqlite_master", [], |_| Ok(())) {
-            Ok(()) => {}
-            Err(rusqlite::Error::SqliteFailure(err, _)) if err.code == ErrorCode::NotADatabase => {
-                return Err(OpenError::WrongPassword);
-            }
-            Err(err) => return Err(err.into()),
-        }
+        let mut conn = connect(path, &key)?;
         migrations::run(&mut conn, path)?;
-        let vault = Vault { conn, key };
+        let vault = Vault { path: path.to_path_buf(), conn, key };
         vault.purge_expired()?;
         Ok(vault)
     }
@@ -228,6 +235,107 @@ impl Vault {
         &self.key
     }
 
+    /// Change the password from `current` to `new`: re-encrypt the vault in
+    /// place (SQLCipher's rekey) with a new random salt and the key `new`
+    /// makes with it. The file is backed up first, and the backup deleted
+    /// once the vault opens from scratch with `new`, passes its integrity
+    /// checks and holds just what it held before. If anything fails, the
+    /// vault is left (or put back from the backup) as it was. Gives back
+    /// the backup if it couldn't be deleted: the old password opens it.
+    pub fn change_password(
+        &mut self,
+        current: &str,
+        new: &str,
+    ) -> Result<Option<PathBuf>, ChangeError> {
+        self.change_password_checked(current, new, |_| Ok(()))
+    }
+
+    /// `change_password`, with `after_rekey` run on the vault's path right
+    /// after re-encrypting it (tests use it to make things go wrong).
+    fn change_password_checked(
+        &mut self,
+        current: &str,
+        new: &str,
+        after_rekey: impl FnOnce(&Path) -> Result<()>,
+    ) -> Result<Option<PathBuf>, ChangeError> {
+        let unchanged = ChangeError::Unchanged;
+        let old_salt = read_salt(&self.path).map_err(unchanged)?;
+        if derive_key(current, &old_salt).map_err(unchanged)? != self.key {
+            return Err(ChangeError::WrongPassword);
+        }
+        let mut new_salt = [0u8; SALT_LEN];
+        rand::fill(&mut new_salt);
+        let new_key = derive_key(new, &new_salt).map_err(unchanged)?;
+        let before = fingerprint(&self.conn).map_err(unchanged)?;
+        let backup = migrations::backup(&self.path, "password").map_err(unchanged)?;
+
+        let changed = rekey(&self.conn, &new_key, &new_salt)
+            .and_then(|()| after_rekey(&self.path))
+            .and_then(|()| {
+                // Just as unlocking will: the salt from the file, and the
+                // key from the new password.
+                let key = derive_key(new, &read_salt(&self.path)?)?;
+                let conn = connect(&self.path, &key).context("reopening with the new password")?;
+                check(&conn, &before)?;
+                Ok(conn)
+            });
+        // Close the vault as it was opened, before reopening it.
+        let old = std::mem::replace(&mut self.conn, closed());
+        drop(old);
+        match changed {
+            Ok(conn) => {
+                self.conn = conn;
+                self.key = new_key;
+                Ok(fs::remove_file(&backup).err().map(|_| backup))
+            }
+            Err(err) => match self.reopen_as_before(&old_salt, &backup, &before) {
+                Ok(conn) => {
+                    self.conn = conn;
+                    let _ = fs::remove_file(&backup);
+                    Err(ChangeError::Unchanged(err))
+                }
+                Err(restore_err) => Err(ChangeError::Broken(anyhow!(
+                    "{err:#}; putting the vault back failed too ({restore_err:#}). \
+                     A copy from before, which the old password opens, is at {}",
+                    backup.display()
+                ))),
+            },
+        }
+    }
+
+    /// After a failed password change: the vault opened as it was before,
+    /// with the old key. Either the change was undone (SQLCipher rolls a
+    /// failed rekey back), or the vault is put back from the backup.
+    fn reopen_as_before(
+        &self,
+        old_salt: &[u8; SALT_LEN],
+        backup: &Path,
+        before: &[u8],
+    ) -> Result<Connection> {
+        let as_before = || -> Result<Connection> {
+            if read_salt(&self.path)? != *old_salt {
+                bail!("the vault has a new salt");
+            }
+            let conn = connect(&self.path, &self.key)?;
+            check(&conn, before)?;
+            Ok(conn)
+        };
+        if let Ok(conn) = as_before() {
+            return Ok(conn);
+        }
+        // A journal left over is the failed change's, not the backup's.
+        let journal = self.path.with_file_name(format!(
+            "{}-journal",
+            self.path.file_name().context("vault path has no file name")?.to_string_lossy()
+        ));
+        if journal.exists() {
+            fs::remove_file(&journal).with_context(|| format!("removing {}", journal.display()))?;
+        }
+        fs::copy(backup, &self.path)
+            .with_context(|| format!("copying {} back", backup.display()))?;
+        as_before()
+    }
+
     /// All posts (not counting the Trash), most recently updated first.
     pub fn list_posts(&self) -> Result<Vec<PostSummary>> {
         self.summaries("deleted_at IS NULL ORDER BY updated_at DESC, id DESC")
@@ -623,17 +731,90 @@ fn derive_key(password: &str, salt: &[u8]) -> Result<Key> {
     Ok(key)
 }
 
+/// Open the vault at `path` with `key`. A key that doesn't fit is a wrong
+/// password.
+fn connect(path: &Path, key: &Key) -> Result<Connection, OpenError> {
+    let salt = read_salt(path)?;
+    let conn = Connection::open_with_flags(path, OpenFlags::SQLITE_OPEN_READ_WRITE)?;
+    apply_key(&conn, key, &salt)?;
+    // SQLCipher only notices a wrong key on the first real read.
+    match conn.query_row("SELECT count(*) FROM sqlite_master", [], |_| Ok(())) {
+        Ok(()) => Ok(conn),
+        Err(rusqlite::Error::SqliteFailure(err, _)) if err.code == ErrorCode::NotADatabase => {
+            Err(OpenError::WrongPassword)
+        }
+        Err(err) => Err(err.into()),
+    }
+}
+
+/// A connection to nothing, standing in for the vault while it's reopened.
+fn closed() -> Connection {
+    Connection::open_in_memory().expect("an in-memory database always opens")
+}
+
 fn apply_key(conn: &Connection, key: &Key, salt: &[u8; SALT_LEN]) -> Result<()> {
-    // Raw key + explicit salt: "x'<64 hex chars of key><32 hex chars of salt>'".
-    let pragma = Zeroizing::new(format!(
-        "PRAGMA key = \"x'{}{}'\";",
+    conn.execute_batch(&key_pragma("key", key, salt))?;
+    Ok(())
+}
+
+/// Re-encrypt the whole vault with `key` and `salt`, all or nothing.
+fn rekey(conn: &Connection, key: &Key, salt: &[u8; SALT_LEN]) -> Result<()> {
+    conn.execute_batch(&key_pragma("rekey", key, salt)).context("re-encrypting the vault")
+}
+
+/// `PRAGMA key` or `rekey` with a raw key and explicit salt:
+/// "x'<64 hex chars of key><32 hex chars of salt>'".
+fn key_pragma(pragma: &str, key: &Key, salt: &[u8; SALT_LEN]) -> Zeroizing<String> {
+    Zeroizing::new(format!(
+        "PRAGMA {pragma} = \"x'{}{}'\";",
         hex(key.as_ref()).as_str(),
         hex(salt).as_str()
-    ));
-    conn.execute_batch(&pragma)?;
+    ))
+}
+
+/// Check the vault opened by `conn` passes its integrity checks and holds
+/// just what it did when `before` was its fingerprint.
+fn check(conn: &Connection, before: &[u8]) -> Result<()> {
+    migrations::verify(conn)?;
+    if fingerprint(conn)? != before {
+        bail!("the vault doesn't hold what it did before");
+    }
     Ok(())
 }
 
+/// A digest of everything in the vault: its schema version and every row
+/// of every table.
+fn fingerprint(conn: &Connection) -> Result<Vec<u8>> {
+    let mut hasher = Sha256::new();
+    let version: i64 = conn.pragma_query_value(None, "user_version", |row| row.get(0))?;
+    hasher.update(version.to_le_bytes());
+    let tables: Vec<String> = conn
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name")?
+        .query_map([], |row| row.get(0))?
+        .collect::<rusqlite::Result<_>>()?;
+    for table in tables {
+        hasher.update(table.as_bytes());
+        let mut stmt = conn.prepare(&format!("SELECT * FROM \"{table}\" ORDER BY rowid"))?;
+        let columns = stmt.column_count();
+        let mut rows = stmt.query([])?;
+        while let Some(row) = rows.next()? {
+            for i in 0..columns {
+                let (tag, bytes) = match row.get_ref(i)? {
+                    ValueRef::Null => (0u8, Vec::new()),
+                    ValueRef::Integer(n) => (1, n.to_le_bytes().to_vec()),
+                    ValueRef::Real(x) => (2, x.to_le_bytes().to_vec()),
+                    ValueRef::Text(text) => (3, text.to_vec()),
+                    ValueRef::Blob(blob) => (4, blob.to_vec()),
+                };
+                hasher.update([tag]);
+                hasher.update((bytes.len() as u64).to_le_bytes());
+                hasher.update(&bytes);
+            }
+        }
+    }
+    Ok(hasher.finalize().to_vec())
+}
+
 fn hex(bytes: &[u8]) -> Zeroizing<String> {
     let mut out = Zeroizing::new(String::with_capacity(bytes.len() * 2));
     for byte in bytes {
@@ -1009,6 +1190,130 @@ mod tests {
         assert_eq!(vault.settings().unwrap().line_width, DEFAULT_LINE_WIDTH);
     }
 
+    /// A vault with a post, a version, an export and settings in it, and
+    /// its fingerprint.
+    fn full_vault(path: &Path) -> (Vault, Vec<u8>) {
+        let vault = Vault::create(path, "old password").unwrap();
+        let id = vault.create_post().unwrap();
+        vault.update_post_body(id, "# Dear diary\n\nToday I wrote.").unwrap();
+        vault.create_version(id, "First", "# Dear diary").unwrap();
+        let settings = Settings { author: "Ada".into(), ..Settings::default() };
+        vault.set_settings(&settings).unwrap();
+        let fingerprint = fingerprint(&vault.conn).unwrap();
+        (vault, fingerprint)
+    }
+
+    fn files(path: &Path) -> Vec<String> {
+        let mut names: Vec<_> = fs::read_dir(path.parent().unwrap())
+            .unwrap()
+            .map(|e| e.unwrap().file_name().into_string().unwrap())
+            .collect();
+        names.sort();
+        names
+    }
+
+    #[test]
+    fn changing_the_password_keeps_everything_and_the_old_one_stops_working() {
+        let (_dir, path) = temp_vault();
+        let (mut vault, before) = full_vault(&path);
+        let old_salt = read_salt(&path).unwrap();
+        let old_key = vault.key().clone();
+        assert_eq!(vault.change_password("old password", "new password").unwrap(), None);
+        // A new salt and key, and the open vault carries on with them.
+        assert_ne!(read_salt(&path).unwrap(), old_salt);
+        assert_ne!(vault.key(), &old_key);
+        assert_eq!(fingerprint(&vault.conn).unwrap(), before);
+        vault.update_post_body(1, "# Dear diary\n\nStill writing.").unwrap();
+        drop(vault);
+        // The backup is gone.
+        assert_eq!(files(&path), ["writui.db"]);
+        assert!(matches!(Vault::open(&path, "old password"), Err(OpenError::WrongPassword)));
+        assert!(matches!(Vault::open_with_key(&path, old_key), Err(OpenError::WrongPassword)));
+        let vault = Vault::open(&path, "new password").unwrap();
+        assert_eq!(vault.post(1).unwrap().body, "# Dear diary\n\nStill writing.");
+        assert_eq!(vault.list_versions(1).unwrap()[0].name, "First");
+        assert_eq!(vault.settings().unwrap().author, "Ada");
+        migrations::verify(&vault.conn).unwrap();
+    }
+
+    #[test]
+    fn a_wrong_current_password_changes_nothing() {
+        let (_dir, path) = temp_vault();
+        let (mut vault, before) = full_vault(&path);
+        let bytes = fs::read(&path).unwrap();
+        assert!(matches!(
+            vault.change_password("not it", "new password"),
+            Err(ChangeError::WrongPassword)
+        ));
+        assert_eq!(fs::read(&path).unwrap(), bytes);
+        assert_eq!(fingerprint(&vault.conn).unwrap(), before);
+        assert_eq!(files(&path), ["writui.db"]);
+    }
+
+    /// After a failed change: the old password opens the vault, which holds
+    /// what it did, the new one doesn't, and the backup is gone.
+    fn as_before(vault: Vault, path: &Path, before: &[u8]) {
+        assert_eq!(fingerprint(&vault.conn).unwrap(), before);
+        vault.update_post_body(1, "# Dear diary\n\nCarrying on.").unwrap();
+        drop(vault);
+        assert_eq!(files(path), ["writui.db"]);
+        assert!(matches!(Vault::open(path, "new password"), Err(OpenError::WrongPassword)));
+        let vault = Vault::open(path, "old password").unwrap();
+        assert_eq!(vault.post(1).unwrap().body, "# Dear diary\n\nCarrying on.");
+        migrations::verify(&vault.conn).unwrap();
+    }
+
+    #[test]
+    fn a_failed_check_after_the_change_puts_the_vault_back() {
+        let (_dir, path) = temp_vault();
+        let (mut vault, before) = full_vault(&path);
+        let old_key = vault.key().clone();
+        let err = vault
+            .change_password_checked("old password", "new password", |_| bail!("check failed"))
+            .unwrap_err();
+        let ChangeError::Unchanged(err) = err else { panic!("{err:?}") };
+        assert!(format!("{err:#}").contains("check failed"));
+        assert_eq!(vault.key(), &old_key);
+        as_before(vault, &path, &before);
+    }
+
+    #[test]
+    fn a_vault_damaged_by_the_change_is_put_back_from_the_backup() {
+        let (_dir, path) = temp_vault();
+        let (mut vault, before) = full_vault(&path);
+        let damage = |path: &Path| {
+            let mut bytes = fs::read(path)?;
+            bytes[4096 + 200] ^= 0xff;
+            fs::write(path, bytes)?;
+            Ok(())
+        };
+        let err = vault.change_password_checked("old password", "new password", damage);
+        assert!(matches!(err, Err(ChangeError::Unchanged(_))), "{err:?}");
+        as_before(vault, &path, &before);
+    }
+
+    #[test]
+    fn if_the_vault_cant_be_put_back_the_backup_is_kept() {
+        let (_dir, path) = temp_vault();
+        let (mut vault, _) = full_vault(&path);
+        // Damage the vault, and the backup too, so neither will do.
+        let damage = |path: &Path| {
+            for name in files(path) {
+                let file = path.with_file_name(name);
+                let mut bytes = fs::read(&file)?;
+                bytes[4096 + 200] ^= 0xff;
+                fs::write(&file, bytes)?;
+            }
+            Ok(())
+        };
+        let err = vault.change_password_checked("old password", "new password", damage);
+        let Err(ChangeError::Broken(err)) = err else { panic!("{err:?}") };
+        let backups: Vec<_> = files(&path).into_iter().filter(|n| n.ends_with(".bak")).collect();
+        assert_eq!(backups.len(), 1);
+        assert!(backups[0].starts_with("writui.db.password-"));
+        assert!(format!("{err:#}").contains(&backups[0]), "{err:#}");
+    }
+
     #[test]
     fn title_prefix_is_always_kept() {
         assert_eq!(with_title_prefix("# Hi"), "# Hi");