lts-backup-cli 2.0.0__py3-none-any.whl

lts_backup_cli/sshconfig.py

@@ -0,0 +1,142 @@
+"""Managed blocks in ~/.ssh/config, delimited by comment tags. Text ops are pure; I/O is at the bottom."""
+
+from __future__ import annotations
+
+import os
+import pwd
+import re
+import shutil
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def begin_tag(label: str) -> str:
+    return f"# >>> ltsbu:{label} >>>"
+
+
+def end_tag(label: str) -> str:
+    return f"# <<< ltsbu:{label} <<<"
+
+
+def host_alias(label: str) -> str:
+    return f"ltsbu-{label}"
+
+
+def storage_label(server_label: str) -> str:
+    """Block label in the web server's ~/.ssh/config for its route to the storage host."""
+    return f"storage-{server_label}"
+
+
+def storage_alias(server_label: str) -> str:
+    return host_alias(storage_label(server_label))
+
+
+@dataclass(frozen=True)
+class SshHost:
+    label: str
+    hostname: str
+    user: str
+    port: int = 22
+    identity_file: str | None = None
+
+    def render(self) -> str:
+        lines = [
+            begin_tag(self.label),
+            "# Managed by lts-backup-cli. Edits inside this block are overwritten.",
+            f"Host {host_alias(self.label)}",
+            f"    HostName {self.hostname}",
+            f"    User {self.user}",
+            f"    Port {self.port}",
+        ]
+        if self.identity_file:
+            lines += [f"    IdentityFile {self.identity_file}", "    IdentitiesOnly yes"]
+        lines += [
+            "    StrictHostKeyChecking accept-new",  # TOFU: unattended runs on a fresh machine
+            "    ServerAliveInterval 60",
+            "    ServerAliveCountMax 240",
+            end_tag(self.label),
+        ]
+        return "\n".join(lines) + "\n"
+
+
+def _block_re(label: str) -> re.Pattern[str]:
+    return re.compile(
+        rf"^{re.escape(begin_tag(label))}\n.*?^{re.escape(end_tag(label))}\n?",
+        re.MULTILINE | re.DOTALL,
+    )
+
+
+def has_block(text: str, label: str) -> bool:
+    return bool(_block_re(label).search(text))
+
+
+def upsert(text: str, host: SshHost) -> str:
+    """Replace the label's block in place, or append it. Idempotent."""
+    block = host.render()
+    pattern = _block_re(host.label)
+    if pattern.search(text):
+        return pattern.sub(lambda _m: block, text, count=1)
+    if text and not text.endswith("\n"):
+        text += "\n"
+    sep = "\n" if text.strip() else ""
+    return text + sep + block  # appended so user-written entries keep first-match precedence
+
+
+def remove(text: str, label: str) -> str:
+    return _block_re(label).sub("", text, count=1)
+
+
+def defined_hosts(text: str) -> set[str]:
+    """Literal Host aliases (no wildcards/negations) the user can pass to `ltsbu discover`."""
+    found: set[str] = set()
+    for line in text.splitlines():
+        parts = line.split()
+        if len(parts) > 1 and parts[0].lower() == "host":
+            found |= {p for p in parts[1:] if not any(ch in p for ch in "*?!")}
+    return found
+
+
+def lint(text: str) -> list[str]:
+    """Report unbalanced or duplicated ltsbu tags."""
+    problems: list[str] = []
+    begins = re.findall(r"^# >>> ltsbu:(\S+) >>>$", text, re.MULTILINE)
+    ends = re.findall(r"^# <<< ltsbu:(\S+) <<<$", text, re.MULTILINE)
+    for lbl in sorted(set(begins) | set(ends)):
+        b, e = begins.count(lbl), ends.count(lbl)
+        if b != 1 or e != 1:
+            problems.append(f"ssh config block ltsbu:{lbl} has {b} begin / {e} end tags")
+    return problems
+
+
+# --- I/O -------------------------------------------------------------------------------
+
+
+def default_path() -> Path:
+    # ssh reads ~/.ssh/config from the passwd home, not $HOME (differs under `sudo -E`, in tests...)
+    return Path(pwd.getpwuid(os.getuid()).pw_dir) / ".ssh" / "config"
+
+
+def read(path: Path) -> str:
+    return path.read_text() if path.exists() else ""
+
+
+def write(path: Path, text: str) -> Path | None:
+    """Atomic write with a timestamped backup of the previous file. Returns the backup path."""
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    backup: Path | None = None
+    if path.exists():
+        backup = path.with_name(f"{path.name}.ltsbu-{time.strftime('%Y%m%dT%H%M%S')}.bak")
+        shutil.copy2(path, backup)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".config.ltsbu-")
+    try:
+        with os.fdopen(fd, "w") as fh:
+            fh.write(text)
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+    return backup

