agentbundle 0.57.0__tar.gz → 0.58.1__tar.gz

{agentbundle-0.57.0/agentbundle.egg-info → agentbundle-0.58.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.57.0
+Version: 0.58.1
 Summary: npm for your coding agent. Install packs of skills, subagents, and hooks into any repo, for every major agent.
 Author-email: eugenelim <eugenelim@users.noreply.github.com>
 License-Expression: Apache-2.0 OR MIT
@@ -35,6 +35,20 @@ python -m pip install agentbundle
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
 
+## What's new in 0.58.1
+
+The workspace MCP bridge understands supervisor runs. While a spec has a
+supervisor status file, `workspace_status` shows that run's id, stage, and
+`run_active` signal. A pending human question appears only as framed untrusted
+text that has passed a content-safety check, or as a fixed placeholder. A
+status file that is a link, oversized, or malformed shows no run and no gate.
+
+## What's new in 0.58.0
+
+The shared file-safety helper gains `write_confined_regular_file`, which creates
+or updates a file inside a root without following links and restores the
+original bytes if a write fails.
+
 ## What's new in 0.57.0
 
 `install` and `upgrade` now print the steps to move to a renamed pack when the

{agentbundle-0.57.0 → agentbundle-0.58.1}/README-pypi.md

@@ -14,6 +14,20 @@ python -m pip install agentbundle
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
 
+## What's new in 0.58.1
+
+The workspace MCP bridge understands supervisor runs. While a spec has a
+supervisor status file, `workspace_status` shows that run's id, stage, and
+`run_active` signal. A pending human question appears only as framed untrusted
+text that has passed a content-safety check, or as a fixed placeholder. A
+status file that is a link, oversized, or malformed shows no run and no gate.
+
+## What's new in 0.58.0
+
+The shared file-safety helper gains `write_confined_regular_file`, which creates
+or updates a file inside a root without following links and restores the
+original bytes if a write fails.
+
 ## What's new in 0.57.0
 
 `install` and `upgrade` now print the steps to move to a renamed pack when the

agentbundle-0.58.1/agentbundle/_data/_content_safety.py

@@ -0,0 +1,419 @@
+"""_content_safety — content-safety guard for durable semantic writer boundaries.
+
+Accepts a named profile and payload bytes; returns a typed ContentSafetyDecision
+without persisting anything. Standard library only.
+
+Every durable semantic writer and replay boundary is registered in
+SLICE_1_WRITER_BOUNDARIES before use; a missing or unknown profile refuses
+without persisting payload bytes. The registered writer boundary table names
+the same set and the same profiles.
+
+Rejected payload bytes, excerpts, and content-derived hashes never leave this
+module; accepted free text is returned as typed UntrustedData for consumers.
+The inert wrapper signals that the value must not be concatenated into system
+instructions, commands, tool calls, paths, approvals, or authority.
+
+Classification vocabulary (content-safety-policy.v1):
+  public, repository-internal  — may persist as bounded Git text
+  restricted                   — requires a controlled reference; cannot persist
+  credential, personal         — rejected immediately; producer-declared guard
+  unknown                      — rejected as unknown-class
+
+Python 3.11+ standard library only. No third-party imports, no packaging, no
+installation.
+"""
+
+import hashlib
+import re
+from dataclasses import dataclass
+from typing import ClassVar, Final
+
+__all__ = [
+    "ContentSafetyDecision",
+    "UntrustedData",
+    "POLICY_VERSION",
+    "BOUNDARY_PROFILES",
+    "SLICE_1_WRITER_BOUNDARIES",
+    "check_content_safety",
+    "wrap_as_untrusted",
+]
+
+# ── Policy identity ──────────────────────────────────────────────────────────
+
+# Stable version identifier for this policy, matching content-safety-policy.v1.
+POLICY_VERSION: Final[str] = "slice-1.v1"
+
+# ── Boundary profile definitions ─────────────────────────────────────────────
+#
+# Per-profile size and shape limits for each content-safety boundary profile.
+# Keys: profile names used in the semantic boundary and writer boundary tables.
+# Every key in SLICE_1_WRITER_BOUNDARIES must map to a key here.
+BOUNDARY_PROFILES: Final[dict[str, dict]] = {
+    # 64 KiB: allowlisted identifiers, enums, digests, numbers, repo-relative paths
+    "structured-control": {
+        "max_bytes": 64 * 1024,
+    },
+    # 64 KiB: embedded evidence; raw output is a controlled reference, never embedded
+    "evidence-embedded-record": {
+        "max_bytes": 64 * 1024,
+    },
+    # 1 MiB total, 64 KiB per free-text field: natural prose is UntrustedData
+    "review-report": {
+        "max_total_bytes": 1 * 1024 * 1024,
+        "max_free_text_bytes": 64 * 1024,
+    },
+    # 256 KiB, 1 000 conflict paths: paths are repository-relative and classified
+    "integration-diagnostic": {
+        "max_bytes": 256 * 1024,
+    },
+    # 64 KiB: raw transcripts and unbounded tool output reject
+    "knowledge-observation": {
+        "max_bytes": 64 * 1024,
+    },
+    # Existing result byte cap: uses admission and scanner policy
+    "product-addition": {},
+}
+
+# ── Writer boundary registry ──────────────────────────────────────────────────
+#
+# The SINGLE declared registry that every durable semantic writer and replay
+# boundary must use. A writer that bypasses this registry or uses a profile
+# other than the one assigned here violates the content-safety contract.
+#
+# The registered writer boundary table names this same set and these same
+# profiles. The roster test asserts both agree.
+#
+# Policy-import writers: initial-plan-review.v1, approval-record.v1, reviewed-execution-envelope.v1
+# Evidence-store writers: semantic-evidence-transaction.v1 (frame), evidence-receipt.v1,
+#                         evidence-supersession.v1
+# Security-event writer: security-event.v1
+# Shadow facade writers: delivery-subject.v1, acceptance-property.v1,
+#                        acceptance-verdict.v1
+SLICE_1_WRITER_BOUNDARIES: Final[dict[str, str]] = {
+    "initial-plan-review.v1": "structured-control",
+    "approval-record.v1": "structured-control",
+    "reviewed-execution-envelope.v1": "structured-control",
+    "security-event.v1": "structured-control",
+    "semantic-evidence-transaction.v1": "structured-control",
+    "evidence-receipt.v1": "evidence-embedded-record",
+    "evidence-supersession.v1": "evidence-embedded-record",
+    "delivery-subject.v1": "structured-control",
+    "acceptance-property.v1": "structured-control",
+    "acceptance-verdict.v1": "structured-control",
+}
+
+# ── Classification vocabulary ─────────────────────────────────────────────────
+
+# Only these two classes may persist as bounded Git text.
+_PERSISTABLE_CLASSES: Final[frozenset[str]] = frozenset(
+    {"public", "repository-internal"}
+)
+_CREDENTIAL_CLASS: Final[str] = "credential"
+_PERSONAL_CLASS: Final[str] = "personal"
+
+# ── C0 control-character scanner ─────────────────────────────────────────────
+#
+# Rejects C0 control characters (0x00–0x1F) and DEL (0x7F), except:
+#   HT (0x09), LF (0x0A), CR (0x0D) — valid whitespace in text content.
+# ESC and other C0 survivors are dangerous in terminal-captured streams.
+_CONTROL_RE: Final[re.Pattern[str]] = re.compile(
+    r"[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]"
+)
+
+# ── Credential scanner patterns ───────────────────────────────────────────────
+#
+# High-confidence token shapes from the required scanner corpus.
+# Matching any pattern returns rejected-credential without payload retention.
+_CREDENTIAL_PATTERNS: Final[list[re.Pattern[str]]] = [
+    # GitHub personal access tokens (classic 40-char suffix form)
+    re.compile(r"ghp_[A-Za-z0-9]{36,}"),
+    # GitHub fine-grained PATs
+    re.compile(r"github_pat_[A-Za-z0-9_]{76,}"),
+    # AWS access key IDs
+    re.compile(r"AKIA[0-9A-Z]{16}"),
+    # Generic high-entropy API/secret/access-token assignments (case-insensitive)
+    re.compile(r"(?i)api[-_]?key\s*[:=]\s*[A-Za-z0-9/+_.\-]{20,}"),
+    re.compile(r"(?i)secret[-_]?key\s*[:=]\s*[A-Za-z0-9/+_.\-]{20,}"),
+    re.compile(r"(?i)access[-_]?token\s*[:=]\s*[A-Za-z0-9/+_.\-]{20,}"),
+]
+
+# ── Personal-data scanner patterns ────────────────────────────────────────────
+#
+# Direct personal identifiers from the required scanner corpus.
+# Matching any pattern returns rejected-personal-data without payload retention.
+_PERSONAL_DATA_PATTERNS: Final[list[re.Pattern[str]]] = [
+    # Email addresses (any domain)
+    re.compile(r"[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}"),
+    # US Social Security Numbers
+    re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),
+    # US phone numbers (various formats)
+    re.compile(r"\b(?:\+1[-. ]?)?\(?\d{3}\)?[-. ]?\d{3}[-. ]?\d{4}\b"),
+]
+
+# ── Executable-structure scanner patterns ─────────────────────────────────────
+#
+# Tool-call objects, shell shebangs, and authority-shaped fields that must not
+# persist in any semantic record. These form executable or capability-granting
+# structures in the content stream.
+_EXECUTABLE_PATTERNS: Final[list[re.Pattern[str]]] = [
+    # Agentic tool-call object patterns (common in LLM APIs)
+    re.compile(r'"tool_call[s]?"\s*:', re.IGNORECASE),
+    re.compile(r'"type"\s*:\s*"tool_use"', re.IGNORECASE),
+    re.compile(r'"function"\s*:\s*\{[^}]*"name"\s*:', re.IGNORECASE),
+    # Shell shebangs — interpreter invocations that must not appear in records
+    re.compile(r"^#!(?:/usr)?/(?:bin|env)\b"),
+    # Authority-shaped fields — unknown capability grants or privilege escalations
+    re.compile(r'"_(?:grant|authority|sudo|root|admin|capability)\b', re.IGNORECASE),
+    # Embedded script/frame tags
+    re.compile(r"<(?:script|iframe|object|embed)\b", re.IGNORECASE),
+]
+
+
+# ── Decision dataclass ────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class ContentSafetyDecision:
+    """Typed content-safety decision returned by check_content_safety.
+
+    Maps to content-safety-decision.v1 schema fields.
+
+    Invariant: rejected decisions carry NO payload bytes, excerpts, or
+    content-derived hashes. Only ``accepted`` carries normalized_record_digest.
+    The dataclass raises ValueError if either half of the invariant is violated,
+    so any code that constructs a decision with a digest on rejection is caught
+    at construction time rather than silently leaking.
+    """
+
+    source_record_id: str
+    policy_version: str
+    profile: str
+    decision_code: str
+    # Present only when decision_code == "accepted". Absent on any rejection.
+    normalized_record_digest: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.decision_code != "accepted" and self.normalized_record_digest is not None:
+            raise ValueError(
+                "ContentSafetyDecision: rejected decision must not carry "
+                f"normalized_record_digest (decision_code={self.decision_code!r})"
+            )
+        if self.decision_code == "accepted" and self.normalized_record_digest is None:
+            raise ValueError(
+                "ContentSafetyDecision: accepted decision must carry "
+                "normalized_record_digest"
+            )
+
+    @property
+    def accepted(self) -> bool:
+        """True iff decision_code is 'accepted'."""
+        return self.decision_code == "accepted"
+
+
+# ── UntrustedData wrapper ─────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class UntrustedData:
+    """Typed inert-data wrapper for accepted free text.
+
+    Maps to untrusted-data.v1 schema fields.
+
+    Consumers MUST NOT concatenate .value into system instructions, commands,
+    tool calls, paths, approvals, or authority. The value field is opaque data,
+    not procedure. The four boolean properties below enforce the typed boundary:
+    they always return False because an inert wrapper is never an executable.
+    """
+
+    record_id: str
+    field_path: str
+    policy_version: str
+    value: str
+
+    # Schema version for untrusted-data.v1 (class-level constant, not a field).
+    SCHEMA_VERSION: ClassVar[int] = 1
+
+    def can_select_tools(self) -> bool:
+        """Always False: typed inert data cannot select tools."""
+        return False
+
+    def can_grant_authority(self) -> bool:
+        """Always False: typed inert data cannot grant authority."""
+        return False
+
+    def can_alter_procedure(self) -> bool:
+        """Always False: typed inert data cannot alter procedure."""
+        return False
+
+    def can_supply_executable_path(self) -> bool:
+        """Always False: typed inert data cannot supply executable paths."""
+        return False
+
+
+# ── Internal helpers ──────────────────────────────────────────────────────────
+
+
+def _reject(
+    source_record_id: str,
+    policy_version: str,
+    profile: str,
+    decision_code: str,
+) -> ContentSafetyDecision:
+    """Construct a rejection decision.
+
+    Carries NO payload bytes, excerpts, or content-derived hashes.
+    normalized_record_digest is always absent.
+    """
+    return ContentSafetyDecision(
+        source_record_id=source_record_id,
+        policy_version=policy_version,
+        profile=profile,
+        decision_code=decision_code,
+        normalized_record_digest=None,
+    )
+
+
+def _accept(
+    source_record_id: str,
+    policy_version: str,
+    profile: str,
+    normalized_bytes: bytes,
+) -> ContentSafetyDecision:
+    """Construct an acceptance decision.
+
+    The normalized_record_digest is the SHA-256 of the normalized bytes,
+    prefixed with 'sha256:'. The caller supplies normalized bytes, not raw.
+    """
+    digest = "sha256:" + hashlib.sha256(normalized_bytes).hexdigest()
+    return ContentSafetyDecision(
+        source_record_id=source_record_id,
+        policy_version=policy_version,
+        profile=profile,
+        decision_code="accepted",
+        normalized_record_digest=digest,
+    )
+
+
+def _profile_max_bytes(profile_cfg: dict) -> int | None:
+    """Return the byte cap for the given profile config, or None if uncapped."""
+    if "max_bytes" in profile_cfg:
+        return profile_cfg["max_bytes"]
+    if "max_total_bytes" in profile_cfg:
+        return profile_cfg["max_total_bytes"]
+    return None
+
+
+# ── Public guard entry point ──────────────────────────────────────────────────
+
+
+def check_content_safety(
+    profile: str,
+    payload: bytes,
+    *,
+    source_record_id: str,
+    classification: str = "public",
+) -> ContentSafetyDecision:
+    """Apply the named content-safety profile to payload bytes.
+
+    Returns a ContentSafetyDecision without persisting anything.
+    On rejection, carries NO payload bytes, excerpts, or content-derived hashes.
+    On acceptance, carries a SHA-256 digest of the normalized bytes.
+
+    Checks, in order:
+      1. Profile lookup       — unknown profile: rejected-missing-profile
+      2. Classification check — credential: rejected-credential
+                               personal: rejected-personal-data
+                               restricted or unknown: rejected-unknown-class
+      3. UTF-8 decoding       — invalid encoding: rejected-encoding
+      4. Control characters   — C0 except HT/LF/CR and DEL: rejected-encoding
+      5. Size limit           — over profile cap: rejected-size
+      6. Executable structure — tool-call, shebang, authority field: rejected-structure
+      7. Credential scanner   — high-confidence token patterns: rejected-credential
+      8. Personal-data scanner — direct identifiers: rejected-personal-data
+      9. Accept               — returns digest of CRLF-normalized UTF-8 bytes
+
+    Args:
+        profile:          Named boundary profile from BOUNDARY_PROFILES.
+        payload:          Raw bytes to evaluate. Never stored on rejection.
+        source_record_id: Stable identity of the source record.
+        classification:   Producer-declared content class. Defaults to 'public'.
+                         Only 'public' and 'repository-internal' may persist.
+    """
+    # Step 1 — Profile lookup. An unknown profile blocks without inspecting payload.
+    profile_cfg = BOUNDARY_PROFILES.get(profile)
+    if profile_cfg is None:
+        return _reject(source_record_id, POLICY_VERSION, profile, "rejected-missing-profile")
+
+    # Step 2 — Classification check. Reject non-persistable classes immediately.
+    if classification not in _PERSISTABLE_CLASSES:
+        if classification == _CREDENTIAL_CLASS:
+            return _reject(source_record_id, POLICY_VERSION, profile, "rejected-credential")
+        if classification == _PERSONAL_CLASS:
+            return _reject(source_record_id, POLICY_VERSION, profile, "rejected-personal-data")
+        # restricted and any unknown class use the unknown-class code.
+        return _reject(source_record_id, POLICY_VERSION, profile, "rejected-unknown-class")
+
+    # Step 3 — UTF-8 encoding check. Payload must decode without error.
+    try:
+        text = payload.decode("utf-8", errors="strict")
+    except UnicodeDecodeError:
+        return _reject(source_record_id, POLICY_VERSION, profile, "rejected-encoding")
+
+    # Step 4 — Control-character check. C0 except HT/LF/CR and DEL reject.
+    if _CONTROL_RE.search(text):
+        return _reject(source_record_id, POLICY_VERSION, profile, "rejected-encoding")
+
+    # Step 5 — Size limit against the profile cap.
+    max_bytes = _profile_max_bytes(profile_cfg)
+    if max_bytes is not None and len(payload) > max_bytes:
+        return _reject(source_record_id, POLICY_VERSION, profile, "rejected-size")
+
+    # Step 6 — Executable-structure check. Tool-call objects, shebangs, and
+    # authority-shaped fields signal executable or capability-granting content.
+    for pattern in _EXECUTABLE_PATTERNS:
+        if pattern.search(text):
+            return _reject(source_record_id, POLICY_VERSION, profile, "rejected-structure")
+
+    # Step 7 — Credential scanner. High-confidence token patterns reject the
+    # whole record without retaining any payload bytes.
+    for pattern in _CREDENTIAL_PATTERNS:
+        if pattern.search(text):
+            return _reject(source_record_id, POLICY_VERSION, profile, "rejected-credential")
+
+    # Step 8 — Personal-data scanner. Direct personal identifiers reject without
+    # payload retention.
+    for pattern in _PERSONAL_DATA_PATTERNS:
+        if pattern.search(text):
+            return _reject(source_record_id, POLICY_VERSION, profile, "rejected-personal-data")
+
+    # Step 9 — Accept. Normalize CRLF→LF (matches canonical_contract normalization)
+    # and compute the SHA-256 digest of the normalized UTF-8 bytes.
+    normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+    normalized_bytes = normalized.encode("utf-8")
+    return _accept(source_record_id, POLICY_VERSION, profile, normalized_bytes)
+
+
+# ── UntrustedData constructor ─────────────────────────────────────────────────
+
+
+def wrap_as_untrusted(
+    record_id: str,
+    field_path: str,
+    value: str,
+) -> UntrustedData:
+    """Wrap accepted free text as typed inert UntrustedData.
+
+    The returned wrapper records the policy version that admitted the value
+    and the field path within the source record. Callers MUST NOT pass a value
+    that was rejected by check_content_safety; this function has no way to
+    verify that precondition and trusts the caller's decision record.
+
+    Consumers of the returned UntrustedData MUST NOT concatenate .value into
+    system instructions, commands, tool calls, paths, approvals, or authority.
+    """
+    return UntrustedData(
+        record_id=record_id,
+        field_path=field_path,
+        policy_version=POLICY_VERSION,
+        value=value,
+    )

