vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/lib/auth/provider_resolver.py

@@ -0,0 +1,89 @@
+"""Which provider credential this invocation uses and where it came from.
+
+Order is environment → keyring → restricted file. Secrets get their own precedence
+because a CI job exporting OPENAI_API_KEY must win over whatever was stored locally.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+
+from ...types.provider import PROVIDER_ENV_VARS, Provider
+from ..errors.failures import InvalidProviderEnvironmentKey
+from .provider_credentials import ProviderCredentials
+from .provider_store import ProviderCredentialStore
+
+_MAX_KEY_CHARACTERS = 4096
+
+
+class ProviderSource(StrEnum):
+    """Stable non-secret provenance for a resolved provider credential."""
+
+    ENVIRONMENT = "environment"
+    KEYRING = "keyring"
+    RESTRICTED_FILE = "restricted_file"
+
+
+@dataclass(frozen=True)
+class ResolvedProviderCredential:
+    """Secret-safe credential plus non-secret provenance."""
+
+    credentials: ProviderCredentials
+    source: ProviderSource
+
+
+class ProviderResolver:
+    """Read one scoped provider credential according to documented precedence."""
+
+    def __init__(self, store: ProviderCredentialStore, environment: Mapping[str, str]) -> None:
+        # Store and environment injected for test control.
+        self._store = store
+        self._environment = environment
+
+    def resolve(self, profile: str, provider: Provider) -> ResolvedProviderCredential | None:
+        # Env var is highest; set-but-unusable is an error, not a silent miss.
+        if provider == Provider.GEMINI:
+            return self._resolve_gemini(profile)
+        env_var = PROVIDER_ENV_VARS[provider]
+        environment_value = self._environment.get(env_var)
+        if environment_value is not None:
+            token = environment_value.strip()
+            if not token or len(token) > _MAX_KEY_CHARACTERS:
+                raise InvalidProviderEnvironmentKey(provider.value, env_var)
+            if not ProviderCredentials.is_live_format(provider, token):
+                raise InvalidProviderEnvironmentKey(provider.value, env_var)
+            return ResolvedProviderCredential(
+                ProviderCredentials(provider=provider, api_key=token),  # type: ignore[arg-type]
+                ProviderSource.ENVIRONMENT,
+            )
+        keyring_value = self._store.keyring.read(profile, provider)
+        if keyring_value is not None:
+            return ResolvedProviderCredential(keyring_value, ProviderSource.KEYRING)
+        file_value = self._store.file.read(profile, provider)
+        if file_value is not None:
+            return ResolvedProviderCredential(file_value, ProviderSource.RESTRICTED_FILE)
+        return None
+
+    def _resolve_gemini(self, profile: str) -> ResolvedProviderCredential | None:
+        # Google supports GEMINI_API_KEY and legacy GOOGLE_API_KEY, with GOOGLE taking precedence.
+        for env_var in ("GOOGLE_API_KEY", "GEMINI_API_KEY"):
+            environment_value = self._environment.get(env_var)
+            if environment_value is not None:
+                token = environment_value.strip()
+                if not token or len(token) > _MAX_KEY_CHARACTERS:
+                    raise InvalidProviderEnvironmentKey(Provider.GEMINI.value, env_var)
+                if not ProviderCredentials.is_live_format(Provider.GEMINI, token):
+                    raise InvalidProviderEnvironmentKey(Provider.GEMINI.value, env_var)
+                return ResolvedProviderCredential(
+                    ProviderCredentials(provider=Provider.GEMINI, api_key=token),  # type: ignore[arg-type]
+                    ProviderSource.ENVIRONMENT,
+                )
+        keyring_value = self._store.keyring.read(profile, Provider.GEMINI)
+        if keyring_value is not None:
+            return ResolvedProviderCredential(keyring_value, ProviderSource.KEYRING)
+        file_value = self._store.file.read(profile, Provider.GEMINI)
+        if file_value is not None:
+            return ResolvedProviderCredential(file_value, ProviderSource.RESTRICTED_FILE)
+        return None

vidbyte_cli/lib/auth/provider_store.py

@@ -0,0 +1,149 @@
+"""Keyring-first provider credential facade.
+
+Mirrors CredentialStore but namespaces to vidbyte-cli-provider and scopes by provider.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, cast
+
+import keyring
+from keyring.errors import KeyringError
+from pydantic import ValidationError
+
+from ...types.provider import Provider
+from ..config.paths import VidbytePaths
+from ..errors.failures import NoApprovedProviderStore, ProviderStoreUnavailable
+from .provider_credentials import (
+    FileProviderStore,
+    ProviderCredentials,
+    ProviderScope,
+    ProviderStorage,
+)
+
+if TYPE_CHECKING:
+    pass
+
+_PROVIDER_SERVICE = "vidbyte-cli-provider"
+_MINIMUM_BACKEND_PRIORITY = 1
+
+
+class ProviderKeyringBackend(Protocol):
+    """Small structural surface needed from the provider keyring backend."""
+
+    priority: float
+
+    def get_password(self, service: str, username: str) -> str | None: ...
+
+    def set_password(self, service: str, username: str, password: str) -> None: ...
+
+    def delete_password(self, service: str, username: str) -> None: ...
+
+
+class KeyringProviderStore:
+    """Secret store for provider keys backed by the OS keyring."""
+
+    def __init__(self, backend: ProviderKeyringBackend | None = None) -> None:
+        # Backend injectable for tests; otherwise resolved lazily.
+        self._backend = backend
+
+    def available(self) -> bool:
+        # Availability is a question, not a failure.
+        try:
+            return float(self._get_backend().priority) >= _MINIMUM_BACKEND_PRIORITY
+        except (KeyringError, RuntimeError, TypeError, ValueError):
+            return False
+
+    def read(self, profile: str, provider: Provider) -> ProviderCredentials | None:
+        # Returns None when unavailable or missing; raises only on backend errors.
+        if not self.available():
+            return None
+        try:
+            value = self._get_backend().get_password(
+                _PROVIDER_SERVICE,
+                ProviderScope(profile, provider).account,
+            )
+        except KeyringError as error:
+            raise ProviderStoreUnavailable(error) from error
+        if value is None:
+            return None
+        try:
+            return ProviderCredentials(provider=provider, api_key=value)  # type: ignore[arg-type]
+        except ValidationError as error:
+            raise ProviderStoreUnavailable(error) from error
+
+    def write(self, credentials: ProviderCredentials, profile: str, provider: Provider) -> None:
+        # Verifies write by reading back; a lying backend must not report success.
+        if not self.available():
+            raise ProviderStoreUnavailable()
+        account = ProviderScope(profile, provider).account
+        try:
+            backend = self._get_backend()
+            backend.set_password(_PROVIDER_SERVICE, account, credentials.secret_value())
+            read_back = backend.get_password(_PROVIDER_SERVICE, account)
+        except KeyringError as error:
+            raise ProviderStoreUnavailable(error) from error
+        if read_back != credentials.secret_value():
+            raise ProviderStoreUnavailable()
+
+    def clear(self, profile: str, provider: Provider) -> bool:
+        # Clears the keyring entry if present.
+        if not self.available():
+            return False
+        account = ProviderScope(profile, provider).account
+        try:
+            backend = self._get_backend()
+            if backend.get_password(_PROVIDER_SERVICE, account) is None:
+                return False
+            backend.delete_password(_PROVIDER_SERVICE, account)
+            return True
+        except KeyringError as error:
+            raise ProviderStoreUnavailable(error) from error
+
+    def _get_backend(self) -> ProviderKeyringBackend:
+        # Resolved on first use and cached; discovery can open a keychain session.
+        if self._backend is None:
+            self._backend = cast(ProviderKeyringBackend, keyring.get_keyring())
+        return self._backend
+
+
+class ProviderCredentialStore:
+    """Keyring-first durable provider credential facade."""
+
+    def __init__(
+        self,
+        keyring_store: KeyringProviderStore | None = None,
+        file_store: FileProviderStore | None = None,
+        paths: VidbytePaths | None = None,
+    ) -> None:
+        # Composition mirrors CredentialStore for test injection.
+        resolved_paths = paths or VidbytePaths.default()
+        self.keyring = keyring_store or KeyringProviderStore()
+        self.file = file_store or FileProviderStore(resolved_paths)
+
+    def read(self, profile: str, provider: Provider) -> ProviderCredentials | None:
+        # Keyring outranks file; file is fallback.
+        return self.keyring.read(profile, provider) or self.file.read(profile, provider)
+
+    def write(
+        self,
+        credentials: ProviderCredentials,
+        profile: str,
+        provider: Provider,
+        *,
+        allow_file_fallback: bool = False,
+    ) -> ProviderStorage:
+        # Writes to keyring when available; otherwise file with consent.
+        if self.keyring.available():
+            self.keyring.write(credentials, profile, provider)
+            return ProviderStorage.KEYRING
+        if not allow_file_fallback:
+            raise NoApprovedProviderStore(provider.value)
+        self.file.write(credentials, profile, provider)
+        return ProviderStorage.RESTRICTED_FILE
+
+    def clear(self, profile: str, provider: Provider) -> bool:
+        # Clears both stores; a stale entry in either would stay effective.
+        keyring_cleared = self.keyring.clear(profile, provider)
+        file_cleared = self.file.clear(profile, provider)
+        return keyring_cleared or file_cleared

