filekeeper-cli 0.1.0__py3-none-any.whl

filekeeper/core/paths.py

@@ -0,0 +1,236 @@
+"""Workspace-bound path resolution.
+
+Every operation goes through :func:`resolve_path`. It is the single place where
+"which file is this?" is decided, and it enforces four rules:
+
+1. Relative paths resolve against the workspace root; absolute paths are accepted
+   only when they land inside the workspace after canonical resolution.
+2. Relative paths containing a ``..`` segment are rejected outright with
+   :class:`PathOutsideWorkspaceError`. They are never needed for legitimate
+   workspace work, and rejecting them is cheaper to audit than proving each
+   normalisation correct.
+3. Symlinks are resolved. A link whose target leaves the workspace is refused
+   with :class:`SymlinkEscapeRefusedError`, and a symlink is never a write
+   target: the link itself would be replaced.
+4. An absolute path that resolves outside the workspace is refused with
+   :class:`AbsolutePathOutsideWorkspaceError`.
+5. Device files, sockets and FIFOs are refused for normal file operations, as are
+   paths inside Filekeeper's own state directory.
+
+Errors name the caller's path, never the resolved host path, so adapter output
+stays free of absolute paths.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from .errors import (
+    AbsolutePathOutsideWorkspaceError,
+    NotAFileError,
+    PathNotFoundError,
+    PathOutsideWorkspaceError,
+    SpecialFileRefusedError,
+    StatePathError,
+    SymlinkEscapeRefusedError,
+    SymlinkWriteRefusedError,
+    ValidationError,
+)
+from .errors import (
+    NotADirectoryError as FilekeeperNotADirectoryError,
+)
+
+PathKind = Literal["file", "directory", "symlink", "other"]
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedPath:
+    """A path proven to be inside the workspace.
+
+    ``absolute`` is the canonical target (symlinks resolved) and is what
+    operations act on. ``link_path`` is the path as located in the workspace,
+    which differs only when the final component is a symlink; metadata calls need
+    it to stat the link itself instead of its target.
+    """
+
+    absolute: Path
+    relative: str
+    exists: bool
+    is_symlink: bool
+    link_path: Path
+
+    @property
+    def kind(self) -> PathKind:
+        if self.is_symlink:
+            return "symlink"
+        if self.absolute.is_dir():
+            return "directory"
+        if self.absolute.is_file():
+            return "file"
+        return "other"
+
+
+def _reject_traversal(raw: str) -> None:
+    normalised = raw.replace("\\", "/")
+    for segment in normalised.split("/"):
+        if segment == "..":
+            raise PathOutsideWorkspaceError(
+                "path traversal with '..' is not allowed; use a workspace-relative path",
+                details={"path": raw},
+            )
+
+
+def _kind_of(path: Path) -> PathKind:
+    if path.is_symlink():
+        return "symlink"
+    if path.is_dir():
+        return "directory"
+    if path.is_file():
+        return "file"
+    return "other"
+
+
+def _escapes_through_symlink(joined: Path, root_canonical: Path) -> bool:
+    """True when a symlink at or below the workspace root points outside it."""
+
+    try:
+        relative = Path(os.path.abspath(joined)).relative_to(root_canonical)
+    except ValueError:
+        return False
+    current = root_canonical
+    for part in relative.parts:
+        current = current / part
+        if not current.is_symlink():
+            continue
+        target = Path(os.path.realpath(current))
+        if target != root_canonical and root_canonical not in target.parents:
+            return True
+    return False
+
+
+def _reject_special_file(path: Path, *, display: str) -> None:
+    try:
+        info = os.lstat(path)
+    except FileNotFoundError:
+        return
+    mode = info.st_mode
+    if stat.S_ISREG(mode) or stat.S_ISDIR(mode) or stat.S_ISLNK(mode):
+        return
+    raise SpecialFileRefusedError(
+        "only regular files and directories are supported; device files, sockets "
+        "and FIFOs are refused",
+        details={"path": display},
+    )
+
+
+def resolve_path(
+    root: Path,
+    user_path: str | Path,
+    *,
+    for_write: bool = False,
+    must_exist: bool = False,
+    expect: Literal["file", "directory"] | None = None,
+    state_dir: Path | None = None,
+) -> ResolvedPath:
+    """Resolve ``user_path`` inside ``root`` or raise a boundary error."""
+
+    root_canonical = Path(root).resolve()
+    if not root_canonical.is_dir():
+        raise ValidationError(
+            "workspace root does not exist or is not a directory",
+            details={"root": str(root)},
+        )
+
+    raw = str(user_path)
+    if "\x00" in raw:
+        raise ValidationError("path contains a NUL byte", details={"path": "<contains NUL>"})
+    if raw.strip() == "":
+        raise ValidationError("path must not be empty")
+
+    candidate = Path(raw)
+    if candidate.is_absolute():
+        joined = candidate
+    else:
+        _reject_traversal(raw)
+        joined = root_canonical / candidate
+
+    # realpath resolves symlinks in the existing prefix and is well-defined for
+    # paths that do not exist yet.
+    canonical = Path(os.path.realpath(joined))
+
+    if canonical != root_canonical and root_canonical not in canonical.parents:
+        if _escapes_through_symlink(joined, root_canonical):
+            raise SymlinkEscapeRefusedError(
+                "symlink target resolves outside the workspace",
+                details={"path": raw},
+            )
+        if candidate.is_absolute():
+            raise AbsolutePathOutsideWorkspaceError(
+                "absolute path resolves outside the workspace",
+                details={"path": raw},
+            )
+        raise PathOutsideWorkspaceError(
+            "path resolves outside the workspace",
+            details={"path": raw},
+        )
+
+    if state_dir is not None:
+        state_canonical = Path(os.path.realpath(state_dir))
+        if canonical == state_canonical or state_canonical in canonical.parents:
+            raise StatePathError(
+                "path points inside Filekeeper's own state directory",
+                details={"path": raw},
+            )
+
+    is_link = joined.is_symlink()
+    exists = os.path.lexists(joined)
+    link_location = Path(os.path.abspath(joined))
+
+    if is_link and for_write:
+        raise SymlinkWriteRefusedError(
+            "writes to symlinks are refused; write to the link target explicitly",
+            details={"path": raw},
+        )
+
+    if exists:
+        _reject_special_file(joined, display=raw)
+
+    reported = link_location if is_link else canonical
+    relative = reported.relative_to(root_canonical).as_posix()
+    resolved = ResolvedPath(
+        absolute=canonical,
+        relative=relative if relative != "." else "",
+        exists=exists and canonical.exists(),
+        is_symlink=is_link,
+        link_path=link_location,
+    )
+
+    if must_exist and not resolved.exists:
+        raise PathNotFoundError("path does not exist", details={"path": raw})
+
+    if expect is not None and resolved.exists:
+        kind = resolved.kind
+        if expect == "file" and kind not in {"file", "symlink"}:
+            raise NotAFileError("path is not a regular file", details={"path": raw})
+        if expect == "file" and kind == "symlink":
+            # A symlink that resolves to a file is acceptable for reads.
+            if not resolved.absolute.is_file():
+                raise NotAFileError("path is not a regular file", details={"path": raw})
+        if expect == "directory" and not resolved.absolute.is_dir():
+            raise FilekeeperNotADirectoryError("path is not a directory", details={"path": raw})
+
+    return resolved
+
+
+def ensure_parent_directory(resolved: ResolvedPath) -> None:
+    """Raise a validation error when the destination's parent is missing."""
+
+    if not resolved.absolute.parent.is_dir():
+        raise ValidationError(
+            "parent directory does not exist; create it first",
+            details={"path": resolved.relative or "."},
+        )

