vvz-file-backup 0.1.1__py3-none-any.whl

file_backup/__init__.py

@@ -0,0 +1,60 @@
+"""Independent backup, saved-point inspection, verification, and restore API."""
+
+from .api.backup import Backup
+from .api.list_points import ListPoints
+from .api.inspect_point import InspectPoint
+from .api.list_files import ListFiles
+from .api.restore import Restore
+from .api.restore_file import RestoreFile
+from .api.verify import Verify
+from .api.recover_catalog import RecoverCatalog
+from .api.help import Help
+from .api.info import Info
+from ._configuration import DEFAULT_CATALOG_DIRECTORY
+from .errors import FileBackupError, ArgumentError, PointNotFoundError, FileNotFoundError, ArchiveMissingError, ArchiveCorruptError, ChainError, BackupIOError, CatalogError, ConflictError, SourceChangedError, SectionNotFoundError, CommandNotFoundError
+from .types import BackupCreated, BackupUnchanged, BackupPreview, PointInfo, PointList, FileList, RestoreResult, FileRestoreResult, RestorePreview, FileRestorePreview, VerificationReport, CatalogRecoveryResult, CatalogRecoveryPreview, HelpPage, InfoTOC, InfoSection, CLIResult, CLIError
+
+__all__ = [
+    'DEFAULT_CATALOG_DIRECTORY',
+    'Backup',
+    'ListPoints',
+    'InspectPoint',
+    'ListFiles',
+    'Restore',
+    'RestoreFile',
+    'Verify',
+    'RecoverCatalog',
+    'Help',
+    'Info',
+    'FileBackupError',
+    'ArgumentError',
+    'PointNotFoundError',
+    'FileNotFoundError',
+    'ArchiveMissingError',
+    'ArchiveCorruptError',
+    'ChainError',
+    'BackupIOError',
+    'CatalogError',
+    'ConflictError',
+    'SourceChangedError',
+    'SectionNotFoundError',
+    'CommandNotFoundError',
+    'BackupCreated',
+    'BackupUnchanged',
+    'BackupPreview',
+    'PointInfo',
+    'PointList',
+    'FileList',
+    'RestoreResult',
+    'FileRestoreResult',
+    'RestorePreview',
+    'FileRestorePreview',
+    'VerificationReport',
+    'CatalogRecoveryResult',
+    'CatalogRecoveryPreview',
+    'HelpPage',
+    'InfoTOC',
+    'InfoSection',
+    'CLIResult',
+    'CLIError',
+]

file_backup/_archives.py