vidbyte_cli/lib/auth/provider_verifier.py

@@ -0,0 +1,219 @@
+"""Live probe verifiers for provider BYOK keys.
+
+Verifies OpenAI via GET https://api.openai.com/v1/models with Authorization: Bearer,
+Claude via GET https://api.anthropic.com/v1/models with x-api-key + anthropic-version,
+and Grok/DeepSeek/GLM/Muse via Bearer probes to their native /v1/models endpoints.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Protocol
+
+from pydantic import BaseModel, ConfigDict
+
+from ...types.provider import PROVIDER_PROBE_URLS, Provider
+from ..errors.failures import (
+    ProviderApiProtocolError,
+    ProviderApiUnreachable,
+    ProviderCredentialsRejected,
+    ProviderRateLimited,
+    ProviderRequestRejected,
+)
+from .provider_credentials import ProviderCredentials
+
+_MAX_RESPONSE_BYTES = 1_048_576
+
+
+class ProviderIdentity(BaseModel):
+    """Non-secret identity behind a verified provider key."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    provider: Provider
+    verified: bool = True
+
+
+class ProviderVerifier(Protocol):
+    """Proves a candidate provider key against its native endpoint."""
+
+    def verify(self, credentials: ProviderCredentials) -> ProviderIdentity: ...
+
+
+class _BaseProviderVerifier:
+    """Shared transport and decoding for one provider probe."""
+
+    def _headers(self, credentials: ProviderCredentials) -> dict[str, str]:
+        # Subclasses define exact auth headers per provider docs.
+        raise NotImplementedError
+
+    def _url(self, provider: Provider) -> str:
+        # Canonical probe URL per provider.
+        return PROVIDER_PROBE_URLS[provider]
+
+    def _probe(self, credentials: ProviderCredentials, timeout_seconds: float) -> None:
+        # Executes the live GET and classifies the outcome.
+        import httpx
+
+        url = self._url(credentials.provider)
+        headers = {"Accept": "application/json", **self._headers(credentials)}
+        try:
+            with httpx.Client(timeout=timeout_seconds, follow_redirects=False) as client:
+                response = client.get(url, headers=headers)
+        except httpx.HTTPError as error:
+            raise ProviderApiUnreachable(credentials.provider.value, error) from error
+        self._classify_status(credentials, response)
+        self._validate_body(credentials, response)
+
+    def _classify_status(self, credentials: ProviderCredentials, response: object) -> None:
+        # Maps status to a typed failure before any body is inspected.
+        status = int(getattr(response, "status_code", 0))
+        headers = getattr(response, "headers", {})
+        if status == 429:
+            retry = headers.get("Retry-After") if hasattr(headers, "get") else None
+            try:
+                retry_after = int(retry) if retry is not None else None
+            except ValueError:
+                retry_after = None
+            raise ProviderRateLimited(credentials.provider.value, retry_after)
+        if status in (401, 403):
+            raise ProviderCredentialsRejected(credentials.provider.value)
+        if status in (400, 404, 409, 422):
+            raise ProviderRequestRejected(credentials.provider.value)
+        if 500 <= status < 600:
+            raise ProviderApiUnreachable(credentials.provider.value)
+        if not 200 <= status < 300:
+            raise ProviderRequestRejected(credentials.provider.value)
+
+    def _validate_body(self, credentials: ProviderCredentials, response: object) -> None:
+        # Bounds, parses, and shape-checks the 2xx body.
+        content = getattr(response, "content", b"")
+        if not content or len(content) > _MAX_RESPONSE_BYTES:
+            raise ProviderApiProtocolError(credentials.provider.value)
+        try:
+            payload = json.loads(content)
+        except (ValueError, json.JSONDecodeError) as error:
+            raise ProviderApiProtocolError(credentials.provider.value, error) from error
+        if not isinstance(payload, dict):
+            raise ProviderApiProtocolError(credentials.provider.value)
+        # OpenAI-style uses data; Gemini/Cohere use models.
+        data = payload.get("data")
+        if isinstance(data, list):
+            return
+        models = payload.get("models")
+        if isinstance(models, list):
+            return
+        raise ProviderApiProtocolError(credentials.provider.value)
+
+
+class OpenAIVerifier(_BaseProviderVerifier):
+    """Proves an OpenAI key via GET /v1/models with Bearer auth."""
+
+    def verify(self, credentials: ProviderCredentials) -> ProviderIdentity:
+        # Uses a short timeout derived from caller's config where available.
+        self._probe(credentials, timeout_seconds=15.0)
+        return ProviderIdentity(provider=credentials.provider)
+
+    def _headers(self, credentials: ProviderCredentials) -> dict[str, str]:
+        # Exact string per OpenAI docs: Authorization: Bearer $OPENAI_API_KEY
+        return {"Authorization": f"Bearer {credentials.secret_value()}"}
+
+
+class ClaudeVerifier(_BaseProviderVerifier):
+    """Proves a Claude key via GET /v1/models with x-api-key + version."""
+
+    def verify(self, credentials: ProviderCredentials) -> ProviderIdentity:
+        # Anthropic requires anthropic-version header on every request.
+        self._probe(credentials, timeout_seconds=15.0)
+        return ProviderIdentity(provider=credentials.provider)
+
+    def _headers(self, credentials: ProviderCredentials) -> dict[str, str]:
+        # Per Anthropic docs: x-api-key + anthropic-version: 2023-06-01
+        return {
+            "x-api-key": credentials.secret_value(),
+            "anthropic-version": "2023-06-01",
+        }
+
+
+class GrokVerifier(_BaseProviderVerifier):
+    """Proves a Grok key via GET /v1/models with Bearer auth."""
+
+    def verify(self, credentials: ProviderCredentials) -> ProviderIdentity:
+        # xAI uses OpenAI-compatible Bearer on https://api.x.ai/v1/models.
+        self._probe(credentials, timeout_seconds=15.0)
+        return ProviderIdentity(provider=credentials.provider)
+
+    def _headers(self, credentials: ProviderCredentials) -> dict[str, str]:
+        # Exact string per xAI docs: Authorization: Bearer $XAI_API_KEY
+        return {"Authorization": f"Bearer {credentials.secret_value()}"}
+
+
+class DeepSeekVerifier(_BaseProviderVerifier):
+    """Proves a DeepSeek key via GET /v1/models with Bearer auth."""
+
+    def verify(self, credentials: ProviderCredentials) -> ProviderIdentity:
+        # DeepSeek is OpenAI-compatible on https://api.deepseek.com/v1/models.
+        self._probe(credentials, timeout_seconds=15.0)
+        return ProviderIdentity(provider=credentials.provider)
+
+    def _headers(self, credentials: ProviderCredentials) -> dict[str, str]:
+        # Per DeepSeek docs: Authorization: Bearer $DEEPSEEK_API_KEY
+        return {"Authorization": f"Bearer {credentials.secret_value()}"}
+
+
+class GlmVerifier(_BaseProviderVerifier):
+    """Proves a GLM key via GET /models with Bearer auth."""
+
+    def verify(self, credentials: ProviderCredentials) -> ProviderIdentity:
+        # Z.AI is OpenAI-compatible on https://api.z.ai/api/paas/v4/models.
+        self._probe(credentials, timeout_seconds=15.0)
+        return ProviderIdentity(provider=credentials.provider)
+
+    def _headers(self, credentials: ProviderCredentials) -> dict[str, str]:
+        # Per Z.AI docs: Authorization: Bearer $ZAI_API_KEY
+        return {"Authorization": f"Bearer {credentials.secret_value()}"}
+
+
+class MuseVerifier(_BaseProviderVerifier):
+    """Proves a Muse key via GET /v1/models with Bearer auth."""
+
+    def verify(self, credentials: ProviderCredentials) -> ProviderIdentity:
+        # Meta is OpenAI-compatible on https://api.meta.ai/v1/models.
+        self._probe(credentials, timeout_seconds=15.0)
+        return ProviderIdentity(provider=credentials.provider)
+
+    def _headers(self, credentials: ProviderCredentials) -> dict[str, str]:
+        # Per Meta docs: Authorization: Bearer $MODEL_API_KEY
+        return {"Authorization": f"Bearer {credentials.secret_value()}"}
+
+
+class GeminiVerifier(_BaseProviderVerifier):
+    """Proves a Gemini key via GET /v1beta/models with x-goog-api-key."""
+
+    def verify(self, credentials: ProviderCredentials) -> ProviderIdentity:
+        # Google uses x-goog-api-key on generativelanguage.googleapis.com.
+        self._probe(credentials, timeout_seconds=15.0)
+        return ProviderIdentity(provider=credentials.provider)
+
+    def _headers(self, credentials: ProviderCredentials) -> dict[str, str]:
+        # Per Google docs: x-goog-api-key: $GEMINI_API_KEY
+        return {"x-goog-api-key": credentials.secret_value()}
+
+
+def verifier_for_provider(provider: Provider) -> ProviderVerifier:
+    # Factory keeps command branching closed over Provider variants.
+    if provider == Provider.OPENAI:
+        return OpenAIVerifier()
+    if provider == Provider.CLAUDE:
+        return ClaudeVerifier()
+    if provider == Provider.GROK:
+        return GrokVerifier()
+    if provider == Provider.DEEPSEEK:
+        return DeepSeekVerifier()
+    if provider == Provider.GLM:
+        return GlmVerifier()
+    if provider == Provider.MUSE:
+        return MuseVerifier()
+    if provider == Provider.GEMINI:
+        return GeminiVerifier()
+    raise ValueError(f"unsupported provider {provider}")

