feat(backup): restore at first-run setup, restore --in-place, docs lead with the UI (#5818, #5819)

#5818 "First-run setup: Restore from a backup, by upload": beside creating
the first admin, setup offers "Or restore from a backup". Only while no
user exists; the upload is checked (a newer backup or one whose key can't
open its secrets is refused and not kept), then restored with no safety
backup (nothing to keep), and Steward restarts into the backup's users.

#5819 "Docs and CI": backups.md leads with restoring from Settings →
Backups and from setup; `steward restore --in-place` does the same-schema
restore from the shell, and CI's image check now uses it with a real
pg_restore: a changed setting comes back and the audit log stays.

Also exempts errors/restoring.html from the breadcrumb guard, as with
the other whole-app error pages: it replaces every page while a restore
runs, so there is nowhere to trail back to.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/test_auth.py

@@ -65,3 +65,71 @@ async def test_require_role_redirects_unauthenticated(client):
     response = await client.get("/")
     assert response.status_code == 302
     assert "/login" in response.headers["Location"]
+
+
+def _setup_restore_stubs(monkeypatch, tmp_path, schema="same", unopened=0):
+    """First-run setup's restore (#5818) with the check and the restore
+    stubbed: restoring.py and check.py have their own tests."""
+    from steward.backup import job, restoring
+    from steward.backup.check import AreaCheck, CheckReport, TableCheck
+    seen = []
+
+    async def check_file(app, path, name=""):
+        return CheckReport(name=name, manifest={}, schema=schema, backup_heads=[], here_heads=[],
+                           key_same=False, sealed=1, unopened=unopened,
+                           areas=[AreaCheck("Settings", [TableCheck("app_settings", same=0)])])
+
+    def start_restore(app, path, name, **kw):
+        seen.append({"name": name, "data": path.read_bytes()} | kw)
+        return True
+
+    monkeypatch.setattr(restoring, "SAFETY_DIR", tmp_path)
+    monkeypatch.setattr(job, "check_file", check_file)
+    monkeypatch.setattr(restoring, "start_restore", start_restore)
+    return seen
+
+
+async def _send_backup(client, name="steward-20261015T030000Z.tar"):
+    import io
+
+    from quart.datastructures import FileStorage
+    headers = await with_csrf(client)
+    return await client.post("/setup/restore", headers=headers, files={
+        "file": FileStorage(io.BytesIO(b"a backup"), filename=name)})
+
+
+@pytest.mark.asyncio
+async def test_setup_restores_a_backup_without_a_safety_backup(client, monkeypatch, tmp_path):
+    seen = _setup_restore_stubs(monkeypatch, tmp_path, schema="older")
+    with patch("steward.auth.routes.get_user_count", new=AsyncMock(return_value=0)):
+        response = await _send_backup(client)
+    assert response.status_code == 302 and response.headers["Location"].endswith("/setup")
+    [started] = seen
+    assert started["name"] == "steward-20261015T030000Z.tar" and started["data"] == b"a backup"
+    assert started["safety"] is False and started["replace_all"] is True
+    assert started["username"] == "first-run setup"
+
+
+@pytest.mark.asyncio
+async def test_setup_refuses_a_backup_it_cant_restore(client, monkeypatch, tmp_path):
+    seen = _setup_restore_stubs(monkeypatch, tmp_path, schema="newer")
+    with patch("steward.auth.routes.get_user_count", new=AsyncMock(return_value=0)):
+        response = await _send_backup(client)
+    assert response.status_code == 400 and not seen
+    assert "update Steward, then restore it" in await response.get_data(as_text=True)
+    assert not list((tmp_path / "incoming").iterdir())          # nothing left held
+
+
+@pytest.mark.asyncio
+async def test_setup_restore_is_gone_once_a_user_exists(client, monkeypatch, tmp_path):
+    seen = _setup_restore_stubs(monkeypatch, tmp_path)
+    with patch("steward.auth.routes.get_user_count", new=AsyncMock(return_value=1)):
+        response = await _send_backup(client)
+    assert response.status_code == 302 and "/login" in response.headers["Location"] and not seen
+
+
+@pytest.mark.asyncio
+async def test_setup_offers_a_restore(client):
+    with patch("steward.auth.routes.get_user_count", new=AsyncMock(return_value=0)):
+        page = await (await client.get("/setup")).get_data(as_text=True)
+    assert 'action="/setup/restore"' in page and 'enctype="multipart/form-data"' in page

tests/test_breadcrumbs.py

@@ -33,6 +33,7 @@ TOP_LEVEL = {
     "steward/templates/errors/404.html",
     "steward/templates/errors/500.html",
     "steward/templates/errors/database_unavailable.html",
+    "steward/templates/errors/restoring.html",
 }
 
 _EXTENDS_BASE = re.compile(r"""\{%-?\s*extends\s+["']base\.html["']""")