@@ -0,0 +1,100 @@
+"""Archive creation and strict catalog-bound integrity checks."""
+import hashlib
+import io
+import json
+from pathlib import Path
+import tarfile
+
+from ._validation import relative_path, safe_absolute
+from .errors import ArchiveMissingError, ArchiveCorruptError, BackupIOError
+
+
+def digest(data):
+    return hashlib.sha256(data).hexdigest()
+
+
+def encode(manifest):
+    return json.dumps(manifest, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def create(path, manifest, content):
+    with tarfile.open(path, "w:gz") as archive:
+        for name, data in [("manifest.json", encode(manifest)), *[("files/" + n, b) for n, b in sorted(content.items())]]:
+            member = tarfile.TarInfo(name)
+            member.size = len(data)
+            archive.addfile(member, io.BytesIO(data))
+
+
+def read(repository, row, identity, operation):
+    relative = row["archive"]
+    path = Path(repository) / relative
+    context = dict(operation=operation, point=row["point"], archive=str(path))
+    if not relative_path(relative) or relative != f"archives/{row['point']}.tar.gz" or not safe_absolute(str(path)):
+        raise ArchiveCorruptError("Unsafe archive path", expected="safe archive", got=relative, **context)
+    try:
+        data = path.read_bytes()
+    except FileNotFoundError as cause:
+        raise ArchiveMissingError("Required archive missing", **context) from cause
+    except OSError as cause:
+        raise BackupIOError("Cannot read archive", operation=operation, path=str(path), phase="read") from cause
+    actual = digest(data)
+    if actual != row["archive_sha256"]:
+        raise ArchiveCorruptError("Archive checksum mismatch", expected=row["archive_sha256"], got=actual, **context)
+    try:
+        content = {}
+        with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as archive:
+            names = set()
+            for member in archive:
+                if member.name in names or not member.isfile() or not relative_path(member.name):
+                    raise ValueError("unsafe or duplicate archive member")
+                names.add(member.name)
+                handle = archive.extractfile(member)
+                payload = handle.read()
+                if member.name == "manifest.json":
+                    manifest = json.loads(payload)
+                elif member.name.startswith("files/") and relative_path(member.name[6:]):
+                    content[member.name[6:]] = payload
+                else:
+                    raise ValueError("unexpected member")
+            if "manifest.json" not in names:
+                raise ValueError("missing manifest")
+        if manifest != row["manifest"] or manifest["repository"] != identity:
+            raise ValueError("manifest/catalog binding mismatch")
+        for field in ("point", "kind", "base_point", "previous_point", "snapshot_at", "completed_at"):
+            if manifest[field] != row[field]:
+                raise ValueError("manifest point binding mismatch")
+        changed = manifest["changed"]
+        if len(changed) != len(set(changed)) or set(changed) != set(content):
+            raise ValueError("archive member set mismatch")
+        for name, item in manifest["files"].items():
+            if not relative_path(name) or item["size"] < 0 or item["version"] != item["sha256"]:
+                raise ValueError("invalid file manifest")
+        for name, payload in content.items():
+            item = manifest["files"][name]
+            if digest(payload) != item["sha256"] or len(payload) != item["size"]:
+                raise ValueError("file integrity mismatch")
+        if len(manifest["deleted"]) != len(set(manifest["deleted"])) or any(not relative_path(n) or n in manifest["files"] for n in manifest["deleted"]):
+            raise ValueError("invalid tombstones")
+        return content
+    except (tarfile.TarError, OSError, ValueError, KeyError, TypeError, UnboundLocalError) as cause:
+        raise ArchiveCorruptError("Invalid archive or manifest", expected="catalog-bound safe archive", got=str(cause), **context) from cause
+
+
+def materialize(repository, chain, identity, operation):
+    live = {}
+    for row in chain:
+        updates = read(repository, row, identity, operation)
+        manifest = row["manifest"]
+        if row["kind"] == "full":
+            live = {}
+        for name in manifest["deleted"]:
+            if name not in live:
+                raise ArchiveCorruptError("Tombstone has no prior file", operation=operation, point=row["point"],
+                                          archive=row["archive"], expected="live prior path", got=name)
+            del live[name]
+        live.update(updates)
+        expected = manifest["files"]
+        if set(live) != set(expected) or any(digest(payload) != expected[name]["sha256"] or len(payload) != expected[name]["size"] for name, payload in live.items()):
+            raise ArchiveCorruptError("Saved slice does not match manifest", operation=operation, point=row["point"],
+                                      archive=row["archive"], expected="exact slice", got="mismatch")
+    return live

file_backup/_catalog.py

@@ -0,0 +1,87 @@
+"""SQLite saved-point catalog and exact chain selection."""
+import json
+from pathlib import Path
+import sqlite3
+
+from .errors import CatalogError, ChainError, PointNotFoundError
+from .types import PointInfo
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS repository (identity TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS points (
+ sequence INTEGER PRIMARY KEY, point TEXT UNIQUE NOT NULL,
+ kind TEXT NOT NULL, base_point TEXT NOT NULL, previous_point TEXT,
+ snapshot_at TEXT NOT NULL, completed_at TEXT NOT NULL,
+ archive TEXT NOT NULL, archive_sha256 TEXT NOT NULL, manifest TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS checkpoint (point TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS objects (path TEXT PRIMARY KEY);
+CREATE TABLE IF NOT EXISTS content_versions (sha256 TEXT PRIMARY KEY, size INTEGER NOT NULL);
+CREATE TABLE IF NOT EXISTS archives (point TEXT PRIMARY KEY, file TEXT NOT NULL, digest TEXT NOT NULL, kind TEXT NOT NULL, state TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS chains (point TEXT PRIMARY KEY, base_point TEXT NOT NULL, previous_point TEXT);
+CREATE TABLE IF NOT EXISTS point_members (point TEXT NOT NULL, path TEXT NOT NULL, sha256 TEXT NOT NULL, archive TEXT NOT NULL, PRIMARY KEY(point,path));
+CREATE TABLE IF NOT EXISTS tombstones (point TEXT NOT NULL, path TEXT NOT NULL, PRIMARY KEY(point,path));
+"""
+
+
+def load(repository, operation, catalog=None):
+    catalog = Path(catalog) if catalog else Path(repository) / "catalog.sqlite3"
+    if catalog.is_symlink():
+        raise CatalogError("Catalog must not be a symlink", operation=operation, catalog=str(catalog), phase="open")
+    if not catalog.exists():
+        archives = Path(repository) / "archives"
+        if archives.exists() and any(archives.glob("*.tar.gz")):
+            raise CatalogError("Catalog missing while archives exist", operation=operation,
+                               catalog=str(catalog), phase="open")
+        return None, []
+    try:
+        with sqlite3.connect(catalog.as_uri() + "?mode=ro", uri=True) as connection:
+            connection.row_factory = sqlite3.Row
+            if connection.execute("PRAGMA integrity_check").fetchone()[0] != "ok":
+                raise sqlite3.DatabaseError("catalog integrity check failed")
+            identity = connection.execute("SELECT identity FROM repository").fetchone()[0]
+            points = []
+            for row in connection.execute("SELECT * FROM points ORDER BY sequence"):
+                point = dict(row)
+                point["manifest"] = json.loads(point["manifest"])
+                points.append(point)
+            checkpoint = connection.execute("SELECT point FROM checkpoint").fetchall()
+            missing_base_rebootstrap = operation == "backup" and not points and len(checkpoint) == 1
+            if not missing_base_rebootstrap and (len(checkpoint) != bool(points) or points and checkpoint[0][0] != points[-1]["point"]):
+                raise sqlite3.DatabaseError("checkpoint does not match last committed point")
+            return identity, points
+    except (sqlite3.Error, ValueError, KeyError, IndexError, TypeError) as cause:
+        raise CatalogError("Cannot read catalog", operation=operation, catalog=str(catalog), phase="read") from cause
+
+
+def chain(points, point, operation):
+    by_id = {row["point"]: row for row in points}
+    if point not in by_id:
+        raise PointNotFoundError("Saved point not found", operation=operation, point=point)
+    result, seen = [], set()
+    selected = by_id[point]
+    current = selected
+    while True:
+        identifier = current["point"]
+        if identifier in seen:
+            raise ChainError("Cyclic saved-point chain", operation=operation, point=point, missing_dependency=identifier)
+        seen.add(identifier)
+        result.append(current)
+        if current["kind"] == "full":
+            if current["base_point"] != identifier or current["previous_point"] is not None or selected["base_point"] != identifier:
+                raise ChainError("Invalid full base", operation=operation, point=point, missing_dependency=identifier)
+            return list(reversed(result))
+        previous = by_id.get(current["previous_point"])
+        if (current["kind"] != "incremental" or previous is None
+                or previous["sequence"] >= current["sequence"]
+                or previous["base_point"] != current["base_point"]):
+            raise ChainError("Missing or unordered dependency", operation=operation, point=point,
+                             missing_dependency=current["previous_point"])
+        current = previous
+
+
+def info(points, row, operation):
+    members = row["manifest"]["files"]
+    return PointInfo(row["point"], row["kind"], row["base_point"], row["previous_point"],
+                     row["snapshot_at"], row["completed_at"], row["archive"], row["archive_sha256"],
+                     tuple(item["point"] for item in chain(points, row["point"], operation)),
+                     len(members), len(row["manifest"]["deleted"]))

file_backup/_configuration.py

@@ -0,0 +1,40 @@
+"""Explicit catalog directory selection without ambient configuration."""
+from collections.abc import Mapping
+import os
+from pathlib import Path
+
+from ._validation import invalid
+
+DEFAULT_CATALOG_DIRECTORY = "."
+
+
+def directory(repository, value, operation, parameter):
+    if type(value) is not str:
+        invalid(operation, parameter, "type", "nonempty directory string", value)
+    if not value or "\0" in value:
+        invalid(operation, parameter, "value", "nonempty NUL-free directory", value)
+    raw = Path(repository) / value
+    # Check lexical components before normalizing .. away.
+    for part in (raw, *raw.parents):
+        if part.is_symlink() or part.exists() and not part.is_dir():
+            invalid(operation, parameter, "value", "directory without symlink components", value)
+    return Path(os.path.abspath(raw))
+
+
+def resolve_catalog(repository, catalog_directory, config, operation):
+    if config is not None and not isinstance(config, Mapping):
+        invalid(operation, "config", "type", "mapping or None", config)
+    settings = {} if config is None else config
+    for key in settings:
+        if type(key) is not str or key != "catalog_directory":
+            invalid(operation, "config", "unknown", ["catalog_directory"], key)
+    configured = None
+    if "catalog_directory" in settings:
+        configured = directory(repository, settings["catalog_directory"], operation, "config.catalog_directory")
+    explicit = None
+    if catalog_directory is not None:
+        explicit = directory(repository, catalog_directory, operation, "catalog_directory")
+    selected = explicit if explicit is not None else configured
+    if selected is None:
+        selected = directory(repository, DEFAULT_CATALOG_DIRECTORY, operation, "catalog_directory")
+    return selected / "catalog.sqlite3"

file_backup/_namespace.py

@@ -0,0 +1,16 @@
+"""Internal namespace base for classmethod-only operations."""
+
+from ._resources import resource
+
+class _OperationNamespace:
+    """Operation declarations cannot be instantiated."""
+    def __new__(cls, *args: object, **kwargs: object) -> object:
+        raise TypeError("operation namespaces cannot be instantiated")
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        declaration = resource(cls.__module__.rsplit(".", 1)[-1], "metadata.json")
+        for attribute, field in (("name", "name"), ("version", "version"),
+                                 ("descr", "description"), ("category", "category"),
+                                 ("author", "author"), ("email", "email")):
+            setattr(cls, attribute, declaration[field])

file_backup/_operations.py

@@ -0,0 +1,356 @@
+"""Filesystem backup operations over committed catalog points."""
+from contextlib import contextmanager
+from datetime import datetime, timezone
+import fcntl
+import os
+from pathlib import Path
+import shutil
+import sqlite3
+import stat
+import tempfile
+import uuid
+
+from . import _archives as archives
+from . import _catalog as catalog
+from ._validation import invalid, safe_absolute
+from .errors import (ArchiveCorruptError, ArchiveMissingError, BackupIOError, CatalogError, ChainError,
+                     ConflictError, FileNotFoundError as SavedFileNotFoundError, SourceChangedError)
+from .types import (BackupCreated, BackupUnchanged, BackupPreview, PointList, FileList,
+                    RestoreResult, RestorePreview, FileRestoreResult, FileRestorePreview,
+                    VerificationReport, CatalogRecoveryResult, CatalogRecoveryPreview)
+
+
+def now():
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def inside(path, root):
+    return Path(path).is_relative_to(Path(root))
+
+
+def scan(source, operation):
+    root = Path(source)
+    if not root.is_dir():
+        invalid(operation, "source", "value", "existing directory", source)
+    content, signatures = {}, {}
+    try:
+        for directory, dirs, names in os.walk(root, followlinks=False):
+            for name in sorted(dirs + names):
+                path = Path(directory) / name
+                before = path.lstat()
+                if stat.S_ISDIR(before.st_mode):
+                    continue
+                if not stat.S_ISREG(before.st_mode):
+                    invalid(operation, "source", "value", "regular files only", str(path))
+                with path.open("rb") as handle:
+                    opened = os.fstat(handle.fileno())
+                    if (opened.st_ino, opened.st_dev) != (before.st_ino, before.st_dev):
+                        raise SourceChangedError("Source changed before read", operation=operation, path=str(path))
+                    payload = handle.read()
+                    after = os.fstat(handle.fileno())
+                signature = (before.st_dev, before.st_ino, before.st_size, before.st_mtime_ns, before.st_ctime_ns)
+                if signature != (after.st_dev, after.st_ino, after.st_size, after.st_mtime_ns, after.st_ctime_ns):
+                    raise SourceChangedError("Source changed during read", operation=operation, path=str(path))
+                relative = path.relative_to(root).as_posix()
+                content[relative] = payload
+                signatures[relative] = signature
+        return content, signatures
+    except OSError as cause:
+        raise BackupIOError("Cannot scan source", operation=operation, path=str(root), phase="scan") from cause
+
+
+@contextmanager
+def writer(repository, catalog_path):
+    root = Path(repository)
+    root.mkdir(parents=True, exist_ok=True)
+    catalog_path.parent.mkdir(parents=True, exist_ok=True)
+    with (catalog_path.parent / ".writer.lock").open("a+b") as handle:
+        try:
+            fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as cause:
+            raise ConflictError("Another backup writer is active", operation="backup", path=str(root), reason="writer_locked") from cause
+        try:
+            yield
+        finally:
+            fcntl.flock(handle, fcntl.LOCK_UN)
+
+
+def backup(repository, source, dry_run=False, catalog_path=None):
+    operation = "backup"
+    catalog_path = Path(catalog_path) if catalog_path else Path(repository) / "catalog.sqlite3"
+    if inside(repository, source) or inside(source, repository):
+        invalid(operation, "source", "value", "disjoint repository and source", source)
+    if inside(catalog_path.parent, source) or inside(source, catalog_path.parent):
+        invalid(operation, "catalog_directory", "value", "disjoint catalog and source", str(catalog_path.parent))
+    initial = scan(source, operation)
+    if dry_run:
+        return _backup(repository, source, True, initial, catalog_path)
+    # Missing selected catalog must fail before creating its directory or lock.
+    catalog.load(repository, operation, catalog_path)
+    try:
+        with writer(repository, catalog_path):
+            return _backup(repository, source, False, initial, catalog_path)
+    except OSError as cause:
+        raise BackupIOError("Cannot write backup", operation=operation, path=repository, phase="write") from cause
+
+
+def _backup(repository, source, dry_run, initial, catalog_path):
+    operation = "backup"
+    content, signatures = initial
+    identity, points = catalog.load(repository, operation, catalog_path)
+    previous = points[-1] if points else None
+    base = next((r for r in points if previous and r["point"] == previous["base_point"]), None)
+    full = previous is None or base is None or not (Path(repository) / base["archive"]).exists()
+    if previous and not full:
+        archives.materialize(repository, catalog.chain(points, previous["point"], operation), identity, operation)
+    before = previous["manifest"]["files"] if previous else {}
+    added = set(content) - set(before)
+    modified = {n for n in set(content) & set(before) if archives.digest(content[n]) != before[n]["sha256"]}
+    deleted = set(before) - set(content)
+    action = "full" if full else "incremental" if added or modified or deleted else "unchanged"
+    if dry_run:
+        return BackupPreview("preview", action, len(added), len(modified), len(deleted), previous["point"] if previous else None)
+    if action == "unchanged":
+        return BackupUnchanged("unchanged", previous["point"], None, 0, 0, 0)
+    root = Path(repository)
+    archive_dir = root / "archives"
+    if not safe_absolute(str(archive_dir)):
+        invalid(operation, "repository", "value", "archive directory without symlinks", str(archive_dir))
+    archive_dir.mkdir(exist_ok=True)
+    # A finalized archive without a committed catalog row is a crash orphan.
+    known = {r["archive"] for r in points}
+    for orphan in archive_dir.glob("*.tar.gz"):
+        if orphan.relative_to(root).as_posix() not in known:
+            quarantine = root / "quarantine"
+            quarantine.mkdir(exist_ok=True)
+            os.replace(orphan, quarantine / (orphan.name + "." + uuid.uuid4().hex))
+    identity = identity or str(uuid.uuid4())
+    marker = root / ".repository-id"
+    if not marker.exists():
+        marker.write_text(identity, encoding="ascii")
+    elif marker.read_text(encoding="ascii") != identity:
+        raise CatalogError("Repository identity mismatch", operation=operation, catalog=str(catalog_path), phase="identity")
+    point = str(uuid.uuid4())
+    stamp = now()
+    relative = f"archives/{point}.tar.gz"
+    manifest = dict(repository=identity, point=point, kind=action,
+                    base_point=point if full else previous["base_point"],
+                    previous_point=None if full else previous["point"],
+                    snapshot_at=stamp, completed_at=stamp,
+                    files={name:dict(sha256=archives.digest(data), version=archives.digest(data), size=len(data),
+                                     archive=relative if full or name in added or name in modified else before[name]["archive"])
+                           for name, data in sorted(content.items())},
+                    changed=sorted(content if full else added | modified), deleted=[] if full else sorted(deleted))
+    temporary = None
+    final = root / relative
+    connection = None
+    committed = False
+    catalog_existed = catalog_path.exists()
+    try:
+        descriptor, temporary = tempfile.mkstemp(prefix=".archive-", dir=archive_dir)
+        os.close(descriptor)
+        archives.create(temporary, manifest, {n:content[n] for n in manifest["changed"]})
+        with open(temporary, "rb") as handle:
+            os.fsync(handle.fileno())
+        after, after_signatures = scan(source, operation)
+        if content != after or signatures != after_signatures:
+            raise SourceChangedError("Source changed during backup", operation=operation, path=source)
+        archive_hash = archives.digest(Path(temporary).read_bytes())
+        os.replace(temporary, final)
+        temporary = None
+        directory_descriptor = os.open(archive_dir, os.O_RDONLY)
+        try:
+            os.fsync(directory_descriptor)
+        finally:
+            os.close(directory_descriptor)
+        after, after_signatures = scan(source, operation)
+        if content != after or signatures != after_signatures:
+            raise SourceChangedError("Source changed before checkpoint", operation=operation, path=source)
+        try:
+            connection = sqlite3.connect(catalog_path, timeout=0)
+            connection.executescript(catalog.SCHEMA)
+            connection.execute("BEGIN IMMEDIATE")
+            if not connection.execute("SELECT identity FROM repository").fetchone():
+                connection.execute("INSERT INTO repository VALUES (?)", (identity,))
+            connection.execute("INSERT INTO points(point,kind,base_point,previous_point,snapshot_at,completed_at,archive,archive_sha256,manifest) VALUES (?,?,?,?,?,?,?,?,?)",
+                               (point, action, manifest["base_point"], manifest["previous_point"], stamp, stamp, relative, archive_hash, archives.encode(manifest).decode("utf-8")))
+            connection.execute("INSERT INTO archives VALUES (?,?,?,?,?)", (point, relative, archive_hash, action, "complete"))
+            connection.execute("INSERT INTO chains VALUES (?,?,?)", (point, manifest["base_point"], manifest["previous_point"]))
+            for name, item in manifest["files"].items():
+                connection.execute("INSERT OR IGNORE INTO objects VALUES (?)", (name,))
+                connection.execute("INSERT OR IGNORE INTO content_versions VALUES (?,?)", (item["sha256"], item["size"]))
+                connection.execute("INSERT INTO point_members VALUES (?,?,?,?)", (point, name, item["sha256"], item["archive"]))
+            for name in manifest["deleted"]:
+                connection.execute("INSERT INTO tombstones VALUES (?,?)", (point, name))
+            connection.execute("DELETE FROM checkpoint")
+            connection.execute("INSERT INTO checkpoint VALUES (?)", (point,))
+            connection.commit()
+            committed = True
+        except sqlite3.Error as cause:
+            if connection:
+                connection.rollback()
+            raise CatalogError("Cannot commit saved point", operation=operation, catalog=str(catalog_path), phase="commit") from cause
+        return BackupCreated("created", point, action, manifest["base_point"], manifest["previous_point"], str(final), stamp,
+                             len(added), len(modified), len(deleted))
+    finally:
+        if connection:
+            connection.close()
+        if temporary and Path(temporary).exists():
+            Path(temporary).unlink()
+        if not committed and final.exists():
+            final.unlink()
+        if not committed and not catalog_existed:
+            catalog_path.unlink(missing_ok=True)
+
+
+def selected(repository, point, operation, catalog_path=None):
+    identity, points = catalog.load(repository, operation, catalog_path)
+    chain = catalog.chain(points, point, operation)
+    try:
+        content = archives.materialize(repository, chain, identity, operation)
+    except (ArchiveMissingError, ArchiveCorruptError) as cause:
+        if operation in ("restore", "restore_file") and cause.point != point:
+            raise ChainError("Saved point dependency is unavailable", operation=operation,
+                             point=point, missing_dependency=cause.point) from cause
+        raise
+    return identity, points, chain, content
+
+
+def list_points(repository, catalog_path=None):
+    _, points = catalog.load(repository, "list_points", catalog_path)
+    return PointList(tuple(catalog.info(points, row, "list_points") for row in sorted(points, key=lambda r:(r["completed_at"], r["point"]))))
+
+
+def inspect_point(repository, point, catalog_path=None):
+    _, points = catalog.load(repository, "inspect_point", catalog_path)
+    chain = catalog.chain(points, point, "inspect_point")
+    return catalog.info(points, chain[-1], "inspect_point")
+
+
+def list_files(repository, point, catalog_path=None):
+    _, points = catalog.load(repository, "list_files", catalog_path)
+    chain = catalog.chain(points, point, "list_files")
+    return FileList(tuple(dict(path=name, **item) for name,item in sorted(chain[-1]["manifest"]["files"].items())))
+
+
+def destination_check(repository, destination, operation, catalog_path=None):
+    if inside(destination, repository) or inside(repository, destination):
+        invalid(operation, "destination", "value", "outside repository", destination)
+    if catalog_path is not None and operation in ("restore", "restore_file") and inside(destination, Path(catalog_path).parent):
+        invalid(operation, "destination", "value", "outside catalog directory", destination)
+
+
+def restore(repository, point, destination, dry_run=False, catalog_path=None):
+    operation = "restore"
+    destination_check(repository, destination, operation, catalog_path)
+    target = Path(destination)
+    if target.exists() and (not target.is_dir() or any(target.iterdir())):
+        raise ConflictError("Restore destination must be empty", operation=operation, path=destination, reason="nonempty_destination")
+    _, _, _, content = selected(repository, point, operation, catalog_path)
+    size = sum(map(len, content.values()))
+    if dry_run:
+        return RestorePreview("preview", point, destination, len(content), size)
+    staging = None
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        staging = Path(tempfile.mkdtemp(prefix=".restore-", dir=target.parent))
+        for name, data in content.items():
+            path = staging / name
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with path.open("wb") as handle:
+                handle.write(data)
+                handle.flush()
+                os.fsync(handle.fileno())
+        if target.exists() and any(target.iterdir()):
+            raise ConflictError("Destination changed during restore", operation=operation, path=destination, reason="nonempty_destination")
+        os.replace(staging, target)
+        staging = None
+        return RestoreResult("restored", point, destination, len(content), size)
+    except OSError as cause:
+        raise BackupIOError("Cannot publish restored slice", operation=operation, path=destination, phase="restore") from cause
+    finally:
+        if staging:
+            shutil.rmtree(staging)
+
+
+def restore_file(repository, point, path, destination, overwrite=False, dry_run=False, catalog_path=None):
+    operation = "restore_file"
+    destination_check(repository, destination, operation, catalog_path)
+    target = Path(destination)
+    if not safe_absolute(str(target)):
+        invalid(operation, "destination", "value", "no symlink components", str(target))
+    if target.exists() and (not overwrite or not target.is_file()):
+        raise ConflictError("Destination file exists", operation=operation, path=str(target), reason="file_exists")
+    _, _, _, content = selected(repository, point, operation, catalog_path)
+    if path not in content:
+        raise SavedFileNotFoundError("File is not live at point", operation=operation, point=point, path=path)
+    payload = content[path]
+    sha = archives.digest(payload)
+    if dry_run:
+        return FileRestorePreview("preview", point, path, sha, len(payload))
+    temporary = None
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, temporary = tempfile.mkstemp(prefix=".restore-file-", dir=target.parent)
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+        if overwrite:
+            os.replace(temporary, target)
+        else:
+            os.link(temporary, target)
+            os.unlink(temporary)
+        temporary = None
+        return FileRestoreResult("restored", point, path, str(target), sha, len(payload))
+    except OSError as cause:
+        raise BackupIOError("Cannot restore file", operation=operation, path=str(target), phase="restore") from cause
+    finally:
+        if temporary:
+            Path(temporary).unlink(missing_ok=True)
+
+
+def verify(repository, point, catalog_path=None):
+    _, _, chain, content = selected(repository, point, "verify", catalog_path)
+    return VerificationReport("verified", point, len(chain), len(content), sum(map(len, content.values())))
+
+
+def recover_catalog(repository, destination, catalog_copy, dry_run=False, catalog_path=None):
+    operation = "recover_catalog"
+    destination_check(repository, destination, operation)
+    target = Path(destination)
+    if catalog_path is not None and target == Path(catalog_path):
+        invalid(operation, "destination", "value", "different from active catalog", destination)
+    if target.exists():
+        raise ConflictError("Catalog destination exists", operation=operation, path=destination, reason="destination_exists")
+    identity, points = catalog.load(repository, operation, catalog_copy)
+    marker = Path(repository) / ".repository-id"
+    try:
+        expected = marker.read_text(encoding="ascii")
+    except OSError as cause:
+        raise CatalogError("Repository identity is unavailable", operation=operation, catalog=catalog_copy, phase="identity") from cause
+    if identity != expected:
+        raise CatalogError("Catalog copy belongs to another repository", operation=operation, catalog=catalog_copy, phase="identity")
+    for row in points:
+        archives.materialize(repository, catalog.chain(points, row["point"], operation), identity, operation)
+    if dry_run:
+        return CatalogRecoveryPreview("preview", destination, len(points))
+    temporary = None
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, temporary = tempfile.mkstemp(prefix=".catalog-", dir=target.parent)
+        os.close(descriptor)
+        with sqlite3.connect(Path(catalog_copy).as_uri() + "?mode=ro", uri=True) as source:
+            with sqlite3.connect(temporary) as output:
+                source.backup(output)
+        with open(temporary, "rb") as handle:
+            os.fsync(handle.fileno())
+        os.link(temporary, target)
+        os.unlink(temporary)
+        temporary = None
+        return CatalogRecoveryResult("recovered", destination, len(points))
+    except (OSError, sqlite3.Error) as cause:
+        raise CatalogError("Cannot publish catalog copy", operation=operation, catalog=destination, phase="recover") from cause
+    finally:
+        if temporary:
+            Path(temporary).unlink(missing_ok=True)