fadenstack 0.4.2__py3-none-any.whl

faden_cli/core/maintenance.py

@@ -0,0 +1,82 @@
+"""Maintenance mode: the front door answers with a maintenance page.
+
+While ``nginx/maintenance.flag`` exists in the install, nginx answers every
+page with ``nginx/maintenance.html`` -- which reloads itself once the
+platform is back -- and the APIs with a 503 saying so (see
+``shared/nginx/locations.conf``). Only ``/api/health`` and nginx's own
+health check stay open. The flag is plain JSON the page reads to say why:
+``{"reason": "upgrade" | "manual", "since": ..., "message": ...}``.
+
+``faden upgrade`` puts it down for its restart and lifts it once the backend
+is healthy again; ``faden maintenance on|off`` does it by hand.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+FLAG = Path("nginx") / "maintenance.flag"
+
+
+def flag_path(install_dir: Path) -> Path:
+    """Where the flag lives in *install_dir* (nginx reads /etc/nginx/faden/maintenance.flag)."""
+    return install_dir / FLAG
+
+
+def state(install_dir: Path) -> dict[str, Any] | None:
+    """What the flag says, or ``None`` when the platform is not in maintenance."""
+    path = flag_path(install_dir)
+    if not path.is_file():
+        return None
+    try:
+        found = json.loads(path.read_text(encoding="utf-8") or "{}")
+    except ValueError:
+        found = {}
+    return found if isinstance(found, dict) else {}
+
+
+def enter(install_dir: Path, *, reason: str, message: str | None = None) -> Path:
+    """Put the flag down: from now on nginx answers with the maintenance page."""
+    path = flag_path(install_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    doc: dict[str, Any] = {"reason": reason, "since": datetime.now(tz=UTC).isoformat(timespec="seconds")}
+    if message:
+        doc["message"] = message
+    # Readable by nginx's worker user whatever the umask: the install's nginx
+    # directory is bind-mounted read-only into the container.
+    path.write_text(json.dumps(doc) + "\n", encoding="utf-8")
+    path.chmod(0o644)
+    return path
+
+
+def leave(install_dir: Path) -> bool:
+    """Lift the flag; whether there was one."""
+    path = flag_path(install_dir)
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        return False
+    return True
+
+
+@contextmanager
+def during(install_dir: Path, *, reason: str) -> Iterator[None]:
+    """Maintenance for the block, lifted however it ends.
+
+    A failed upgrade must not leave the platform answering "maintenance":
+    whatever runs then is better reached than hidden. An operator who had
+    switched maintenance on by hand keeps it on.
+    """
+    if state(install_dir) is not None:
+        yield
+        return
+    enter(install_dir, reason=reason)
+    try:
+        yield
+    finally:
+        leave(install_dir)

faden_cli/core/private_files.py

@@ -0,0 +1,133 @@
+"""Files only the user who runs ``faden`` may read: ``.env``, backups, saved credentials.
+
+``.env`` holds every password and key of an install, and a backup holds them and every database. Written
+with the default umask they were readable by every local user: ``.env`` 0644 (0664 on a live install),
+backups 0775 directories with 0664 dumps, manifest and ``.env.bak``, and root-owned 0644 volume archives.
+
+Compose reads ``.env`` as the user who runs ``faden``, and no container mounts ``.env`` or the backups:
+owner-only takes nothing from the services. Windows has no such bits; there these helpers write the files and
+leave their access to the folder they are in.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import stat
+from pathlib import Path
+from typing import BinaryIO
+
+#: Read and written by the owner only.
+PRIVATE_FILE = 0o600
+#: Entered and listed by the owner only.
+PRIVATE_DIR = 0o700
+
+
+def _posix() -> bool:
+    return os.name != "nt"
+
+
+def open_private(path: Path, *, mode: int = PRIVATE_FILE) -> BinaryIO:
+    """Open *path* for writing (truncated), with *mode* set before a byte is written.
+
+    ``open()`` applies a mode to a file it creates only; a file that exists keeps its own, so the mode is set
+    on the open file as well. A file another user owns but this one may write (a group-writable ``.env``)
+    is still written; its mode stays, and ``faden deploy`` and ``faden upgrade`` say so.
+    """
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_BINARY", 0)
+    fd = os.open(str(path), flags, mode)
+    if _posix():
+        try:
+            os.fchmod(fd, mode)
+        except PermissionError:
+            pass
+        except BaseException:
+            os.close(fd)
+            raise
+    return os.fdopen(fd, "wb")
+
+
+def write_private(path: Path, data: bytes, *, mode: int = PRIVATE_FILE) -> Path:
+    """Write *data* to *path*, readable by its owner only (or with *mode*) from the start."""
+    with open_private(path, mode=mode) as handle:
+        handle.write(data)
+    return path
+
+
+def make_private(path: Path, *, mode: int = PRIVATE_FILE) -> bool:
+    """Give an existing file *mode*; ``False`` when it could not be changed (another user's file)."""
+    if not _posix() or not path.is_file() or path.is_symlink():
+        return True
+    try:
+        if stat.S_IMODE(path.stat().st_mode) != mode:
+            path.chmod(mode)
+    except OSError:
+        return False
+    return True
+
+
+def private_dir(path: Path) -> Path:
+    """Make *path* (and its parents) and give it :data:`PRIVATE_DIR`; the parents keep their modes."""
+    path.mkdir(parents=True, exist_ok=True)
+    if _posix():
+        # A directory someone else owns, such as a mount point, keeps its mode: its files are still private.
+        with contextlib.suppress(OSError):
+            path.chmod(PRIVATE_DIR)
+    return path
+
+
+def tighten_tree(root: Path) -> list[Path]:
+    """Make *root* and everything below it owner-only: directories 0700, files 0600.
+
+    For an install's backups, from before they were written that way. Returns what could not be changed,
+    such as a volume archive a helper container wrote as root; inside a 0700 directory nobody else reaches
+    it anyway. Symbolic links are left alone, and not followed.
+    """
+    if not _posix() or not root.is_dir() or root.is_symlink():
+        return []
+    stuck: list[Path] = []
+    # Top-down and without following links: each directory is listed, then made private.
+    for current, _dirs, files in os.walk(root):
+        here = Path(current)
+        try:
+            if stat.S_IMODE(here.stat().st_mode) != PRIVATE_DIR:
+                here.chmod(PRIVATE_DIR)
+        except OSError:
+            stuck.append(here)
+        stuck.extend(here / name for name in files if not make_private(here / name))
+    return stuck
+
+
+def secure_install(install_dir: Path) -> list[Path]:
+    """Make an install's secrets owner-only: ``.env``, the saved credentials, the backups.
+
+    ``faden deploy`` and ``faden upgrade`` run it, so an install made before keeps nothing readable by
+    others. Warns about what could not be changed, and returns it. Files another user owns inside a
+    backups directory that is now private (volume archives older backups had written as root) are out of
+    everyone else's reach, and only mentioned.
+    """
+    from faden_cli.core.console import info, warning  # noqa: PLC0415
+
+    install_dir = Path(install_dir)
+    exposed = [
+        path
+        for path in (install_dir / ".env", install_dir / ".bootstrap-credentials")
+        if not make_private(path)
+    ]
+    backups = install_dir / "backups"
+    stuck = tighten_tree(backups)
+    shielded: list[Path] = []
+    (exposed if backups in stuck else shielded).extend(stuck)
+    if exposed:
+        paths = " ".join(str(path) for path in exposed[:5])
+        more = f" (and {len(exposed) - 5} more)" if len(exposed) > 5 else ""  # noqa: PLR2004
+        warning(
+            "Another user owns these, so they could not be made readable by their owner only:"
+            f' {paths}{more}.\n  Fix with: sudo chown -R "$(id -un)" {paths}, then run this command again.'
+        )
+    if shielded:
+        info(
+            f"{len(shielded)} file(s) in the backups belong to another user (archives older backups wrote as"
+            " root); the backups directory is private, so nobody else reaches them."
+        )
+    return exposed