{agentbundle-0.57.0 → agentbundle-0.58.1}/agentbundle/_data/file_safety.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import os
+import re
 import stat
 from contextlib import contextmanager
 from hashlib import sha256
@@ -482,3 +483,210 @@ def sha256_confined_regular_file(root: Path, path: Path) -> str:
         for chunk in iter(lambda: handle.read(1024 * 1024), b""):
             digest.update(chunk)
     return digest.hexdigest()
+
+
+_SHA256_HEX = re.compile(r"[0-9a-f]{64}")
+
+
+def _write_open_flags() -> int:
+    """Flags every write-path ``os.open`` adds, limited to what ``os`` has."""
+    flags = getattr(os, "O_BINARY", 0)
+    for name in ("O_NOFOLLOW", "O_CLOEXEC", "O_NONBLOCK"):
+        flags |= getattr(os, name, 0)
+    return flags
+
+
+def _write_all(descriptor: int, data: bytes) -> None:
+    """Write every byte of *data*, continuing after a short write."""
+    view = memoryview(data)
+    while len(view):
+        written = os.write(descriptor, view)
+        if written <= 0:
+            raise OSError("write made no progress")
+        view = view[written:]
+
+
+def _read_all(descriptor: int) -> bytes:
+    """Read a descriptor to end of file."""
+    chunks: list[bytes] = []
+    while True:
+        chunk = os.read(descriptor, 1024 * 1024)
+        if not chunk:
+            return b"".join(chunks)
+        chunks.append(chunk)
+
+
+def _create_confined_file(
+    root: Path,
+    path: Path,
+    data: bytes,
+    *,
+    relative: str,
+    parent_fd: int | None,
+    leaf: str,
+) -> None:
+    """Create *path* exclusively; remove only the file this call created."""
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | _write_open_flags()
+    try:
+        if parent_fd is None:
+            descriptor = os.open(path, flags, 0o600)
+        else:
+            descriptor = os.open(leaf, flags, 0o600, dir_fd=parent_fd)
+    except OSError as exc:
+        raise UnsafeContentError(
+            f"target cannot be created safely: {relative}"
+        ) from exc
+    identity: tuple[int, int] | None = None
+    try:
+        try:
+            created = os.fstat(descriptor)
+            identity = (created.st_dev, created.st_ino)
+            _validate_regular_file_stat(created, relative)
+            if parent_fd is None:
+                # No byte is written until the created path is known to be
+                # inside the root and to be the file this call created.
+                path.resolve(strict=True).relative_to(root.resolve(strict=True))
+                named = path.lstat()
+                if (named.st_dev, named.st_ino) != identity:
+                    raise UnsafeContentError(
+                        f"target changed while creating: {relative}"
+                    )
+            _write_all(descriptor, data)
+            os.fsync(descriptor)
+        except (UnsafeContentError, OSError, RuntimeError, ValueError) as exc:
+            _remove_created(path, parent_fd, leaf, identity)
+            if isinstance(exc, UnsafeContentError):
+                raise
+            raise UnsafeContentError(
+                f"target cannot be written safely: {relative}"
+            ) from exc
+    finally:
+        os.close(descriptor)
+
+
+def _remove_created(
+    path: Path, parent_fd: int | None, leaf: str, identity: tuple[int, int] | None
+) -> None:
+    """Unlink the leaf only when it still has the created file's identity."""
+    if identity is None:
+        return
+    try:
+        if parent_fd is None:
+            named = path.lstat()
+            if (named.st_dev, named.st_ino) == identity:
+                path.unlink()
+        else:
+            named = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
+            if (named.st_dev, named.st_ino) == identity:
+                os.unlink(leaf, dir_fd=parent_fd)
+    except OSError:
+        pass
+
+
+def _update_confined_file(
+    root: Path,
+    path: Path,
+    data: bytes,
+    expect_sha256: str,
+    *,
+    relative: str,
+    parent_fd: int | None,
+    leaf: str,
+) -> None:
+    """Rewrite *path* in place when its bytes still hash to *expect_sha256*."""
+    flags = os.O_RDWR | _write_open_flags()
+    try:
+        if parent_fd is None:
+            before = path.lstat()
+            _validate_regular_file_stat(before, relative)
+            path.resolve(strict=True).relative_to(root.resolve(strict=True))
+            descriptor = os.open(path, flags)
+        else:
+            before = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
+            _validate_regular_file_stat(before, relative)
+            descriptor = os.open(leaf, flags, dir_fd=parent_fd)
+    except UnsafeContentError:
+        raise
+    except (OSError, RuntimeError, ValueError) as exc:
+        raise UnsafeContentError(
+            f"target cannot be opened safely: {relative}"
+        ) from exc
+    try:
+        try:
+            after = os.fstat(descriptor)
+            _validate_regular_file_stat(after, relative)
+            if (before.st_dev, before.st_ino) != (after.st_dev, after.st_ino):
+                raise UnsafeContentError(f"target changed while opening: {relative}")
+            original = _read_all(descriptor)
+        except OSError as exc:
+            raise UnsafeContentError(
+                f"target cannot be read safely: {relative}"
+            ) from exc
+        if sha256(original).hexdigest() != expect_sha256:
+            raise UnsafeContentError(f"target does not match its digest: {relative}")
+        try:
+            os.lseek(descriptor, 0, os.SEEK_SET)
+            _write_all(descriptor, data)
+            os.ftruncate(descriptor, len(data))
+            os.fsync(descriptor)
+        except OSError as exc:
+            try:
+                os.lseek(descriptor, 0, os.SEEK_SET)
+                _write_all(descriptor, original)
+                os.ftruncate(descriptor, len(original))
+                os.fsync(descriptor)
+            except OSError as restore_exc:
+                raise UnsafeContentError(
+                    f"target write failed and was not restored: {relative}"
+                ) from restore_exc
+            raise UnsafeContentError(
+                f"target cannot be written safely: {relative}"
+            ) from exc
+    finally:
+        os.close(descriptor)
+
+
+def write_confined_regular_file(
+    root: Path,
+    path: Path,
+    data: bytes,
+    *,
+    expect_sha256: str | None,
+) -> None:
+    """Write *data* to a confined, no-follow, single-link regular file.
+
+    ``expect_sha256=None`` creates the target exclusively, so anything already
+    present (a dangling link included) is refused.  Otherwise the target must
+    exist and its bytes, read from the same descriptor that is then written,
+    must hash to ``expect_sha256`` (lowercase hex); the file is rewritten in
+    place so its identity is kept, and restored from the bytes read if a write,
+    truncate or sync fails.  A failed create removes only the file it created.
+    Every refusal is an ``UnsafeContentError``; a non-``bytes`` *data* or a
+    malformed digest is a ``ValueError``.
+    """
+    if not isinstance(data, bytes):
+        raise ValueError("data must be bytes")
+    if expect_sha256 is not None and (
+        not isinstance(expect_sha256, str)
+        or _SHA256_HEX.fullmatch(expect_sha256) is None
+    ):
+        raise ValueError("expect_sha256 must be 64 lowercase hex characters or None")
+    try:
+        relative = path.relative_to(root).as_posix()
+    except ValueError as exc:
+        raise UnsafeContentError("target path is outside its declared root") from exc
+    with _open_confined_parent(root, path, relative=relative) as (parent_fd, leaf):
+        if expect_sha256 is None:
+            _create_confined_file(
+                root, path, data, relative=relative, parent_fd=parent_fd, leaf=leaf
+            )
+        else:
+            _update_confined_file(
+                root,
+                path,
+                data,
+                expect_sha256,
+                relative=relative,
+                parent_fd=parent_fd,
+                leaf=leaf,
+            )