filekeeper/core/safety/__init__.py

@@ -0,0 +1,5 @@
+"""Safety primitives: atomic replacement, hashing, text rules, refusals."""
+
+from . import atomic, hashing, sensitive, textdata, vcs
+
+__all__ = ["atomic", "hashing", "sensitive", "textdata", "vcs"]

filekeeper/core/safety/atomic.py

@@ -0,0 +1,129 @@
+"""The atomic single-file write primitive.
+
+The guarantee: on return, the destination holds either its complete previous
+content or the complete new content. Never a prefix, never a mixture. That holds
+across process death because the visible change is a single ``rename`` within one
+directory, and it holds across machine crash when ``fsync`` is enabled because
+both the temporary file and the parent directory are flushed first.
+
+Failure before the rename leaves the destination untouched and removes the
+temporary file; the caller can retry.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import stat
+import tempfile
+from pathlib import Path
+
+from ..errors import StorageError
+from .hashing import hash_bytes, hash_file
+
+_TEMP_PREFIX = ".keeper-tmp-"
+
+
+def _default_file_mode() -> int:
+    """The mode a plain ``open()`` would produce for a new file under this umask."""
+
+    current = os.umask(0)
+    os.umask(current)
+    return 0o666 & ~current
+
+
+def _fsync_directory(directory: Path) -> None:
+    """Flush a directory entry. Unsupported on some platforms; that is not an error."""
+
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    try:
+        descriptor = os.open(directory, flags)
+    except OSError:
+        return
+    try:
+        os.fsync(descriptor)
+    except OSError:  # pragma: no cover - e.g. filesystems that reject dir fsync
+        pass
+    finally:
+        os.close(descriptor)
+
+
+def atomic_write_bytes(
+    destination: Path,
+    data: bytes,
+    *,
+    mode: int | None = None,
+    fsync: bool = True,
+    display_path: str | None = None,
+) -> str:
+    """Replace ``destination`` with ``data`` atomically; return the new content hash.
+
+    ``mode`` sets the resulting permission bits. When omitted, an existing
+    destination keeps its mode and a new file gets the umask-derived default.
+    ``display_path`` is the caller-facing path used in error details; the
+    resolved host path and the temporary name are never reported. The final
+    content is read back and hashed; a mismatch is a storage error.
+    """
+
+    details = {"path": display_path} if display_path is not None else {}
+
+    if destination.is_symlink():
+        raise StorageError(
+            "refusing to replace a symlink atomically; the link itself would be "
+            "replaced, not its target",
+            details=details,
+        )
+    parent = destination.parent
+    if not parent.is_dir():
+        raise StorageError("destination directory does not exist", details=details)
+
+    existing_mode: int | None = None
+    try:
+        existing_mode = stat.S_IMODE(destination.stat().st_mode)
+    except FileNotFoundError:
+        existing_mode = None
+
+    temporary_path: Path | None = None
+    try:
+        descriptor, temporary_name = tempfile.mkstemp(prefix=_TEMP_PREFIX, dir=parent)
+        temporary_path = Path(temporary_name)
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            if fsync:
+                os.fsync(handle.fileno())
+        effective_mode = mode if mode is not None else existing_mode
+        if effective_mode is None:
+            # tempfile.mkstemp creates 0600; a new file should follow the umask.
+            effective_mode = _default_file_mode()
+        os.chmod(temporary_path, effective_mode)
+        os.replace(temporary_path, destination)
+    except OSError as exc:
+        # ``str(exc)`` carries the temporary path and errno context; only the
+        # standard reason phrase is safe to show a caller.
+        raise StorageError(
+            f"atomic write failed: {exc.strerror or type(exc).__name__}",
+            details=details,
+        ) from exc
+    finally:
+        if temporary_path is not None:
+            with contextlib.suppress(FileNotFoundError):
+                temporary_path.unlink()
+
+    if fsync:
+        _fsync_directory(parent)
+
+    expected = hash_bytes(data)
+    actual = hash_file(destination, display_path=display_path or destination.name)
+    if expected != actual:
+        raise StorageError(
+            "content verification failed after atomic write",
+            details={**details, "expected_hash": expected, "actual_hash": actual},
+        )
+    return actual
+
+
+def fsync_directory(directory: Path) -> None:
+    """Public wrapper used after rename/unlink by non-atomic operations."""
+
+    _fsync_directory(directory)

filekeeper/core/safety/hashing.py

@@ -0,0 +1,73 @@
+"""SHA-256 hashing helpers.
+
+Hashes are always returned as ``sha256:<hex>``. Incoming hashes are accepted with
+or without the prefix, and a malformed value is a validation error rather than a
+silent mismatch.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from pathlib import Path
+
+from ..errors import PathNotFoundError, ValidationError, storage_failure
+
+ALGORITHM = "sha256"
+PREFIX = f"{ALGORITHM}:"
+CHUNK_SIZE = 1024 * 1024
+_HEX_LENGTH = 64
+
+
+def format_digest(digest_hex: str) -> str:
+    """Return the canonical ``sha256:<hex>`` form for a bare hex digest."""
+
+    return f"{PREFIX}{digest_hex}"
+
+
+def hash_bytes(data: bytes) -> str:
+    return format_digest(hashlib.sha256(data).hexdigest())
+
+
+def hash_file(path: Path, *, display_path: str | None = None) -> str:
+    """Stream a file through SHA-256; never loads the whole file into memory.
+
+    ``display_path`` is the caller-facing path used in error details. Callers that
+    hold a resolved path must pass the workspace-relative form; when it is
+    omitted only the file name is used, so a failure never reports the resolved
+    host path.
+    """
+
+    display = path.name if display_path is None else display_path
+    digest = hashlib.sha256()
+    try:
+        with path.open("rb") as handle:
+            while chunk := handle.read(CHUNK_SIZE):
+                digest.update(chunk)
+    except FileNotFoundError as exc:
+        raise PathNotFoundError("file not found", details={"path": display}) from exc
+    except OSError as exc:
+        raise storage_failure("hash", display, exc) from exc
+    return format_digest(digest.hexdigest())
+
+
+def normalize_hash(value: str) -> str:
+    """Validate and canonicalise a caller-supplied hash."""
+
+    candidate = value.strip()
+    if candidate.startswith(PREFIX):
+        candidate = candidate[len(PREFIX) :]
+    valid_characters = set("0123456789abcdefABCDEF")
+    if len(candidate) != _HEX_LENGTH or any(char not in valid_characters for char in candidate):
+        raise ValidationError(
+            "not a SHA-256 hash; expected 64 hexadecimal characters, optionally "
+            "prefixed with 'sha256:'",
+            details={"value": value},
+        )
+    return format_digest(candidate.lower())
+
+
+def hashes_match(left: str, right: str) -> bool:
+    """Constant-time comparison of two canonical hashes."""
+
+    return hmac.compare_digest(normalize_hash(left), normalize_hash(right))

