f-layer 2.0.0__py3-none-any.whl

flayer/profiles/artifacts.py

@@ -0,0 +1,609 @@
+"""Bounded artifact bundles with exclusive ownership and verified local cleanup."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import stat
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Iterator
+
+from flayer.core.contracts import (
+    ContractError,
+    ParseIdentity,
+    RequireTable,
+    StackIdentity,
+    ValidateFields,
+    ValidateName,
+)
+
+MAX_ARTIFACT_BYTES = 1048576
+MAX_BUNDLE_BYTES = 2097152
+MAX_MANIFEST_BYTES = 16384
+MAX_BUNDLE_FILES = 8
+_FILE_PATTERN = re.compile(r"[a-z][a-z0-9-]{0,62}\.[a-z0-9]{1,12}\Z")
+_MANIFEST_NAME = "manifest.json"
+
+
+class ArtifactError(ContractError):
+    """An artifact is invalid, foreign, changed, busy, or unavailable for safe storage."""
+
+
+@dataclass(frozen=True, slots=True)
+class _FileReceipt:
+    """Pinned file identity and exact bytes authorized for a subsequent destructive step."""
+
+    device: int
+    inode: int
+    size: int
+    modified_ns: int
+    changed_ns: int
+    sha256: str
+
+
+@dataclass(frozen=True, slots=True)
+class _OwnedFile:
+    """One verified immutable file snapshot excluding its payload from representation."""
+
+    name: str
+    content: bytes = field(repr=False)
+    receipt: _FileReceipt
+
+
+@dataclass(frozen=True, slots=True)
+class _BundleSnapshot:
+    """A complete authorized bundle with the manifest and each payload pinned separately."""
+
+    files: tuple[_OwnedFile, ...]
+    manifest: _FileReceipt
+
+
+@dataclass(frozen=True, slots=True)
+class Artifact:
+    """Memory-only generated bytes; sensitive payloads are never included in repr."""
+
+    name: str
+    content: bytes = field(repr=False)
+    sensitive: bool = True
+
+    def __post_init__(self) -> None:
+        """Require a portable single filename and a bounded immutable payload."""
+
+        if (
+            not isinstance(self.name, str)
+            or _FILE_PATTERN.fullmatch(self.name) is None
+            or self.name == _MANIFEST_NAME
+        ):
+            raise ArtifactError("Artifact filename must be portable and must not be manifest.json")
+
+        if not isinstance(self.content, bytes) or not 1 <= len(self.content) <= MAX_ARTIFACT_BYTES:
+            raise ArtifactError("Artifact content must contain 1..1048576 immutable bytes")
+
+        if type(self.sensitive) is not bool:
+            raise ArtifactError("Artifact sensitivity must be an explicit boolean")
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactBundle:
+    """A named set owned by one complete stack identity, independent of provider state."""
+
+    identity: StackIdentity
+    kind: str
+    name: str
+    files: tuple[Artifact, ...] = field(repr=False)
+
+    def __post_init__(self) -> None:
+        """Reject ambiguous bundle names, duplicate files, and oversized compositions."""
+
+        if not isinstance(self.identity, StackIdentity):
+            raise ArtifactError("Artifact identity must be a StackIdentity")
+
+        if not isinstance(self.kind, str) or self.kind not in {"server", "device"}:
+            raise ArtifactError("Artifact kind must be server or device")
+
+        ValidateName(self.name, "artifact name")
+
+        if (
+            not isinstance(self.files, tuple)
+            or not 1 <= len(self.files) <= MAX_BUNDLE_FILES
+            or any(not isinstance(item, Artifact) for item in self.files)
+        ):
+            raise ArtifactError("A bundle must contain 1..8 immutable Artifact values")
+
+        if len({item.name for item in self.files}) != len(self.files):
+            raise ArtifactError("Artifact filenames must be unique")
+
+        if sum(len(item.content) for item in self.files) > MAX_BUNDLE_BYTES:
+            raise ArtifactError("A bundle must not exceed 2097152 bytes")
+
+
+def BuildDeviceBundle(
+    identity: StackIdentity, device_id: str, transport: str, files: tuple[Artifact, ...],
+) -> ArtifactBundle:
+    """Wrap externally issued transport files without generating or validating credentials."""
+
+    ValidateName(transport, "transport")
+    ValidateName(device_id, "device_id")
+
+    if not isinstance(files, tuple) or not 1 <= len(files) < MAX_BUNDLE_FILES or any(
+        not isinstance(item, Artifact) for item in files
+    ):
+        raise ArtifactError("Device files must contain 1..7 immutable Artifact values")
+
+    if any(not item.sensitive for item in files):
+        raise ArtifactError("Externally issued device profiles must be marked sensitive")
+
+    descriptor = Artifact("device-info.json", (json.dumps({
+        "schema_version": 1, "transport": transport, "device_id": device_id,
+        "status": "externally-issued-unverified",
+    }, sort_keys=True) + "\n").encode("utf-8"), sensitive=False)
+
+    return ArtifactBundle(identity, "device", device_id, files + (descriptor,))
+
+
+def _ValidatePath(path: Path) -> None:
+    """Reject parent traversal and preexisting symlink components before opening handles."""
+
+    if not path.name or ".." in path.parts:
+        raise ArtifactError("Artifact storage must name an explicit path without traversal")
+
+    if any(item.is_symlink() for item in (path, *path.parents)):
+        raise ArtifactError("Artifact paths must not contain symlinks")
+
+
+def _RequireOwned(info: os.stat_result, *, directory: bool) -> None:
+    """Require private POSIX ownership and reject special files on every platform."""
+
+    expected_type = stat.S_ISDIR if directory else stat.S_ISREG
+
+    if not expected_type(info.st_mode):
+        raise ArtifactError("Artifact storage requires regular files and directories")
+
+    if not directory and info.st_nlink != 1:
+        raise ArtifactError("Artifact storage must not contain hardlinked files")
+
+    if os.name == "posix":
+        if info.st_uid != os.getuid() or stat.S_IMODE(info.st_mode) != (0o700 if directory else 0o600):
+            raise ArtifactError("Artifact storage must be caller-owned and private")
+
+
+@contextmanager
+def _Directory(path: Path, *, create: bool = False) -> Iterator[int]:
+    """Pin one private directory handle without recursively creating parent paths."""
+
+    if os.name != "posix":
+        raise ArtifactError("Private artifact storage currently requires a POSIX host")
+
+    _ValidatePath(path)
+    descriptor: int | None = None
+
+    try:
+        if create:
+            path.mkdir(mode=0o700, exist_ok=True)
+
+        descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0))
+        _RequireOwned(os.fstat(descriptor), directory=True)
+
+        yield descriptor
+
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+
+
+def _StatKey(info: os.stat_result) -> tuple[int, int, int, int, int]:
+    """Identify replacements and in-place modifications without treating access time as a write."""
+
+    return info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns, info.st_ctime_ns
+
+
+def _Receipt(info: os.stat_result, content: bytes) -> _FileReceipt:
+    """Bind a pinned inode to exact authorized bytes and modification metadata."""
+
+    return _FileReceipt(*_StatKey(info), hashlib.sha256(content).hexdigest())
+
+
+def _ReadSnapshot(directory: int, name: str, limit: int) -> tuple[bytes, _FileReceipt]:
+    """Read bounded private bytes and reject a file that changes during the read."""
+
+    descriptor = os.open(
+        name, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0),
+        dir_fd=directory,
+    )
+
+    try:
+        before = os.fstat(descriptor)
+        _RequireOwned(before, directory=False)
+        result = bytearray()
+
+        while len(result) <= limit:
+            chunk = os.read(descriptor, min(65536, limit + 1 - len(result)))
+
+            if not chunk:
+                break
+
+            result.extend(chunk)
+
+        if len(result) > limit:
+            raise ArtifactError("Artifact file exceeds its bounded size")
+
+        after = os.fstat(descriptor)
+        _RequireOwned(after, directory=False)
+
+        if _StatKey(before) != _StatKey(after):
+            raise ArtifactError("Artifact changed while its content was being verified")
+
+        content = bytes(result)
+
+        return content, _Receipt(after, content)
+
+    finally:
+        os.close(descriptor)
+
+
+def _ReadFile(directory: int, name: str, limit: int) -> bytes:
+    """Return one verified private file snapshot without discarding its bounded-read checks."""
+
+    return _ReadSnapshot(directory, name, limit)[0]
+
+
+def _AssertFile(directory: int, name: str, expected: _FileReceipt) -> None:
+    """Require the original inode, private ownership, metadata, and exact content before cleanup."""
+
+    _, actual = _ReadSnapshot(directory, name, MAX_ARTIFACT_BYTES)
+
+    if actual != expected:
+        raise ArtifactError("Artifact was replaced or changed; cleanup is refused")
+
+
+def _UnlinkFile(directory: int, name: str, expected: _FileReceipt) -> None:
+    """Recheck a pinned receipt immediately before unlink; preserve detected replacements."""
+
+    _AssertFile(directory, name, expected)
+    info = os.stat(name, dir_fd=directory, follow_symlinks=False)
+    _RequireOwned(info, directory=False)
+
+    if _StatKey(info) != (
+        expected.device, expected.inode, expected.size, expected.modified_ns, expected.changed_ns,
+    ):
+        raise ArtifactError("Artifact changed before cleanup; removal is refused")
+
+    os.unlink(name, dir_fd=directory)
+
+
+def _AssertDirectory(parent: int, name: str, descriptor: int) -> None:
+    """Preserve a replacement directory instead of confusing its name with the pinned bundle."""
+
+    pinned = os.fstat(descriptor)
+    named = os.stat(name, dir_fd=parent, follow_symlinks=False)
+    _RequireOwned(pinned, directory=True)
+    _RequireOwned(named, directory=True)
+
+    if (pinned.st_dev, pinned.st_ino) != (named.st_dev, named.st_ino):
+        raise ArtifactError("Artifact directory was replaced; cleanup is refused")
+
+
+def ReadArtifactFile(path: str | Path) -> bytes:
+    """Read only a private artifact; never expose filesystem paths or bytes in failures."""
+
+    artifact_path = Path(path)
+
+    try:
+        _ValidatePath(artifact_path)
+
+        with _Directory(artifact_path.parent) as directory:
+            return _ReadFile(directory, artifact_path.name, MAX_ARTIFACT_BYTES)
+
+    except (OSError, ValueError, RecursionError):
+        raise ArtifactError("Unable to read a valid private artifact") from None
+
+
+def _Manifest(bundle: ArtifactBundle) -> bytes:
+    """Record exact ownership and content digests while excluding payloads and credentials."""
+
+    data = {
+        "schema_version": 1, "identity": asdict(bundle.identity), "kind": bundle.kind,
+        "name": bundle.name, "files": [{
+            "name": item.name, "size": len(item.content), "sensitive": item.sensitive,
+            "sha256": hashlib.sha256(item.content).hexdigest(),
+        } for item in bundle.files],
+    }
+
+    return (json.dumps(data, indent=2, sort_keys=True) + "\n").encode("utf-8")
+
+
+def _WriteFile(directory: int, name: str, content: bytes) -> _FileReceipt:
+    """Create one exclusive private file and fsync all bytes before returning."""
+
+    descriptor = os.open(
+        name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
+        0o600, dir_fd=directory,
+    )
+
+    written_count = 0
+
+    try:
+        remaining = memoryview(content)
+
+        while remaining:
+            written = os.write(descriptor, remaining)
+
+            if written <= 0:
+                raise OSError("Incomplete artifact write")
+
+            remaining = remaining[written:]
+            written_count += written
+
+        os.fsync(descriptor)
+
+    except BaseException:
+        try:
+            receipt = _Receipt(os.fstat(descriptor), content[:written_count])
+
+        finally:
+            os.close(descriptor)
+
+        _UnlinkFile(directory, name, receipt)
+
+        raise
+
+    else:
+        try:
+            receipt = _Receipt(os.fstat(descriptor), content)
+
+        finally:
+            os.close(descriptor)
+
+    return receipt
+
+
+@contextmanager
+def _BundleLock(directory: int, name: str) -> Iterator[None]:
+    """Serialize cooperating operations without deleting an existing crash or foreign lock."""
+
+    lock_name = f".{name}.lock"
+    descriptor = os.open(lock_name, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=directory)
+
+    try:
+        receipt = _Receipt(os.fstat(descriptor), b"")
+
+    finally:
+        os.close(descriptor)
+
+    try:
+        yield
+
+    finally:
+        _UnlinkFile(directory, lock_name, receipt)
+
+
+def WriteArtifactBundle(root: str | Path, bundle: ArtifactBundle) -> Path:
+    """Publish a new manifest-last bundle exclusively and roll back only created files."""
+
+    if not isinstance(bundle, ArtifactBundle):
+        raise ArtifactError("bundle must be an ArtifactBundle")
+
+    root_path = Path(root)
+    bundle_name = f"{bundle.kind}-{bundle.name}"
+    created: list[tuple[str, _FileReceipt]] = []
+    directory: int | None = None
+
+    try:
+        with _Directory(root_path, create=True) as parent:
+            with _BundleLock(parent, bundle_name):
+                try:
+                    os.mkdir(bundle_name, 0o700, dir_fd=parent)
+                    directory = os.open(bundle_name, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0), dir_fd=parent)
+
+                    for artifact in bundle.files:
+                        _AssertDirectory(parent, bundle_name, directory)
+                        receipt = _WriteFile(directory, artifact.name, artifact.content)
+                        created.append((artifact.name, receipt))
+
+                    for name, receipt in created:
+                        _AssertFile(directory, name, receipt)
+
+                    _AssertDirectory(parent, bundle_name, directory)
+                    receipt = _WriteFile(directory, _MANIFEST_NAME, _Manifest(bundle))
+                    created.append((_MANIFEST_NAME, receipt))
+                    os.fsync(directory)
+                    os.fsync(parent)
+
+                except BaseException:
+                    if directory is not None:
+                        _AssertDirectory(parent, bundle_name, directory)
+
+                        for name, receipt in reversed(created):
+                            _UnlinkFile(directory, name, receipt)
+
+                        _AssertDirectory(parent, bundle_name, directory)
+                        os.rmdir(bundle_name, dir_fd=parent)
+
+                    raise
+
+                finally:
+                    if directory is not None:
+                        os.close(directory)
+
+    except (OSError, ValueError, RecursionError):
+        raise ArtifactError("Unable to publish artifact bundle; existing bundles are never replaced") from None
+
+    return root_path / bundle_name
+
+
+def _UniqueObject(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    """Reject duplicate JSON fields at the untrusted ownership-manifest boundary."""
+
+    data: dict[str, object] = {}
+
+    for key, value in pairs:
+        if key in data:
+            raise ArtifactError("Artifact manifest contains duplicate fields")
+
+        data[key] = value
+
+    return data
+
+
+def _ValidateManifest(
+    directory: int, identity: StackIdentity, kind: str, name: str,
+) -> _BundleSnapshot:
+    """Check the complete manifest and every file before authorizing any removal."""
+
+    raw, manifest_receipt = _ReadSnapshot(directory, _MANIFEST_NAME, MAX_MANIFEST_BYTES)
+    data = RequireTable(json.loads(raw, object_pairs_hook=_UniqueObject), "artifact manifest")
+    ValidateFields(data, frozenset({"schema_version", "identity", "kind", "name", "files"}), frozenset(), "artifact manifest")
+
+    if type(data["schema_version"]) is not int or data["schema_version"] != 1:
+        raise ArtifactError("Artifact manifest schema is unsupported")
+
+    if ParseIdentity(data["identity"]) != identity or data["kind"] != kind or data["name"] != name:
+        raise ArtifactError("Artifact manifest does not match the expected ownership")
+
+    files = data["files"]
+
+    if not isinstance(files, list) or not 1 <= len(files) <= MAX_BUNDLE_FILES:
+        raise ArtifactError("Artifact manifest must contain 1..8 file entries")
+
+    names: list[str] = []
+    snapshots: list[_OwnedFile] = []
+    total_size = 0
+
+    for raw_file in files:
+        item = RequireTable(raw_file, "artifact entry")
+        ValidateFields(item, frozenset({"name", "size", "sha256", "sensitive"}), frozenset(), "artifact entry")
+        filename, size, digest = item["name"], item["size"], item["sha256"]
+
+        if not isinstance(filename, str) or _FILE_PATTERN.fullmatch(filename) is None or filename == _MANIFEST_NAME:
+            raise ArtifactError("Artifact manifest contains an unsafe filename")
+
+        if type(size) is not int or not 1 <= size <= MAX_ARTIFACT_BYTES or type(item["sensitive"]) is not bool:
+            raise ArtifactError("Artifact manifest contains an invalid size or sensitivity")
+
+        if not isinstance(digest, str) or re.fullmatch(r"[a-f0-9]{64}", digest) is None:
+            raise ArtifactError("Artifact manifest contains an invalid digest")
+
+        content, receipt = _ReadSnapshot(directory, filename, MAX_ARTIFACT_BYTES)
+
+        if len(content) != size or hashlib.sha256(content).hexdigest() != digest:
+            raise ArtifactError("Artifact content differs from its owned manifest")
+
+        names.append(filename)
+        snapshots.append(_OwnedFile(filename, content, receipt))
+        total_size += size
+
+    if len(set(names)) != len(names) or total_size > MAX_BUNDLE_BYTES:
+        raise ArtifactError("Artifact manifest has duplicates or exceeds its total size limit")
+
+    if set(os.listdir(directory)) != {*names, _MANIFEST_NAME}:
+        raise ArtifactError("Artifact bundle contains unowned files; cleanup is refused")
+
+    return _BundleSnapshot(tuple(snapshots), manifest_receipt)
+
+
+def ReadOwnedArtifactFile(
+    path: str | Path, identity: StackIdentity, *, kind: str, name: str,
+) -> bytes:
+    """Authorize one exact file through the complete unchanged bundle ownership manifest."""
+
+    if not isinstance(identity, StackIdentity) or not isinstance(kind, str) or kind not in {"server", "device"}:
+        raise ArtifactError("Artifact read requires explicit identity and bundle kind")
+
+    ValidateName(name, "artifact name")
+    artifact_path = Path(path)
+
+    if artifact_path.parent.name != f"{kind}-{name}":
+        raise ArtifactError("Artifact path does not match the expected bundle name")
+
+    try:
+        _ValidatePath(artifact_path)
+
+        with _Directory(artifact_path.parent) as directory:
+            snapshot = _ValidateManifest(directory, identity, kind, name)
+            file = next((item for item in snapshot.files if item.name == artifact_path.name), None)
+
+            if file is None:
+                raise ArtifactError("Artifact filename is not owned by its bundle manifest")
+
+            return file.content
+
+    except (OSError, ValueError, RecursionError):
+        raise ArtifactError("Unable to read an unchanged owned artifact bundle") from None
+
+
+def RemoveArtifactBundle(
+    root: str | Path, identity: StackIdentity, *, kind: str, name: str,
+    expected_bundle: ArtifactBundle | None = None,
+) -> bool:
+    """Remove unchanged owned files, optionally binding cleanup to exact caller-expected content."""
+
+    if not isinstance(identity, StackIdentity) or not isinstance(kind, str) or kind not in {"server", "device"}:
+        raise ArtifactError("Artifact removal requires explicit identity and bundle kind")
+
+    ValidateName(name, "artifact name")
+
+    if expected_bundle is not None and (
+        not isinstance(expected_bundle, ArtifactBundle)
+        or expected_bundle.identity != identity or expected_bundle.kind != kind
+        or expected_bundle.name != name
+    ):
+        raise ArtifactError("Expected cleanup bundle must match the complete requested ownership")
+
+    root_path = Path(root)
+    bundle_name = f"{kind}-{name}"
+
+    try:
+        _ValidatePath(root_path)
+
+        if not root_path.exists():
+            return False
+
+        with _Directory(root_path) as parent:
+            with _BundleLock(parent, bundle_name):
+                try:
+                    descriptor = os.open(bundle_name, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0), dir_fd=parent)
+
+                except FileNotFoundError:
+                    return False
+
+                try:
+                    _RequireOwned(os.fstat(descriptor), directory=True)
+                    snapshot = _ValidateManifest(descriptor, identity, kind, name)
+
+                    if expected_bundle is not None and (
+                        {item.name: item.content for item in snapshot.files}
+                        != {item.name: item.content for item in expected_bundle.files}
+                        or snapshot.manifest.sha256
+                        != hashlib.sha256(_Manifest(expected_bundle)).hexdigest()
+                    ):
+                        raise ArtifactError("Artifact bundle differs from the expected cleanup content")
+
+                    _AssertDirectory(parent, bundle_name, descriptor)
+
+                    for file in snapshot.files:
+                        _AssertFile(descriptor, file.name, file.receipt)
+
+                    _AssertFile(descriptor, _MANIFEST_NAME, snapshot.manifest)
+
+                    for file in snapshot.files:
+                        _AssertDirectory(parent, bundle_name, descriptor)
+                        _UnlinkFile(descriptor, file.name, file.receipt)
+
+                    _UnlinkFile(descriptor, _MANIFEST_NAME, snapshot.manifest)
+                    os.fsync(descriptor)
+                    _AssertDirectory(parent, bundle_name, descriptor)
+                    os.rmdir(bundle_name, dir_fd=parent)
+
+                finally:
+                    os.close(descriptor)
+
+                os.fsync(parent)
+
+    except (OSError, ValueError, RecursionError):
+        raise ArtifactError("Unable to remove a valid owned artifact bundle; partial cleanup may require recovery") from None
+
+    return True