feat(523): backup destinations - a folder or an S3 bucket, with the S3 secret sealed and kept out of backups

services/backup_s3.py is FabledSteward's SigV4 client ported (put + list,
never delete, so an append-only key is enough), with its tests against
AWS's published signatures. services/backup_destination.py holds the
admin config (backup_config JSON) and delivers a dated tar to a mounted
folder or a bucket, and checks either without sending a backup.
services/secrets.py seals the S3 secret with Fernet under a key derived
from SECRET_KEY; backup._SETTINGS_NOT_EXPORTED keeps it out of every
backup. cryptography becomes a direct dependency (already in the image
through pyjwt).

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

src/scribe/services/backup_destination.py

@@ -0,0 +1,235 @@
+"""Where the scheduled backup goes, and getting a backup file there.
+
+Two kinds of destination, both instance-wide and set by an admin:
+
+- **folder**: a directory inside the container, usually a mounted share. A
+  backup service that watches the share (or a person) takes it from there.
+- **s3**: any S3-compatible bucket, addressed by path. Scribe only puts and
+  lists, so an append-only key is enough.
+
+Either way Scribe ADDS one dated file per run and never removes one: keeping
+and thinning the history is the destination's job (services/backup_file.py
+says why the file is shaped the way it is for that).
+
+The settings live as admin settings: `backup_config` holds everything but the
+S3 secret as JSON, and `backup_s3_secret` holds the secret sealed under the
+instance's SECRET_KEY (services/secrets.py). The secret is also kept out of
+every backup (backup._SETTINGS_NOT_EXPORTED), so a backup copied off-site
+does not carry the key that writes to that very place.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import tempfile
+from dataclasses import asdict, dataclass, fields, replace
+from datetime import datetime
+from pathlib import Path
+
+from scribe.services import backup_file
+from scribe.services.backup_s3 import S3Error, S3Target, list_objects, put_file
+from scribe.services.secrets import seal, unseal
+from scribe.services.settings import get_admin_setting, set_admin_setting
+
+CONFIG_SETTING = "backup_config"
+SECRET_SETTING = "backup_s3_secret"
+DESTINATION_KINDS = ("folder", "s3")
+DEFAULT_FOLDER = "/backups"
+# 02:00 UTC: before the 03:30 trash purge and the 04:00 DB maintenance, so the
+# backup never contends with a VACUUM, and the night's deletions are still
+# recoverable from the backup taken just before them.
+DEFAULT_HOUR = 2
+
+
+class DestinationError(Exception):
+    """Why the destination can't take a backup, said to the person."""
+
+
+@dataclass(frozen=True)
+class BackupConfig:
+    enabled: bool = False
+    hour: int = DEFAULT_HOUR
+    destination: str = "folder"
+    folder_path: str = DEFAULT_FOLDER
+    s3_endpoint: str = ""
+    s3_bucket: str = ""
+    s3_access_key: str = ""
+    s3_region: str = "us-east-1"
+    s3_verify_tls: bool = True
+
+    @classmethod
+    def from_dict(cls, raw: dict) -> "BackupConfig":
+        """Lenient: unknown keys are ignored and bad values fall back to the
+        default, so an edited or older stored config still loads."""
+        known = {f.name: f for f in fields(cls)}
+        values = {}
+        for name, value in (raw or {}).items():
+            f = known.get(name)
+            if f is None:
+                continue
+            default = f.default
+            if isinstance(default, bool):
+                values[name] = value if isinstance(value, bool) else default
+            elif isinstance(default, int):
+                try:
+                    values[name] = int(value)
+                except (TypeError, ValueError):
+                    values[name] = default
+            else:
+                values[name] = str(value).strip() if value is not None else default
+        config = cls(**values)
+        if not 0 <= config.hour <= 23:
+            config = replace(config, hour=DEFAULT_HOUR)
+        if config.destination not in DESTINATION_KINDS:
+            config = replace(config, destination="folder")
+        return config
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def problems(self, *, has_secret: bool) -> list[str]:
+        """What stops this config from sending a backup, in words. Empty when
+        it is complete (which says nothing about whether the place answers —
+        check_destination does that)."""
+        out: list[str] = []
+        if self.destination == "folder":
+            if not self.folder_path.startswith("/"):
+                out.append("The folder must be an absolute path inside the container.")
+        else:
+            if not self.s3_endpoint.startswith(("http://", "https://")):
+                out.append("The S3 address must start with http:// or https://.")
+            if not self.s3_bucket:
+                out.append("The bucket name is missing.")
+            if not self.s3_access_key:
+                out.append("The access key is missing.")
+            if not has_secret:
+                out.append("The secret key is missing.")
+        return out
+
+
+async def load_config() -> BackupConfig:
+    raw = await get_admin_setting(CONFIG_SETTING, "")
+    try:
+        data = json.loads(raw) if raw else {}
+    except ValueError:
+        data = {}
+    return BackupConfig.from_dict(data if isinstance(data, dict) else {})
+
+
+async def save_config(config: BackupConfig) -> None:
+    await set_admin_setting(CONFIG_SETTING, json.dumps(config.to_dict(), sort_keys=True))
+
+
+async def load_secret() -> tuple[str | None, bool]:
+    """(the S3 secret or None, whether one is stored).
+
+    Stored but None means it was sealed under another SECRET_KEY — after a
+    restore onto a different instance, say — and has to be entered again.
+    """
+    stored = await get_admin_setting(SECRET_SETTING, "")
+    return (unseal(stored), bool(stored))
+
+
+async def save_secret(secret: str) -> None:
+    await set_admin_setting(SECRET_SETTING, seal(secret) if secret else "")
+
+
+def s3_target(config: BackupConfig, secret: str) -> S3Target:
+    return S3Target(
+        endpoint=config.s3_endpoint, bucket=config.s3_bucket,
+        access_key=config.s3_access_key, secret_key=secret,
+        region=config.s3_region or "us-east-1", verify_tls=config.s3_verify_tls,
+    )
+
+
+@dataclass(frozen=True)
+class Delivered:
+    name: str
+    size_bytes: int
+    where: str
+
+
+async def deliver(
+    payload: dict, config: BackupConfig, secret: str | None, at: datetime,
+    *, app_version: str, transport=None,
+) -> Delivered:
+    """Write `payload` as the dated backup file and put it at the destination.
+
+    The file is written off the event loop: serialising a full export is
+    seconds of CPU on a large corpus, and the app keeps serving meanwhile.
+    """
+    problems = config.problems(has_secret=bool(secret))
+    if problems:
+        raise DestinationError(" ".join(problems))
+
+    if config.destination == "folder":
+        folder = Path(config.folder_path)
+        if not folder.is_dir():
+            raise DestinationError(
+                f"{folder} isn't there. Mount the backup share at that path, "
+                "or choose the folder it is mounted at."
+            )
+        try:
+            path = await asyncio.to_thread(
+                backup_file.write_archive, payload, folder, at, app_version=app_version,
+            )
+        except PermissionError:
+            raise DestinationError(f"Scribe isn't allowed to write in {folder}.") from None
+        return Delivered(path.name, path.stat().st_size, str(folder))
+
+    target = s3_target(config, secret or "")
+    with tempfile.TemporaryDirectory(prefix="scribe-backup-") as staging:
+        path = await asyncio.to_thread(
+            backup_file.write_archive, payload, Path(staging), at, app_version=app_version,
+        )
+        size = path.stat().st_size
+        try:
+            await put_file(target, path.name, path, transport=transport)
+        except S3Error as exc:
+            raise DestinationError(str(exc)) from None
+    return Delivered(path.name, size, target.url())
+
+
+async def check_destination(
+    config: BackupConfig, secret: str | None, *, transport=None,
+) -> str:
+    """Ask the destination whether it would take a backup, without sending
+    one. Returns what was found, in words; raises DestinationError otherwise.
+
+    The folder check writes and removes a dot-file, which a folder watcher
+    ignores. The S3 check only lists: an append-only key could add a test
+    object and then never remove it.
+    """
+    problems = config.problems(has_secret=bool(secret))
+    if problems:
+        raise DestinationError(" ".join(problems))
+
+    if config.destination == "folder":
+        folder = Path(config.folder_path)
+        if not folder.is_dir():
+            raise DestinationError(f"{folder} isn't there, or isn't a folder.")
+        probe = folder / ".scribe-write-check"
+        try:
+            await asyncio.to_thread(probe.write_bytes, b"")
+            await asyncio.to_thread(probe.unlink)
+        except PermissionError:
+            raise DestinationError(f"Scribe isn't allowed to write in {folder}.") from None
+        except OSError as exc:
+            raise DestinationError(f"Writing in {folder} failed: {exc.strerror or exc}.") from None
+        count = await asyncio.to_thread(_count_backups, folder)
+        return f"{folder} is writable and holds {count} Scribe backup(s)."
+
+    target = s3_target(config, secret or "")
+    try:
+        objects = await list_objects(target, backup_file.NAME_PREFIX, transport=transport)
+    except S3Error as exc:
+        raise DestinationError(str(exc)) from None
+    return f"Bucket {config.s3_bucket} answered and holds {len(objects)} Scribe backup(s)."
+
+
+def _count_backups(folder: Path) -> int:
+    return sum(
+        1 for name in os.listdir(folder)
+        if name.startswith(backup_file.NAME_PREFIX) and name.endswith(backup_file.NAME_SUFFIX)
+    )