lts_backup_cli/validation.py

@@ -0,0 +1,189 @@
+"""Input validation and sanitisation at the trust boundary. Pure functions; raise ValidationError."""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+from pathlib import Path
+
+
+class ValidationError(ValueError):
+    """Raised when user-supplied input is invalid."""
+
+
+_LABEL_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,62}$")
+_HOST_LABEL_RE = re.compile(r"^(?!-)[A-Za-z0-9-]{1,63}(?<!-)$")
+_DB_RE = re.compile(r"^[A-Za-z0-9_$]{1,64}$")
+_UNIX_USER_RE = re.compile(r"^[a-z_][a-z0-9_-]{0,31}\$?$")
+_SNAPSHOT_RE = re.compile(r"^(latest|[0-9a-f]{8,64})$")
+_DB_USER_RE = re.compile(r"^[A-Za-z0-9_.$-]{1,80}$")
+_DB_HOST_RE = re.compile(r"^[A-Za-z0-9.%_:/-]{1,255}$")  # name, IP, '%' / '_' wildcards, netmask
+_HASH_RE = re.compile(r"^\*[0-9A-F]{40}$")  # mysql_native_password
+DB_PRIVILEGES = frozenset(
+    {
+        "SELECT", "INSERT", "UPDATE", "DELETE", "CREATE", "DROP", "REFERENCES", "INDEX", "ALTER",
+        "CREATE TEMPORARY TABLES", "LOCK TABLES", "CREATE VIEW", "SHOW VIEW", "CREATE ROUTINE",
+        "ALTER ROUTINE", "EXECUTE", "EVENT", "TRIGGER",
+    }
+)  # fmt: skip
+
+
+def label(value: str) -> str:
+    """Repo label: lowercase, starts alnum, [a-z0-9_-], 1..63 chars."""
+    v = value.strip().lower()
+    if not _LABEL_RE.match(v):
+        raise ValidationError(
+            f"invalid label {value!r}: use 1-63 chars of a-z, 0-9, '-', '_' starting with a-z/0-9"
+        )
+    return v
+
+
+def hostname(value: str) -> str:
+    """Hostname (RFC 1123) or IP address."""
+    v = value.strip()
+    try:
+        ipaddress.ip_address(v)
+        return v
+    except ValueError:
+        pass
+    if not v or len(v) > 253 or not all(_HOST_LABEL_RE.match(p) for p in v.rstrip(".").split(".")):
+        raise ValidationError(f"invalid hostname {value!r}")
+    return v.lower()
+
+
+def port(value: int | str) -> int:
+    try:
+        p = int(value)
+    except (TypeError, ValueError):
+        raise ValidationError(f"invalid port {value!r}") from None
+    if not 1 <= p <= 65535:
+        raise ValidationError(f"port out of range 1-65535: {p}")
+    return p
+
+
+def unix_user(value: str) -> str:
+    v = value.strip()
+    if not _UNIX_USER_RE.match(v):
+        raise ValidationError(f"invalid unix user {value!r}")
+    return v
+
+
+def db_name(value: str) -> str:
+    """MariaDB database identifier (unquoted-safe subset)."""
+    v = value.strip()
+    if not _DB_RE.match(v):
+        raise ValidationError(f"invalid database name {value!r}: use [A-Za-z0-9_$], max 64 chars")
+    return v
+
+
+def db_user(value: str) -> str:
+    """MariaDB account name; quote/backslash-free so it is safe inside '...' in SQL."""
+    if not isinstance(value, str) or not _DB_USER_RE.match(value):
+        raise ValidationError(f"invalid database user {value!r}: use [A-Za-z0-9_.$-], max 80 chars")
+    return value
+
+
+def db_host(value: str) -> str:
+    if not isinstance(value, str) or not _DB_HOST_RE.match(value):
+        raise ValidationError(f"invalid database user host {value!r}")
+    return value
+
+
+def password_hash(value: str) -> str:
+    if not isinstance(value, str) or not _HASH_RE.match(value):
+        raise ValidationError("invalid password hash: expected mysql_native_password '*' + 40 hex")
+    return value
+
+
+def privileges(values: list[str]) -> list[str]:
+    """Database-level privileges from an allowlist; never empty."""
+    if not isinstance(values, list) or not values:
+        raise ValidationError("a database user needs at least one privilege")
+    bad = [p for p in values if p not in DB_PRIVILEGES]
+    if bad:
+        raise ValidationError(f"invalid database privilege(s): {', '.join(map(repr, bad))}")
+    return list(dict.fromkeys(values))
+
+
+def abs_path(value: str, must_exist: bool = False, kind: str = "any") -> str:
+    """Absolute, normalised path; optionally checks existence and kind ('dir'|'file'|'any')."""
+    v = value.strip()
+    if not v or "\x00" in v or "\n" in v:
+        raise ValidationError(f"invalid path {value!r}")
+    p = Path(v).expanduser()
+    if not p.is_absolute():
+        raise ValidationError(f"path must be absolute: {value!r}")
+    if must_exist:
+        if not p.exists():
+            raise ValidationError(f"path does not exist: {p}")
+        if kind == "dir" and not p.is_dir():
+            raise ValidationError(f"not a directory: {p}")
+        if kind == "file" and not p.is_file():
+            raise ValidationError(f"not a file: {p}")
+    return str(Path(*p.parts))  # normalises duplicate slashes without resolving symlinks
+
+
+def remote_path(value: str) -> str:
+    """Repository path on the SFTP host: absolute, no whitespace/control chars."""
+    v = value.strip()
+    if not v.startswith("/") or any(c.isspace() or ord(c) < 32 for c in v):
+        raise ValidationError(f"invalid remote repository path {value!r}: absolute, no spaces")
+    return v.rstrip("/") or "/"
+
+
+def snapshot_id(value: str) -> str:
+    v = value.strip().lower()
+    if not _SNAPSHOT_RE.match(v):
+        raise ValidationError(f"invalid snapshot id {value!r}: 'latest' or 8-64 hex chars")
+    return v
+
+
+def keep(value: int | None) -> int | None:
+    if value is None:
+        return None
+    if value < 0:
+        raise ValidationError(f"keep value must be >= 0, got {value}")
+    return value
+
+
+WEEKDAYS = ("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")  # systemd OnCalendar names
+REPO_KINDS = ("vhost", "db", "folder")
+_HHMM_RE = re.compile(r"^([01]?\d|2[0-3]):([0-5]\d)$")
+
+
+def every_hours(value: int | str) -> int:
+    try:
+        h = int(value)
+    except (TypeError, ValueError):
+        raise ValidationError(f"invalid interval {value!r}") from None
+    if not 1 <= h <= 24:
+        raise ValidationError(f"backup interval must be 1-24 hours, got {h}")
+    return h
+
+
+def hhmm(value: str) -> str:
+    m = _HHMM_RE.match(value.strip())
+    if not m:
+        raise ValidationError(f"invalid time {value!r}: use HH:MM (00:00-23:59)")
+    return f"{int(m[1]):02d}:{m[2]}"
+
+
+def weekday(value: str) -> str:
+    v = value.strip().capitalize()
+    if v not in WEEKDAYS:
+        raise ValidationError(f"invalid weekday {value!r}: use one of {', '.join(WEEKDAYS)}")
+    return v
+
+
+def repo_kind(value: str) -> str:
+    if value not in REPO_KINDS:
+        raise ValidationError(f"invalid repo kind {value!r}: use one of {', '.join(REPO_KINDS)}")
+    return value
+
+
+def remote_abs_path(value: str) -> str:
+    """Absolute path on a remote server; normalised textually, never checked locally."""
+    v = value.strip()
+    if not v.startswith("/") or any(c.isspace() or ord(c) < 32 for c in v):
+        raise ValidationError(f"invalid remote path {value!r}: absolute, no spaces")
+    return "/" + "/".join(p for p in v.split("/") if p)