filekeeper/core/safety/sensitive.py

@@ -0,0 +1,65 @@
+"""Refusal to write credential and key material.
+
+A cheap guard on the most expensive mistake. The rule is a name-shape check on
+the workspace-relative target: it refuses obvious credential files and anything
+under a key directory. It is not a content scanner, and it is overridable only
+through a Core argument and a CLI flag whose names state the risk.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+SENSITIVE_FILENAMES: Final[frozenset[str]] = frozenset(
+    {
+        ".env",
+        "id_rsa",
+        "id_dsa",
+        "id_ecdsa",
+        "id_ed25519",
+        "authorized_keys",
+        "known_hosts",
+        ".netrc",
+        ".pgpass",
+        ".npmrc",
+        ".pypirc",
+        "credentials",
+        "credentials.json",
+    }
+)
+SENSITIVE_SUFFIXES: Final[tuple[str, ...]] = (
+    ".pem",
+    ".key",
+    ".p12",
+    ".pfx",
+    ".keystore",
+    ".jks",
+)
+SENSITIVE_DIRECTORIES: Final[frozenset[str]] = frozenset({".ssh", ".gnupg", ".aws"})
+_ENV_PREFIX = ".env."
+
+
+def sensitive_reason(relative_path: str) -> str | None:
+    """Return a short reason when the relative path looks like credential material."""
+
+    parts = [part for part in relative_path.replace("\\", "/").split("/") if part]
+    if not parts:
+        return None
+
+    for part in parts[:-1]:
+        if part.lower() in SENSITIVE_DIRECTORIES:
+            return f"inside the {part}/ directory"
+
+    name = parts[-1]
+    lowered = name.lower()
+    if lowered in SENSITIVE_FILENAMES:
+        return "credential file name"
+    if lowered.startswith(_ENV_PREFIX):
+        return "environment file name"
+    if lowered.endswith(SENSITIVE_SUFFIXES):
+        return "key or certificate file extension"
+    return None
+
+
+def is_sensitive_path(relative_path: str) -> bool:
+    return sensitive_reason(relative_path) is not None

filekeeper/core/safety/textdata.py

@@ -0,0 +1,142 @@
+"""Text detection, decoding and encoding rules.
+
+Rules this module enforces, and that the documentation repeats:
+
+* A file containing a NUL byte in its first 8 KiB is treated as binary. Text
+  operations refuse it instead of returning mojibake.
+* Decoding is strict. Undecodable bytes are an error unless the caller names an
+  encoding explicitly.
+* A UTF-8 byte-order mark is preserved on rewrite.
+* Line endings are *never* normalised. Content is decoded and re-encoded as-is;
+  the detected convention is reported, not applied.
+"""
+
+from __future__ import annotations
+
+import codecs
+from dataclasses import dataclass
+from typing import Final
+
+from ..errors import BinaryContentRefusedError, ValidationError
+
+BINARY_SAMPLE_SIZE: Final = 8192
+_BOM_BYTES: Final[dict[str, bytes]] = {
+    "utf-8": codecs.BOM_UTF8,
+    "utf-16-le": codecs.BOM_UTF16_LE,
+    "utf-16-be": codecs.BOM_UTF16_BE,
+    "utf-32-le": codecs.BOM_UTF32_LE,
+    "utf-32-be": codecs.BOM_UTF32_BE,
+}
+_BOMS: Final[tuple[tuple[bytes, str], ...]] = (
+    (codecs.BOM_UTF8, "utf-8"),
+    (codecs.BOM_UTF16_LE, "utf-16-le"),
+    (codecs.BOM_UTF16_BE, "utf-16-be"),
+    (codecs.BOM_UTF32_LE, "utf-32-le"),
+    (codecs.BOM_UTF32_BE, "utf-32-be"),
+)
+
+
+@dataclass(frozen=True, slots=True)
+class TextProfile:
+    """How a file's bytes decode, and what its lines look like."""
+
+    encoding: str
+    newline: str
+    has_bom: bool
+
+
+def looks_binary(data: bytes) -> bool:
+    """True when the sample contains NUL, the cheapest reliable heuristic."""
+
+    return b"\x00" in data[:BINARY_SAMPLE_SIZE]
+
+
+def detect_bom(data: bytes) -> tuple[str, bool] | None:
+    """Return ``(encoding, has_bom)`` when the data starts with a known BOM."""
+
+    # Longest first: UTF-32 LE shares its first two bytes with UTF-16 LE.
+    for bom, encoding in sorted(_BOMS, key=lambda item: len(item[0]), reverse=True):
+        if data.startswith(bom):
+            return encoding, True
+    return None
+
+
+def detect_newline(text: str) -> str:
+    """Dominant newline convention: ``\\r\\n``, ``\\n``, ``\\r``, or ``""``."""
+
+    crlf = text.count("\r\n")
+    lone_cr = text.count("\r") - crlf
+    lone_lf = text.count("\n") - crlf
+    counts = {"\r\n": crlf, "\n": lone_lf, "\r": lone_cr}
+    best = max(counts, key=lambda key: counts[key])
+    return best if counts[best] > 0 else ""
+
+
+def decode_bytes(
+    data: bytes,
+    *,
+    encoding: str | None = None,
+    partial: bool = False,
+    path: str = "",
+) -> tuple[str, TextProfile]:
+    """Decode bytes as text, or refuse them with BINARY_CONTENT_REFUSED.
+
+    ``partial`` tolerates a truncated trailing multi-byte sequence, which is what
+    a bounded read produces.
+    """
+
+    if encoding is None:
+        if looks_binary(data):
+            raise BinaryContentRefusedError(
+                "binary content cannot be read as text",
+                details={"path": path, "reason": "nul_byte"},
+            )
+        bom = detect_bom(data)
+        if bom is not None:
+            detected, has_bom = bom
+            encoding = detected
+        else:
+            detected, has_bom = "utf-8", False
+            encoding = detected
+    else:
+        has_bom = encoding == "utf-8" and data.startswith(codecs.BOM_UTF8)
+
+    try:
+        decoder = codecs.getincrementaldecoder(encoding)(errors="strict")
+        text = decoder.decode(data, final=not partial)
+    except LookupError as exc:
+        raise ValidationError(
+            f"unknown text encoding: {encoding}", details={"encoding": encoding}
+        ) from exc
+    except UnicodeDecodeError as exc:
+        raise BinaryContentRefusedError(
+            f"content is not valid {encoding}; pass an explicit encoding to force a read",
+            details={"path": path, "encoding": encoding, "byte_offset": exc.start},
+        ) from exc
+
+    if encoding == "utf-8" and text.startswith("\ufeff"):
+        text = text[1:]
+        has_bom = True
+    elif encoding in {"utf-16-le", "utf-16-be", "utf-32-le", "utf-32-be"} and text.startswith(
+        "\ufeff"
+    ):
+        text = text[1:]
+
+    return text, TextProfile(encoding=encoding, newline=detect_newline(text), has_bom=has_bom)
+
+
+def encode_text(text: str, *, encoding: str, has_bom: bool) -> bytes:
+    """Encode text back with the same convention it was read with."""
+
+    try:
+        payload = text.encode(encoding)
+    except (LookupError, UnicodeEncodeError) as exc:
+        raise ValidationError(
+            f"content cannot be encoded as {encoding}: {exc}",
+            details={"encoding": encoding},
+        ) from exc
+    if has_bom:
+        bom = _BOM_BYTES.get(encoding)
+        if bom is not None:
+            return bom + payload
+    return payload