feat(backup): check a backup against what is in place, changing nothing (#5823)

#5823 "Check a backup: compare what it would restore with what is in
place, without restoring".

- steward/backup/check.py: pg_restore writes the backup's rows as COPY
  text with no database involved. The rows in place go out through COPY in
  the same form. Tables are compared on their primary keys, over the columns
  both sides have, and grouped by area.
- Sealed values are opened with each side's own key and compared as
  plaintext digests, so a secret sealed twice still matches. They are never
  shown. A backup whose key can't open its own secrets fails the check.
- What Steward records as it runs (last-seen times, a schedule's last run,
  backup history, scraped UniFi fields) is left out of the comparison:
  contents.ACTIVITY, STATE_SETTINGS and HAND_SET_ONLY.
- Settings → Backups:
  - a Check button on each sent backup, which fetches it from the bucket
    (new s3.get_file);
  - "Check a file" to upload one, with the size limit raised before the
    CSRF check reads the form;
  - a results page.
- Each backup Steward sends checks itself once written, and its history
  row says how that went.
- New CLI command `steward check-backup FILE`. CI's image smoke step checks a
  real backup against its source and expects a match.

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

steward/backup/job.py

@@ -22,7 +22,7 @@ from sqlalchemy import text
 from sqlalchemy.ext.asyncio import create_async_engine
 
 from .dump import BackupError, make_backup
-from .s3 import S3Error, S3Target, list_objects, put_file
+from .s3 import S3Error, S3Target, get_file, list_objects, put_file
 
 logger = logging.getLogger(__name__)
 
@@ -133,7 +133,8 @@ async def run_backup(app, by: str = "schedule", user_id: str | None = None) -> d
             with tempfile.TemporaryDirectory(prefix="steward-backup-") as tmp:
                 made = await make_backup(db_url, app.config["SECRET_KEY"], heads, Path(tmp), now=at)
                 await put_file(target, made.name, made.path)
-            entry.update(ok=True, name=made.name, size=made.size)
+                entry.update(ok=True, name=made.name, size=made.size)
+                entry["check"] = await _self_check(app, made.path, made.name)
         except (BackupError, S3Error) as exc:
             entry["error"] = str(exc)
         except Exception as exc:     # recorded and logged: a run never takes the scheduler down
@@ -148,6 +149,49 @@ async def run_backup(app, by: str = "schedule", user_id: str | None = None) -> d
         return entry
 
 
+async def _self_check(app, path: Path, name: str) -> dict:
+    """A backup just sent, read back and compared with what it was made from
+    (#5823): proof the file restores, kept on its history row. A check that
+    can't run says why; the backup was sent either way."""
+    try:
+        report = await check_file(app, path, name)
+    except Exception as exc:
+        logger.warning("Backup %s couldn't be checked: %s", name, exc)
+        return {"ok": False, "changes": 0, "rows": 0, "summary": f"Couldn't check it: {exc}"}
+    return report.as_entry()
+
+
+async def check_file(app, path: Path, name: str = ""):
+    """Compare a backup file with this Steward's database (check.py)."""
+    from .check import check_backup
+    return await check_backup(path, app.config["DATABASE_URL"], app.config["SECRET_KEY"],
+                              plugin_dirs=[Path(d) for d in app.config["PLUGIN_DIRS"]],
+                              name=name or path.name)
+
+
+def is_backup_name(name: str) -> bool:
+    """A file name Steward's backups have, and nothing else: no path, no
+    other object in the bucket."""
+    import re
+    return bool(re.fullmatch(r"steward-\d{8}T\d{6}Z\.tar", name or ""))
+
+
+async def check_stored(app, name: str):
+    """Fetch one of this Steward's backups from the bucket and check it.
+    Raises BackupError or S3Error with what went wrong."""
+    from steward.core.settings import get_all_settings
+    if not is_backup_name(name):
+        raise BackupError(f"{name!r} isn't the name of a Steward backup.")
+    async with app.db_sessionmaker() as db:
+        target = target_from(await get_all_settings(db))
+    if target is None:
+        raise BackupError("The bucket isn't set up: fill in the endpoint, bucket and keys.")
+    with tempfile.TemporaryDirectory(prefix="steward-check-") as tmp:
+        path = Path(tmp) / name
+        await get_file(target, name, path)
+        return await check_file(app, path, name)
+
+
 def start_backup(app, by: str, user_id: str | None) -> bool:
     """Start a backup in the background for a person; False if one is running."""
     if _running.locked():