vidbyte_cli/lib/auth/resolver.py

@@ -0,0 +1,63 @@
+"""Which credential this invocation uses, and where it came from.
+
+Order is environment → OS keyring → restricted file. Secrets get their own precedence
+because a CI job exporting `VIDBYTE_API_KEY` must win over whatever a developer once stored
+on the same machine, while non-secret config follows the profile layering in `lib/config`.
+
+Reading is all this does. Login deliberately does not resolve through here, which is what
+keeps an environment token from being written into durable storage as if it were entered.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+
+from ..errors.failures import EnvironmentApiKeyNotLive, InvalidEnvironmentApiKey
+from .credentials import Credentials, CredentialStore
+
+_MAX_KEY_CHARACTERS = 4096
+
+
+class CredentialSource(StrEnum):
+    """Stable non-secret provenance for a resolved credential."""
+
+    ENVIRONMENT = "environment"
+    KEYRING = "keyring"
+    RESTRICTED_FILE = "restricted_file"
+
+
+@dataclass(frozen=True)
+class ResolvedCredential:
+    """Secret-safe credential plus non-secret provenance."""
+
+    credentials: Credentials
+    source: CredentialSource
+
+
+class CredentialResolver:
+    """Read one scoped credential according to documented precedence."""
+
+    def __init__(self, store: CredentialStore, environment: Mapping[str, str]) -> None:
+        self._store = store
+        self._environment = environment
+
+    def resolve(self, profile: str, api_url: str) -> ResolvedCredential | None:
+        environment_value = self._environment.get("VIDBYTE_API_KEY")
+        if environment_value is not None:
+            # Set-but-unusable is an error, not a miss: falling through would silently
+            # authenticate as whoever is stored locally, which the caller did not ask for.
+            token = environment_value.strip()
+            if not token or len(token) > _MAX_KEY_CHARACTERS:
+                raise InvalidEnvironmentApiKey()
+            if not Credentials.is_live_format(token):
+                raise EnvironmentApiKeyNotLive()
+            return ResolvedCredential(Credentials.from_value(token), CredentialSource.ENVIRONMENT)
+        keyring_value = self._store.keyring.read(profile, api_url)
+        if keyring_value is not None:
+            return ResolvedCredential(keyring_value, CredentialSource.KEYRING)
+        file_value = self._store.file.read(profile, api_url)
+        if file_value is not None:
+            return ResolvedCredential(file_value, CredentialSource.RESTRICTED_FILE)
+        return None

vidbyte_cli/lib/auth/verifier.py

@@ -0,0 +1,38 @@
+"""The verify-before-persist boundary login must cross before a key reaches storage.
+
+Making it a protocol states the invariant in the type system: `CredentialStore.write` is
+only ever reached through a `verify` that returned. A syntactically valid token is not a
+working one, and a stored bad key fails every later command with no obvious cause.
+
+`verify` returns the identity rather than nothing so `login` and `whoami` can share one call:
+login discards the result, whoami prints it. Two commands asking the same question of the
+backend cannot then drift into asking it two different ways.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from ...types.api import KeyIdentity
+from ..api.client import ApiClient
+from ..api.endpoints.auth import AuthEndpoints
+from ..config import ResolvedConfig
+from ..errors.failures import ApiResponseUnsupported
+from .credentials import Credentials
+
+
+class CredentialVerifier(Protocol):
+    def verify(self, credentials: Credentials, config: ResolvedConfig) -> KeyIdentity: ...
+
+
+class ApiCredentialVerifier:
+    """Prove a candidate key against the backend before it may be persisted."""
+
+    def verify(self, credentials: Credentials, config: ResolvedConfig) -> KeyIdentity:
+        # Calls the permission-free liveness check and returns the non-secret identity.
+        identity = AuthEndpoints(ApiClient(config, credentials)).validate()
+        if not identity.success:
+            # A success status that denies success is a contract this CLI cannot act on, and
+            # treating it as acceptance would store a key the backend has just refused.
+            raise ApiResponseUnsupported()
+        return identity

