mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/credential_store.py

@@ -0,0 +1,1055 @@
+"""Crash-safe protected credential envelopes and local store coordination.
+
+Raw device credentials are permitted only in :class:`ProtectedCredential` values and backend
+payloads.  Every representation and every error in this module is deliberately allowlisted; do
+not replace the explicit encoders with generic dataclass serialization.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import secrets
+import stat
+import time
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, Self
+
+from mostlyright.data_harness.canonical import (
+    CanonicalJSONError,
+    canonical_json_bytes,
+    parse_canonical_json,
+)
+
+CREDENTIAL_ENVELOPE_SCHEMA = "mr-data-credentials.v2"
+MAX_CREDENTIAL_ENVELOPE_BYTES = 64 * 1024
+SECURE_FILE_NAME = "credentials.secure"
+LOCK_FILE_NAME = ".credential.lock"
+
+_STATES = frozenset(
+    {"active", "login_pending", "revoke_pending", "cleanup_pending", "logout_pending"}
+)
+_OPERATIONS = frozenset({"login", "rotate"})
+_CREDENTIAL_FIELDS = frozenset(
+    {"cloud_url", "key_id", "prefix", "last_four", "device_name", "created_at", "raw_key"}
+)
+_LEASE_FIELDS = frozenset(
+    {"nonce", "base_generation", "operation", "requested_device_name", "created_at"}
+)
+
+
+class CredentialStoreError(RuntimeError):
+    """A typed, secret-free protected-store refusal."""
+
+    def __init__(self, code: str, detail: str) -> None:
+        self.code = code
+        self.detail = detail
+        super().__init__(f"{code}: {detail}")
+
+
+@dataclass(frozen=True)
+class ProtectedCredential:
+    """One secret-bearing device credential with an always-redacted representation."""
+
+    cloud_url: str
+    key_id: str
+    prefix: str
+    last_four: str
+    device_name: str
+    created_at: str
+    raw_key: str
+
+    def __post_init__(self) -> None:
+        if any(
+            not isinstance(getattr(self, field), str) or not getattr(self, field)
+            for field in _CREDENTIAL_FIELDS
+        ):
+            raise CredentialStoreError(
+                "CREDENTIAL_STORE_CORRUPT", "the protected credential has an invalid field"
+            )
+
+    def __repr__(self) -> str:
+        return (
+            "ProtectedCredential("
+            f"cloud_url={self.cloud_url!r}, key_id={self.key_id!r}, prefix={self.prefix!r}, "
+            f"last_four={self.last_four!r}, device_name={self.device_name!r}, "
+            f"created_at={self.created_at!r}, raw_key='<redacted>')"
+        )
+
+    def _payload(self) -> dict[str, str]:
+        return {
+            "cloud_url": self.cloud_url,
+            "key_id": self.key_id,
+            "prefix": self.prefix,
+            "last_four": self.last_four,
+            "device_name": self.device_name,
+            "created_at": self.created_at,
+            "raw_key": self.raw_key,
+        }
+
+    @classmethod
+    def _from_payload(cls, value: object) -> Self:
+        if not isinstance(value, dict) or set(value) != _CREDENTIAL_FIELDS:
+            raise _corrupt()
+        if any(
+            not isinstance(value[field], str) or not value[field] for field in _CREDENTIAL_FIELDS
+        ):
+            raise _corrupt()
+        return cls(**{field: value[field] for field in _CREDENTIAL_FIELDS})
+
+
+@dataclass(frozen=True)
+class CredentialLease:
+    """The durable owner of one device authorization flow for one store generation."""
+
+    nonce: str
+    base_generation: int
+    operation: str
+    requested_device_name: str
+    created_at: str
+
+    def __post_init__(self) -> None:
+        if (
+            not isinstance(self.nonce, str)
+            or not self.nonce
+            or type(self.base_generation) is not int
+            or self.base_generation < 0
+            or self.operation not in _OPERATIONS
+            or not isinstance(self.requested_device_name, str)
+            or not self.requested_device_name
+            or not isinstance(self.created_at, str)
+            or not self.created_at
+        ):
+            raise CredentialStoreError(
+                "CREDENTIAL_STORE_CORRUPT", "the protected login lease is invalid"
+            )
+
+    def __repr__(self) -> str:
+        return (
+            "CredentialLease("
+            f"nonce={self.nonce!r}, base_generation={self.base_generation!r}, "
+            f"operation={self.operation!r}, requested_device_name={self.requested_device_name!r}, "
+            f"created_at={self.created_at!r})"
+        )
+
+    def _payload(self) -> dict[str, str | int]:
+        return {
+            "nonce": self.nonce,
+            "base_generation": self.base_generation,
+            "operation": self.operation,
+            "requested_device_name": self.requested_device_name,
+            "created_at": self.created_at,
+        }
+
+    @classmethod
+    def _from_payload(cls, value: object) -> Self:
+        if not isinstance(value, dict) or set(value) != _LEASE_FIELDS:
+            raise _corrupt()
+        try:
+            return cls(
+                nonce=value["nonce"],
+                base_generation=value["base_generation"],
+                operation=value["operation"],
+                requested_device_name=value["requested_device_name"],
+                created_at=value["created_at"],
+            )
+        except (CredentialStoreError, TypeError):
+            raise _corrupt() from None
+
+
+@dataclass(frozen=True)
+class CredentialEnvelope:
+    """One exact state in the closed credential transaction protocol."""
+
+    generation: int
+    state: str
+    active: ProtectedCredential | None = None
+    prior: ProtectedCredential | None = None
+    login_pending: CredentialLease | None = None
+
+    def __post_init__(self) -> None:
+        if type(self.generation) is not int or self.generation < 0 or self.state not in _STATES:
+            raise _corrupt()
+        if self.state == "active":
+            valid = self.active is not None and self.prior is None and self.login_pending is None
+        elif self.state == "login_pending":
+            lease = self.login_pending
+            valid = (
+                lease is not None
+                and self.prior is None
+                and self.generation == lease.base_generation + 1
+                and (
+                    (lease.operation == "login" and self.active is None)
+                    or (lease.operation == "rotate" and self.active is not None)
+                )
+            )
+        elif self.state in {"revoke_pending", "cleanup_pending"}:
+            valid = (
+                self.active is not None and self.prior is not None and self.login_pending is None
+            )
+        else:  # logout_pending
+            valid = self.active is not None and self.prior is None and self.login_pending is None
+        if not valid:
+            raise _corrupt()
+
+    def __repr__(self) -> str:
+        return (
+            "CredentialEnvelope("
+            f"generation={self.generation!r}, state={self.state!r}, active={self.active!r}, "
+            f"prior={self.prior!r}, login_pending={self.login_pending!r})"
+        )
+
+    @classmethod
+    def active_envelope(cls, *, generation: int, active: ProtectedCredential) -> Self:
+        return cls(generation=generation, state="active", active=active)
+
+    @classmethod
+    def login_pending_envelope(
+        cls,
+        *,
+        generation: int,
+        active: ProtectedCredential | None,
+        lease: CredentialLease,
+    ) -> Self:
+        return cls(
+            generation=generation,
+            state="login_pending",
+            active=active,
+            login_pending=lease,
+        )
+
+    @classmethod
+    def pending_remote_revoke(
+        cls,
+        *,
+        generation: int,
+        active: ProtectedCredential,
+        prior: ProtectedCredential,
+    ) -> Self:
+        return cls(
+            generation=generation,
+            state="revoke_pending",
+            active=active,
+            prior=prior,
+        )
+
+    @classmethod
+    def pending_cleanup(
+        cls,
+        *,
+        generation: int,
+        active: ProtectedCredential,
+        prior: ProtectedCredential,
+    ) -> Self:
+        return cls(
+            generation=generation,
+            state="cleanup_pending",
+            active=active,
+            prior=prior,
+        )
+
+    @classmethod
+    def pending_logout(cls, *, generation: int, active: ProtectedCredential) -> Self:
+        return cls(generation=generation, state="logout_pending", active=active)
+
+    def to_bytes(self) -> bytes:
+        payload: dict[str, object] = {
+            "schema_version": CREDENTIAL_ENVELOPE_SCHEMA,
+            "generation": self.generation,
+            "state": self.state,
+        }
+        if self.active is not None:
+            payload["active"] = self.active._payload()
+        if self.prior is not None:
+            payload["prior"] = self.prior._payload()
+        if self.login_pending is not None:
+            payload["login_pending"] = self.login_pending._payload()
+        return canonical_json_bytes(payload)
+
+    @classmethod
+    def from_bytes(cls, value: bytes | bytearray | memoryview) -> Self:
+        raw = bytes(value)
+        if len(raw) > MAX_CREDENTIAL_ENVELOPE_BYTES:
+            raise CredentialStoreError(
+                "CREDENTIAL_STORE_CORRUPT", "the protected credential envelope exceeds its limit"
+            )
+        try:
+            parsed = parse_canonical_json(raw)
+        except (CanonicalJSONError, UnicodeError, ValueError):
+            raise _corrupt() from None
+        if not isinstance(parsed, dict):
+            raise _corrupt()
+        state = parsed.get("state")
+        required = {"schema_version", "generation", "state"}
+        if state == "active" or state == "logout_pending":
+            required.add("active")
+        elif state == "login_pending":
+            required.add("login_pending")
+            if "active" in parsed:
+                required.add("active")
+        elif state in {"revoke_pending", "cleanup_pending"}:
+            required.update({"active", "prior"})
+        if set(parsed) != required or parsed.get("schema_version") != CREDENTIAL_ENVELOPE_SCHEMA:
+            raise _corrupt()
+        try:
+            return cls(
+                generation=parsed["generation"],
+                state=state,
+                active=ProtectedCredential._from_payload(parsed["active"])
+                if "active" in parsed
+                else None,
+                prior=ProtectedCredential._from_payload(parsed["prior"])
+                if "prior" in parsed
+                else None,
+                login_pending=CredentialLease._from_payload(parsed["login_pending"])
+                if "login_pending" in parsed
+                else None,
+            )
+        except (CredentialStoreError, KeyError, TypeError):
+            raise _corrupt() from None
+
+
+class CredentialBackend(Protocol):
+    """A backend that stores one opaque protected-envelope payload."""
+
+    name: str
+
+    def read(self) -> bytes | None: ...
+
+    def write(self, payload: bytes) -> None: ...
+
+    def delete(self) -> None: ...
+
+
+class SecureFileBackend:
+    """Explicit, atomic 0600 fallback backend; never selected implicitly."""
+
+    name = "secure-file"
+
+    def __init__(
+        self,
+        config_dir: Path,
+        *,
+        explicit: bool,
+        filename: str = SECURE_FILE_NAME,
+    ) -> None:
+        if explicit is not True:
+            raise CredentialStoreError(
+                "CREDENTIAL_STORE_EXPLICIT_REQUIRED",
+                "secure-file storage requires explicit selection",
+            )
+        self.config_dir = Path(config_dir)
+        if not filename or filename in {".", ".."} or Path(filename).name != filename:
+            raise CredentialStoreError(
+                "CREDENTIAL_STORE_CORRUPT", "the protected credential filename is invalid"
+            )
+        self._filename = filename
+        self.path = self.config_dir / filename
+        _ensure_private_directory(self.config_dir)
+
+    def read(self) -> bytes | None:
+        _validate_private_directory(self.config_dir)
+        try:
+            descriptor = os.open(
+                self.path,
+                os.O_RDONLY
+                | getattr(os, "O_BINARY", 0)
+                | getattr(os, "O_NONBLOCK", 0)
+                | getattr(os, "O_NOFOLLOW", 0),
+            )
+        except FileNotFoundError:
+            if os.path.lexists(self.path):
+                raise _permission_refusal() from None
+            return None
+        except OSError:
+            raise _permission_refusal() from None
+        try:
+            info = os.fstat(descriptor)
+            _validate_private_file(info, path=self.path)
+            if info.st_size > MAX_CREDENTIAL_ENVELOPE_BYTES:
+                raise CredentialStoreError(
+                    "CREDENTIAL_STORE_CORRUPT",
+                    "the protected credential envelope exceeds its limit",
+                )
+            chunks: list[bytes] = []
+            remaining = MAX_CREDENTIAL_ENVELOPE_BYTES + 1
+            while remaining:
+                chunk = os.read(descriptor, min(remaining, 16 * 1024))
+                if not chunk:
+                    break
+                chunks.append(chunk)
+                remaining -= len(chunk)
+            raw = b"".join(chunks)
+            if len(raw) > MAX_CREDENTIAL_ENVELOPE_BYTES:
+                raise CredentialStoreError(
+                    "CREDENTIAL_STORE_CORRUPT",
+                    "the protected credential envelope exceeds its limit",
+                )
+            return raw
+        except CredentialStoreError:
+            raise
+        except OSError:
+            raise CredentialStoreError(
+                "CREDENTIAL_STORE_UNAVAILABLE", "secure-file storage could not be read"
+            ) from None
+        finally:
+            os.close(descriptor)
+
+    def write(self, payload: bytes) -> None:
+        _validate_private_directory(self.config_dir)
+        if len(payload) > MAX_CREDENTIAL_ENVELOPE_BYTES:
+            raise CredentialStoreError(
+                "CREDENTIAL_STORE_CORRUPT", "the protected credential envelope exceeds its limit"
+            )
+        if os.path.lexists(self.path):
+            # Validate the current target before replacing it.  Atomic replacement is not license
+            # to overwrite a link, hardlink, foreign owner, or permissive file.
+            self.read()
+        stage_name = f".{self._filename}.{secrets.token_hex(16)}.stage"
+        stage = self.config_dir / stage_name
+        descriptor: int | None = None
+        directory_fd: int | None = None
+        try:
+            descriptor = os.open(
+                stage,
+                os.O_WRONLY
+                | os.O_CREAT
+                | os.O_EXCL
+                | getattr(os, "O_BINARY", 0)
+                | getattr(os, "O_NOFOLLOW", 0),
+                0o600,
+            )
+            if os.name == "posix":
+                os.fchmod(descriptor, 0o600)
+            offset = 0
+            while offset < len(payload):
+                written = os.write(descriptor, payload[offset:])
+                if written <= 0:
+                    raise OSError("short credential write")
+                offset += written
+            os.fsync(descriptor)
+            _validate_private_file(os.fstat(descriptor), path=stage)
+            os.close(descriptor)
+            descriptor = None
+            os.replace(stage, self.path)
+            if os.name == "posix":
+                directory_fd = os.open(
+                    self.config_dir,
+                    os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
+                )
+                os.fsync(directory_fd)
+        except CredentialStoreError:
+            raise
+        except OSError:
+            raise CredentialStoreError(
+                "CREDENTIAL_STORE_WRITE_FAILED", "secure-file storage could not be updated"
+            ) from None
+        finally:
+            if descriptor is not None:
+                os.close(descriptor)
+            if directory_fd is not None:
+                os.close(directory_fd)
+            with contextlib.suppress(OSError):
+                stage.unlink()
+
+    def delete(self) -> None:
+        if self.read() is None:
+            return
+        try:
+            self.path.unlink()
+            if os.name == "posix":
+                directory_fd = os.open(
+                    self.config_dir,
+                    os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
+                )
+                try:
+                    os.fsync(directory_fd)
+                finally:
+                    os.close(directory_fd)
+        except OSError:
+            raise CredentialStoreError(
+                "CREDENTIAL_STORE_WRITE_FAILED", "secure-file storage could not be removed"
+            ) from None
+
+
+@contextlib.contextmanager
+def credential_lock(config_dir: Path, *, timeout_seconds: float = 5.0) -> Iterator[None]:
+    """Hold the per-config-root cross-process credential lock."""
+
+    root = Path(config_dir)
+    _ensure_private_directory(root)
+    _validate_private_directory(root)
+    lock_path = root / LOCK_FILE_NAME
+    descriptor: int | None = None
+    try:
+        open_flags = os.O_RDWR | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
+        try:
+            descriptor = os.open(lock_path, open_flags | os.O_CREAT | os.O_EXCL, 0o600)
+            created = True
+        except FileExistsError:
+            descriptor = os.open(lock_path, open_flags)
+            created = False
+        if os.name == "posix" and created:
+            os.fchmod(descriptor, 0o600)
+        _validate_private_file(os.fstat(descriptor), path=lock_path)
+    except (OSError, CredentialStoreError):
+        if descriptor is not None:
+            os.close(descriptor)
+        raise CredentialStoreError(
+            "CREDENTIAL_LOCK_UNAVAILABLE", "the credential lock could not be opened"
+        ) from None
+    acquired = False
+    deadline = time.monotonic() + max(0.0, timeout_seconds)
+    try:
+        if os.name == "nt":
+            import msvcrt
+
+            if os.fstat(descriptor).st_size == 0:
+                os.write(descriptor, b"\0")
+                os.fsync(descriptor)
+            while not acquired:
+                try:
+                    os.lseek(descriptor, 0, os.SEEK_SET)
+                    msvcrt.locking(descriptor, msvcrt.LK_NBLCK, 1)
+                    acquired = True
+                except OSError:
+                    if time.monotonic() >= deadline:
+                        break
+                    time.sleep(0.01)
+        else:
+            import fcntl
+
+            while not acquired:
+                try:
+                    fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    acquired = True
+                except BlockingIOError:
+                    if time.monotonic() >= deadline:
+                        break
+                    time.sleep(0.01)
+        if not acquired:
+            raise CredentialStoreError(
+                "CREDENTIAL_LOCKED", "another credential operation holds the local lock"
+            )
+        yield
+    finally:
+        if acquired:
+            if os.name == "nt":
+                import msvcrt
+
+                os.lseek(descriptor, 0, os.SEEK_SET)
+                msvcrt.locking(descriptor, msvcrt.LK_UNLCK, 1)
+            else:
+                import fcntl
+
+                fcntl.flock(descriptor, fcntl.LOCK_UN)
+        os.close(descriptor)
+
+
+class CredentialStore:
+    """Locking generation/lease facade over one selected backend."""
+
+    def __init__(self, config_dir: Path, backend: CredentialBackend) -> None:
+        self.config_dir = Path(config_dir)
+        self.backend = backend
+
+    def _load_unlocked(self) -> CredentialEnvelope | None:
+        payload = self.backend.read()
+        return None if payload is None else CredentialEnvelope.from_bytes(payload)
+
+    def load(self) -> CredentialEnvelope | None:
+        with credential_lock(self.config_dir):
+            return self._load_unlocked()
+
+    def load_under_held_lock(self) -> CredentialEnvelope | None:
+        """Load while a caller coordinating multiple local files already holds this root's lock."""
+
+        return self._load_unlocked()
+
+    def write_under_held_lock(self, envelope: CredentialEnvelope) -> None:
+        """Write under an outer lock, resuming only a byte-identical interrupted install."""
+
+        incoming = envelope.to_bytes()
+        existing = self.backend.read()
+        if existing is not None and secrets.compare_digest(existing, incoming):
+            return
+        current = None if existing is None else CredentialEnvelope.from_bytes(existing)
+        _validate_saved_transition(
+            current,
+            envelope,
+            expected_generation=None if current is None else current.generation,
+        )
+        self.backend.write(incoming)
+
+    def replace_under_held_lock(
+        self,
+        envelope: CredentialEnvelope,
+        *,
+        expected_generation: int,
+        expected_states: frozenset[str],
+    ) -> CredentialEnvelope:
+        """Advance one known recovery transition while an outer credential lock is held.
+
+        Generic ``save`` intentionally permits only active-to-active replacement.  Lifecycle
+        orchestration needs the same generation proof for its closed pending states without
+        creating a second, unchecked backend write path.
+        """
+
+        current = self._load_unlocked()
+        if (
+            current is None
+            or current.generation != expected_generation
+            or current.state not in expected_states
+            or envelope.generation != expected_generation + 1
+        ):
+            raise CredentialStoreError(
+                "CREDENTIAL_GENERATION_CONFLICT",
+                "the protected credential transaction changed before it could advance",
+            )
+        self.backend.write(envelope.to_bytes())
+        return envelope
+
+    def delete_under_held_lock(
+        self,
+        *,
+        expected_generation: int,
+        expected_states: frozenset[str],
+    ) -> None:
+        """Remove protected material only from a caller-proved terminal cleanup state."""
+
+        current = self._load_unlocked()
+        if (
+            current is None
+            or current.generation != expected_generation
+            or current.state not in expected_states
+        ):
+            raise CredentialStoreError(
+                "CREDENTIAL_GENERATION_CONFLICT",
+                "the protected credential transaction changed before cleanup",
+            )
+        self.backend.delete()
+
+    def save(
+        self, envelope: CredentialEnvelope, *, expected_generation: int | None
+    ) -> CredentialEnvelope:
+        with credential_lock(self.config_dir):
+            current = self._load_unlocked()
+            _validate_saved_transition(current, envelope, expected_generation=expected_generation)
+            self.backend.write(envelope.to_bytes())
+            return envelope
+
+    def acquire_login_lease(
+        self,
+        *,
+        operation: str,
+        requested_device_name: str,
+        created_at: str,
+        nonce: str | None = None,
+    ) -> CredentialEnvelope:
+        with credential_lock(self.config_dir):
+            current = self._load_unlocked()
+            if current is not None and current.state == "login_pending":
+                raise CredentialStoreError(
+                    "CREDENTIAL_LOGIN_PENDING",
+                    "another device flow is pending and its mint outcome is unproved",
+                )
+            if current is not None and current.state != "active":
+                raise CredentialStoreError(
+                    "CREDENTIAL_RECOVERY_REQUIRED",
+                    "the protected credential requires recovery before another mutation",
+                )
+            base_generation = 0 if current is None else current.generation
+            active = None if current is None else current.active
+            lease = CredentialLease(
+                nonce=nonce or secrets.token_urlsafe(32),
+                base_generation=base_generation,
+                operation=operation,
+                requested_device_name=requested_device_name,
+                created_at=created_at,
+            )
+            pending = CredentialEnvelope.login_pending_envelope(
+                generation=base_generation + 1,
+                active=active,
+                lease=lease,
+            )
+            self.backend.write(pending.to_bytes())
+            return pending
+
+    def complete_login_lease(
+        self, *, nonce: str, minted: ProtectedCredential
+    ) -> CredentialEnvelope:
+        with credential_lock(self.config_dir):
+            current = self._load_unlocked()
+            lease = None if current is None else current.login_pending
+            if (
+                current is None
+                or current.state != "login_pending"
+                or lease is None
+                or lease.nonce != nonce
+                or current.generation != lease.base_generation + 1
+            ):
+                raise CredentialStoreError(
+                    "CREDENTIAL_LEASE_CONFLICT",
+                    "the device flow no longer owns the protected credential generation",
+                )
+            if current.active is None:
+                installed = CredentialEnvelope.active_envelope(
+                    generation=current.generation + 1,
+                    active=minted,
+                )
+            else:
+                installed = CredentialEnvelope.pending_remote_revoke(
+                    generation=current.generation + 1,
+                    active=minted,
+                    prior=current.active,
+                )
+            self.backend.write(installed.to_bytes())
+            # Durability proof belongs inside the same lock as the install.
+            # Once this method returns, another process may legitimately
+            # recover this generation or acquire the next lease; callers must
+            # never reinterpret that later drift as a failed mint persistence.
+            if self._load_unlocked() != installed:
+                raise CredentialStoreError(
+                    "CREDENTIAL_STORE_READBACK_FAILED",
+                    "the replacement could not be verified",
+                )
+            return installed
+
+    def recover_login_lease_local_only(self) -> dict[str, str]:
+        with credential_lock(self.config_dir):
+            current = self._load_unlocked()
+            if current is None or current.state != "login_pending":
+                raise CredentialStoreError(
+                    "CREDENTIAL_RECOVERY_NOT_APPLICABLE",
+                    "there is no pending device flow to recover",
+                )
+            if current.active is None:
+                self.backend.delete()
+            else:
+                self.backend.write(
+                    CredentialEnvelope.active_envelope(
+                        generation=current.generation + 1,
+                        active=current.active,
+                    ).to_bytes()
+                )
+            return {"mint_outcome": "unproved", "remote_cleanup": "unproved"}
+
+
+def _corrupt() -> CredentialStoreError:
+    return CredentialStoreError(
+        "CREDENTIAL_STORE_CORRUPT", "the protected credential envelope is invalid"
+    )
+
+
+def _permission_refusal() -> CredentialStoreError:
+    return CredentialStoreError(
+        "CREDENTIAL_STORE_PERMISSIONS",
+        "secure-file storage is not an owner-controlled regular single-link file",
+    )
+
+
+def _validate_saved_transition(
+    current: CredentialEnvelope | None,
+    incoming: CredentialEnvelope,
+    *,
+    expected_generation: int | None,
+) -> None:
+    """Prove a generic save is exactly one active-to-active generation transition."""
+
+    actual_generation = None if current is None else current.generation
+    if actual_generation != expected_generation:
+        raise CredentialStoreError(
+            "CREDENTIAL_GENERATION_CONFLICT",
+            "the protected credential generation changed",
+        )
+    if current is not None and current.state != "active":
+        raise CredentialStoreError(
+            "CREDENTIAL_RECOVERY_REQUIRED",
+            "the protected credential requires recovery before another mutation",
+        )
+    next_generation = 1 if current is None else current.generation + 1
+    if incoming.generation != next_generation:
+        raise CredentialStoreError(
+            "CREDENTIAL_GENERATION_CONFLICT",
+            "the protected credential generation must advance exactly once",
+        )
+    if incoming.state != "active":
+        raise CredentialStoreError(
+            "CREDENTIAL_RECOVERY_REQUIRED",
+            "generic credential saves may only install an active generation",
+        )
+
+
+def _ensure_private_directory(path: Path) -> None:
+    try:
+        try:
+            path.mkdir(mode=0o700, parents=True, exist_ok=False)
+            created = True
+        except FileExistsError:
+            created = False
+        if created and os.name == "posix":
+            os.chmod(path, 0o700, follow_symlinks=False)
+        _validate_private_directory(path)
+    except OSError:
+        raise CredentialStoreError(
+            "CREDENTIAL_STORE_PERMISSIONS", "the credential directory is not owner controlled"
+        ) from None
+
+
+def _validate_private_directory(path: Path) -> None:
+    try:
+        info = path.stat(follow_symlinks=False)
+    except OSError:
+        raise CredentialStoreError(
+            "CREDENTIAL_STORE_PERMISSIONS", "the credential directory is not owner controlled"
+        ) from None
+    if not stat.S_ISDIR(info.st_mode):
+        raise CredentialStoreError(
+            "CREDENTIAL_STORE_PERMISSIONS", "the credential directory is not owner controlled"
+        )
+    if os.name == "posix" and (info.st_uid != os.geteuid() or stat.S_IMODE(info.st_mode) != 0o700):
+        raise CredentialStoreError(
+            "CREDENTIAL_STORE_PERMISSIONS", "the credential directory is not owner controlled"
+        )
+    if os.name == "nt" and not _windows_acl_is_private(path):
+        raise CredentialStoreError(
+            "CREDENTIAL_STORE_PERMISSIONS", "the credential directory is not owner controlled"
+        )
+
+
+def _validate_private_file(info: os.stat_result, *, path: Path | None = None) -> None:
+    valid = stat.S_ISREG(info.st_mode) and info.st_nlink == 1
+    if os.name == "posix":
+        valid = valid and info.st_uid == os.geteuid() and stat.S_IMODE(info.st_mode) == 0o600
+    elif os.name == "nt":
+        valid = path is not None and _windows_acl_is_private(path)
+    if not valid:
+        raise _permission_refusal()
+
+
+def _windows_acl_is_private(path: Path) -> bool:
+    """Prove only the current user, SYSTEM, or Administrators can mutate a Windows path."""
+
+    if os.name != "nt":
+        return True
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        advapi32 = ctypes.WinDLL("advapi32", use_last_error=True)
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        _configure_windows_security_apis(advapi32, kernel32)
+        get_attributes = kernel32.GetFileAttributesW
+        get_attributes.argtypes = [wintypes.LPCWSTR]
+        get_attributes.restype = wintypes.DWORD
+        attributes = get_attributes(str(path))
+        if attributes == 0xFFFFFFFF or attributes & 0x400:  # invalid or reparse point
+            return False
+
+        owner = ctypes.c_void_p()
+        dacl = ctypes.c_void_p()
+        descriptor = ctypes.c_void_p()
+        get_security = advapi32.GetNamedSecurityInfoW
+        result = get_security(
+            str(path),
+            1,  # SE_FILE_OBJECT
+            0x1 | 0x4,  # OWNER_SECURITY_INFORMATION | DACL_SECURITY_INFORMATION
+            ctypes.byref(owner),
+            None,
+            ctypes.byref(dacl),
+            None,
+            ctypes.byref(descriptor),
+        )
+        if result != 0 or not owner.value or not dacl.value or not descriptor.value:
+            return False
+        try:
+            owned_current_sid = _windows_current_user_sid(advapi32, kernel32)
+            if owned_current_sid is None:
+                return False
+            current_sid, _current_sid_backing = owned_current_sid
+            if not advapi32.EqualSid(owner, current_sid):
+                return False
+            allowed = [current_sid]
+            allocated: list[ctypes.c_void_p] = []
+            for text in ("S-1-5-18", "S-1-5-32-544"):  # SYSTEM, Administrators
+                sid = ctypes.c_void_p()
+                if not advapi32.ConvertStringSidToSidW(text, ctypes.byref(sid)) or not sid.value:
+                    return False
+                allocated.append(sid)
+                allowed.append(sid.value)
+            try:
+                return _windows_acl_has_only_allowed_writers(advapi32, dacl, allowed)
+            finally:
+                for sid in allocated:
+                    kernel32.LocalFree(sid)
+        finally:
+            kernel32.LocalFree(descriptor)
+    except (AttributeError, OSError, TypeError, ValueError):
+        return False
+
+
+def _configure_windows_security_apis(advapi32: object, kernel32: object) -> None:
+    """Bind every pointer-bearing ACL API before the first 64-bit Windows call."""
+
+    import ctypes
+    from ctypes import wintypes
+
+    void_pointer_pointer = ctypes.POINTER(ctypes.c_void_p)
+    advapi32.GetNamedSecurityInfoW.argtypes = [
+        wintypes.LPCWSTR,
+        wintypes.DWORD,
+        wintypes.DWORD,
+        void_pointer_pointer,
+        void_pointer_pointer,
+        void_pointer_pointer,
+        void_pointer_pointer,
+        void_pointer_pointer,
+    ]
+    advapi32.GetNamedSecurityInfoW.restype = wintypes.DWORD
+    advapi32.EqualSid.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
+    advapi32.EqualSid.restype = wintypes.BOOL
+    advapi32.ConvertStringSidToSidW.argtypes = [wintypes.LPCWSTR, void_pointer_pointer]
+    advapi32.ConvertStringSidToSidW.restype = wintypes.BOOL
+    advapi32.OpenProcessToken.argtypes = [
+        wintypes.HANDLE,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.HANDLE),
+    ]
+    advapi32.OpenProcessToken.restype = wintypes.BOOL
+    advapi32.GetTokenInformation.argtypes = [
+        wintypes.HANDLE,
+        ctypes.c_int,
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+    ]
+    advapi32.GetTokenInformation.restype = wintypes.BOOL
+    advapi32.GetAce.argtypes = [ctypes.c_void_p, wintypes.DWORD, void_pointer_pointer]
+    advapi32.GetAce.restype = wintypes.BOOL
+    kernel32.GetCurrentProcess.argtypes = []
+    kernel32.GetCurrentProcess.restype = wintypes.HANDLE
+    kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    kernel32.CloseHandle.restype = wintypes.BOOL
+    kernel32.LocalFree.argtypes = [ctypes.c_void_p]
+    kernel32.LocalFree.restype = ctypes.c_void_p
+
+
+def _windows_current_user_sid(advapi32: object, kernel32: object) -> tuple[int, object] | None:
+    import ctypes
+    from ctypes import wintypes
+
+    token = wintypes.HANDLE()
+    if not advapi32.OpenProcessToken(kernel32.GetCurrentProcess(), 0x8, ctypes.byref(token)):
+        return None
+    try:
+        required = wintypes.DWORD()
+        advapi32.GetTokenInformation(token, 1, None, 0, ctypes.byref(required))
+        if required.value == 0:
+            return None
+        buffer = ctypes.create_string_buffer(required.value)
+        if not advapi32.GetTokenInformation(
+            token, 1, buffer, required.value, ctypes.byref(required)
+        ):
+            return None
+        sid = ctypes.cast(buffer, ctypes.POINTER(ctypes.c_void_p)).contents.value
+        if sid is None:
+            return None
+        return sid, buffer
+    finally:
+        kernel32.CloseHandle(token)
+
+
+def _windows_acl_has_only_allowed_writers(
+    advapi32: object,
+    dacl: object,
+    allowed_sids: list[int],
+) -> bool:
+    import ctypes
+    from ctypes import wintypes
+
+    class ACL(ctypes.Structure):
+        _fields_ = [
+            ("revision", ctypes.c_ubyte),
+            ("reserved", ctypes.c_ubyte),
+            ("size", ctypes.c_ushort),
+            ("ace_count", ctypes.c_ushort),
+            ("reserved2", ctypes.c_ushort),
+        ]
+
+    class ACE_HEADER(ctypes.Structure):
+        _fields_ = [
+            ("ace_type", ctypes.c_ubyte),
+            ("ace_flags", ctypes.c_ubyte),
+            ("ace_size", ctypes.c_ushort),
+        ]
+
+    class ACCESS_ALLOWED_ACE(ctypes.Structure):
+        _fields_ = [
+            ("header", ACE_HEADER),
+            ("mask", wintypes.DWORD),
+            ("sid_start", wintypes.DWORD),
+        ]
+
+    write_mask = (
+        0x2
+        | 0x4
+        | 0x10
+        | 0x40  # FILE_DELETE_CHILD grants directory-entry deletion.
+        | 0x100
+        | 0x10000
+        | 0x40000
+        | 0x80000
+        | 0x10000000
+        | 0x40000000
+    )
+    non_granting_ace_types = {
+        1,  # ACCESS_DENIED_ACE_TYPE
+        2,  # SYSTEM_AUDIT_ACE_TYPE
+        3,  # SYSTEM_ALARM_ACE_TYPE
+        6,  # ACCESS_DENIED_OBJECT_ACE_TYPE
+        7,  # SYSTEM_AUDIT_OBJECT_ACE_TYPE
+        8,  # SYSTEM_ALARM_OBJECT_ACE_TYPE
+        10,  # ACCESS_DENIED_CALLBACK_ACE_TYPE
+        12,  # ACCESS_DENIED_CALLBACK_OBJECT_ACE_TYPE
+        13,  # SYSTEM_AUDIT_CALLBACK_ACE_TYPE
+        14,  # SYSTEM_ALARM_CALLBACK_ACE_TYPE
+        15,  # SYSTEM_AUDIT_CALLBACK_OBJECT_ACE_TYPE
+        16,  # SYSTEM_ALARM_CALLBACK_OBJECT_ACE_TYPE
+        17,  # SYSTEM_MANDATORY_LABEL_ACE_TYPE
+        18,  # SYSTEM_RESOURCE_ATTRIBUTE_ACE_TYPE
+        19,  # SYSTEM_SCOPED_POLICY_ID_ACE_TYPE
+        20,  # SYSTEM_PROCESS_TRUST_LABEL_ACE_TYPE
+        21,  # SYSTEM_ACCESS_FILTER_ACE_TYPE
+    }
+    acl = ctypes.cast(dacl, ctypes.POINTER(ACL)).contents
+    for index in range(acl.ace_count):
+        ace_pointer = ctypes.c_void_p()
+        if not advapi32.GetAce(dacl, index, ctypes.byref(ace_pointer)):
+            return False
+        header = ctypes.cast(ace_pointer, ctypes.POINTER(ACE_HEADER)).contents
+        if header.ace_type != 0:
+            if header.ace_type in non_granting_ace_types:
+                continue
+            return False  # Unsupported or unknown granting ACE: the writer proof is incomplete.
+        ace = ctypes.cast(ace_pointer, ctypes.POINTER(ACCESS_ALLOWED_ACE)).contents
+        if not ace.mask & write_mask:
+            continue
+        sid = ace_pointer.value + ACCESS_ALLOWED_ACE.sid_start.offset
+        if not any(advapi32.EqualSid(sid, permitted) for permitted in allowed_sids):
+            return False
+    return True
+
+
+__all__ = [
+    "CREDENTIAL_ENVELOPE_SCHEMA",
+    "CredentialBackend",
+    "CredentialEnvelope",
+    "CredentialLease",
+    "CredentialStore",
+    "CredentialStoreError",
+    "ProtectedCredential",
+    "SecureFileBackend",
+    "credential_lock",
+]