vidbyte_cli/lib/config/__init__.py

@@ -0,0 +1,25 @@
+"""Typed, versioned non-secret CLI configuration contracts."""
+
+from .config import ConfigSnapshot, ConfigStore
+from .models import (
+    ConfigDocument,
+    ConfigField,
+    ConfigSource,
+    ProfileConfig,
+    ResolvedConfig,
+)
+from .paths import VidbytePaths
+from .resolver import ConfigOverrides, ConfigResolver
+
+__all__ = [
+    "ConfigDocument",
+    "ConfigField",
+    "ConfigOverrides",
+    "ConfigResolver",
+    "ConfigSnapshot",
+    "ConfigSource",
+    "ConfigStore",
+    "ProfileConfig",
+    "ResolvedConfig",
+    "VidbytePaths",
+]

vidbyte_cli/lib/config/atomic.py

@@ -0,0 +1,47 @@
+"""The one way local CLI state is replaced on disk: owner-only, fsynced, atomic.
+
+Config, the fallback credential file, and migrated copies all go through here, so the
+permission and durability rules live in one reviewable place instead of at each store.
+
+The write goes to a randomized sibling in the destination directory before `os.replace`,
+because replace is only atomic within a filesystem, and an interrupted write must leave the
+previous file rather than a truncated one. This layer knows nothing about JSON or secrets.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from uuid import uuid4
+
+from ..errors.failures import StateWriteFailed, StateWriteThroughSymlink
+
+
+class AtomicFileWriter:
+    """Write exact files through a flushed sibling and atomic replacement."""
+
+    def write(self, path: Path, content: bytes, *, mode: int = 0o600) -> None:
+        # Replacing a symlink mutates the link entry on some platforms and its target on
+        # others. That is not uniform enough to stand as a security boundary for a path
+        # that may hold a credential, so refuse rather than pick a behavior.
+        if path.is_symlink():
+            raise StateWriteThroughSymlink()
+        temporary_path = path.with_name(f".{path.name}.{uuid4().hex}.tmp")
+        try:
+            path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+            # O_EXCL with a random name means this process owns the temporary file outright.
+            descriptor = os.open(temporary_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode)
+            with os.fdopen(descriptor, "wb") as stream:
+                stream.write(content)
+                stream.flush()
+                os.fsync(stream.fileno())
+            # Windows ignores the mode passed to os.open, and os.replace preserves the
+            # destination's existing permissions, so restate the mode on both sides.
+            os.chmod(temporary_path, mode)
+            os.replace(temporary_path, path)
+            os.chmod(path, mode)
+        except OSError as error:
+            raise StateWriteFailed(error) from error
+        finally:
+            # Only this call's randomized sibling is ever removed, never the destination.
+            temporary_path.unlink(missing_ok=True)