vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/lib/auth/credentials.py

@@ -0,0 +1,223 @@
+"""Secret-safe credential models and the keyring-first store the rest of the CLI talks to.
+
+The key is a `SecretStr`, so it stays out of reprs, logs, and model dumps by default;
+`secret_value()` and `FileCredentialStore._encode` are the only two deliberate unwrappings.
+
+The restricted file is a fallback, never a default. It stores a key readable by anything
+running as this user, so `CredentialStore.write` refuses it unless the caller passes explicit
+consent — a decision that belongs to the person logging in, not to this layer.
+"""
+
+from __future__ import annotations
+
+import json
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, ValidationError, field_validator
+
+from ..config.atomic import AtomicFileWriter
+from ..config.models import DEFAULT_API_URL, DEFAULT_PROFILE
+from ..config.paths import VidbytePaths
+from ..errors.failures import (
+    LegacyCredentialRemovalFailed,
+    LegacyCredentialSymlink,
+    LegacyCredentialUnreadable,
+    NoApprovedCredentialStore,
+    StoredCredentialUnreadable,
+)
+from .keyring_store import CredentialScope, KeyringCredentialStore
+
+# Bounds a hostile or accidentally-redirected file before it is parsed into memory.
+_MAX_CREDENTIAL_BYTES = 1_000_000
+_MAX_KEY_CHARACTERS = 4096
+# The only prefix the backend gatekeeper extracts. A key without it yields no candidate at
+# all, so the request is not rejected as malformed — it is treated as unauthenticated.
+LIVE_API_KEY_PREFIX = "vb_live_"
+
+
+class Credentials(BaseModel):
+    """One opaque Vidbyte API token with secret-safe representation."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    api_key: SecretStr
+
+    @field_validator("api_key")
+    @classmethod
+    def validate_api_key(cls, value: SecretStr) -> SecretStr:
+        if not 1 <= len(value.get_secret_value()) <= _MAX_KEY_CHARACTERS:
+            raise ValueError("API key must contain between 1 and 4096 characters")
+        return value
+
+    @classmethod
+    def from_value(cls, value: str) -> Credentials:
+        return cls(api_key=SecretStr(value))
+
+    @classmethod
+    def is_live_format(cls, value: str) -> bool:
+        # Asked at the input boundaries only. Making it a field invariant would make a stored
+        # non-live key unreadable, and so unremovable by the logout that exists to clear it.
+        return value.startswith(LIVE_API_KEY_PREFIX)
+
+    def secret_value(self) -> str:
+        return self.api_key.get_secret_value()
+
+
+class CredentialStorage(StrEnum):
+    """Durable storage selected for a verified login."""
+
+    KEYRING = "keyring"
+    RESTRICTED_FILE = "restricted_file"
+
+
+class CredentialDocument(BaseModel):
+    """Version-one restricted fallback file."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = 1
+    entries: dict[str, SecretStr] = Field(default_factory=dict)
+
+
+class FileCredentialStore:
+    """Permission-restricted fallback store, never an automatic first choice."""
+
+    def __init__(self, paths: VidbytePaths, writer: AtomicFileWriter | None = None) -> None:
+        self._paths = paths
+        self._writer = writer or AtomicFileWriter()
+
+    def read(self, profile: str, api_url: str) -> Credentials | None:
+        secret = self._load().entries.get(CredentialScope(profile, api_url).account)
+        if secret is not None:
+            return Credentials(api_key=secret)
+        return self._read_legacy_unscoped(profile, api_url)
+
+    def write(self, credentials: Credentials, profile: str, api_url: str) -> None:
+        document = self._load()
+        entries = dict(document.entries)
+        entries[CredentialScope(profile, api_url).account] = credentials.api_key
+        self._writer.write(
+            self._paths.credentials_file(),
+            self._encode(CredentialDocument(entries=entries)),
+        )
+
+    def clear(self, profile: str, api_url: str) -> bool:
+        document = self._load()
+        account = CredentialScope(profile, api_url).account
+        if account not in document.entries:
+            return False
+        entries = dict(document.entries)
+        del entries[account]
+        self._writer.write(
+            self._paths.credentials_file(),
+            self._encode(CredentialDocument(entries=entries)),
+        )
+        return True
+
+    def clear_legacy(self, profile: str, api_url: str) -> bool:
+        # Logout is an explicit destructive request. Unlike migration, which preserves the
+        # legacy tree, it must ensure an old unscoped token cannot become effective again
+        # once the scoped stores are empty.
+        if profile != DEFAULT_PROFILE or api_url != DEFAULT_API_URL:
+            return False
+        path = self._paths.legacy_credentials_file()
+        if not path.exists():
+            return False
+        if path.is_symlink():
+            raise LegacyCredentialSymlink()
+        try:
+            path.unlink()
+        except OSError as error:
+            raise LegacyCredentialRemovalFailed(error) from error
+        return True
+
+    def _load(self) -> CredentialDocument:
+        path = self._paths.credentials_file()
+        if not path.exists():
+            return CredentialDocument()
+        try:
+            raw = path.read_bytes()
+            if len(raw) > _MAX_CREDENTIAL_BYTES:
+                raise ValueError("credential file exceeds the size limit")
+            parsed = json.loads(raw)
+            if isinstance(parsed, dict) and parsed.get("schema_version", 1) != 1:
+                raise ValueError("unsupported credential schema")
+            return CredentialDocument.model_validate(parsed)
+        except (OSError, json.JSONDecodeError, ValidationError, ValueError) as error:
+            raise StoredCredentialUnreadable(error) from error
+
+    def _read_legacy_unscoped(self, profile: str, api_url: str) -> Credentials | None:
+        # The legacy file predates scoping, so it can only answer for the default scope.
+        if profile != DEFAULT_PROFILE or api_url != DEFAULT_API_URL:
+            return None
+        path = self._paths.legacy_credentials_file()
+        if not path.exists():
+            return None
+        try:
+            raw = path.read_bytes()
+            if len(raw) > _MAX_CREDENTIAL_BYTES:
+                raise ValueError("legacy credential file exceeds the size limit")
+            return Credentials.model_validate(json.loads(raw))
+        except (OSError, json.JSONDecodeError, ValidationError, ValueError) as error:
+            raise LegacyCredentialUnreadable(error) from error
+
+    def _encode(self, document: CredentialDocument) -> bytes:
+        # SecretStr's JSON serializer redacts values, which is right everywhere except here:
+        # this is the one intentional unwrapping point for the restricted credential file.
+        payload = {
+            "schema_version": document.schema_version,
+            "entries": {
+                account: secret.get_secret_value() for account, secret in document.entries.items()
+            },
+        }
+        return json.dumps(payload, indent=2, sort_keys=True).encode("utf-8") + b"\n"
+
+
+class CredentialStore:
+    """Keyring-first durable credential facade."""
+
+    def __init__(
+        self,
+        keyring_store: KeyringCredentialStore | None = None,
+        file_store: FileCredentialStore | None = None,
+        paths: VidbytePaths | None = None,
+    ) -> None:
+        resolved_paths = paths or VidbytePaths.default()
+        self.keyring = keyring_store or KeyringCredentialStore()
+        self.file = file_store or FileCredentialStore(resolved_paths)
+
+    def read(
+        self,
+        profile: str = DEFAULT_PROFILE,
+        api_url: str = DEFAULT_API_URL,
+    ) -> Credentials | None:
+        return self.keyring.read(profile, api_url) or self.file.read(profile, api_url)
+
+    def write(
+        self,
+        credentials: Credentials,
+        profile: str = DEFAULT_PROFILE,
+        api_url: str = DEFAULT_API_URL,
+        *,
+        allow_file_fallback: bool = False,
+    ) -> CredentialStorage:
+        if self.keyring.available():
+            self.keyring.write(credentials, profile, api_url)
+            return CredentialStorage.KEYRING
+        if not allow_file_fallback:
+            raise NoApprovedCredentialStore()
+        self.file.write(credentials, profile, api_url)
+        return CredentialStorage.RESTRICTED_FILE
+
+    def clear(
+        self,
+        profile: str = DEFAULT_PROFILE,
+        api_url: str = DEFAULT_API_URL,
+    ) -> bool:
+        # Every store is cleared, not just the first that answers: a stale entry left in one
+        # of them would keep authenticating after the user asked to be logged out.
+        keyring_cleared = self.keyring.clear(profile, api_url)
+        file_cleared = self.file.clear(profile, api_url)
+        legacy_cleared = self.file.clear_legacy(profile, api_url)
+        return keyring_cleared or file_cleared or legacy_cleared

vidbyte_cli/lib/auth/input.py

@@ -0,0 +1,59 @@
+"""The two channels a login token may arrive on: a hidden prompt, or explicit stdin.
+
+There is deliberately no `--api-key` option. An argv secret is visible in `ps`, the shell
+history file, and any CI log that echoes its command line, and no amount of care at the
+raise sites takes it back out of those.
+
+Stdin is read only when `--with-token` asks for it, so a command whose input happens to be
+redirected fails with a usage error instead of consuming a stream meant for something else.
+The environment is absent on purpose: login persists only what a person explicitly entered.
+"""
+
+from __future__ import annotations
+
+import getpass
+
+from ..errors.failures import (
+    ApiKeyNotLiveFormat,
+    InvalidApiKeyInput,
+    NoninteractiveLoginRequiresToken,
+)
+from ..io import IOStreams
+from ..io.terminal import TerminalCapabilities
+from .credentials import Credentials
+
+_MAX_TOKEN_CHARACTERS = 4096
+
+
+class CredentialInput:
+    """Acquire one token through an explicit secret-safe channel."""
+
+    def __init__(
+        self,
+        streams: IOStreams,
+        terminal: TerminalCapabilities,
+        *,
+        no_input: bool,
+    ) -> None:
+        self._streams = streams
+        self._terminal = terminal
+        self._no_input = no_input
+
+    def read(self, *, from_stdin: bool) -> Credentials:
+        if from_stdin:
+            # One past the bound, so an oversized stream is rejected rather than truncated
+            # into a token that looks plausible.
+            value = self._streams.stdin.read(_MAX_TOKEN_CHARACTERS + 1)
+        else:
+            if self._no_input or not self._terminal.interactive:
+                raise NoninteractiveLoginRequiresToken()
+            # The prompt goes to stderr so `login` stays usable inside a pipeline.
+            value = getpass.getpass("Vidbyte API key: ", stream=self._streams.stderr)
+        token = value.strip()
+        if not token or len(token) > _MAX_TOKEN_CHARACTERS:
+            raise InvalidApiKeyInput()
+        # Bounds run first, so an accidental file redirect is reported as oversized rather
+        # than prefix-tested in full.
+        if not Credentials.is_live_format(token):
+            raise ApiKeyNotLiveFormat()
+        return Credentials.from_value(token)

vidbyte_cli/lib/auth/keyring_store.py

@@ -0,0 +1,126 @@
+"""The system keyring, adapted to profile- and API-origin-scoped Vidbyte credentials.
+
+Every stored secret is scoped, so one profile cannot read another's key and a staging login
+cannot authenticate against production. A backend failure is translated, never propagated:
+keyring exceptions routinely quote account identifiers and backend internals.
+
+A write is not believed until the same value reads back. Some backends accept a write and
+store nothing, and a login that reports success while storing nothing is worse than failing.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, cast
+
+import keyring
+from keyring.errors import KeyringError
+from pydantic import ValidationError
+
+from ..config.models import ApiOrigin
+from ..errors.failures import CredentialStoreUnavailable
+
+if TYPE_CHECKING:
+    from .credentials import Credentials
+
+_SERVICE_NAME = "vidbyte-cli"
+# keyring's own null and fail backends sit below 1; anything at or above it is a real store.
+_MINIMUM_BACKEND_PRIORITY = 1
+
+
+class KeyringBackend(Protocol):
+    """Small structural surface needed from an installed 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 CredentialScope:
+    """The profile and API origin that one stored secret belongs to."""
+
+    def __init__(self, profile: str, api_url: str) -> None:
+        self.profile = profile
+        self.origin = ApiOrigin.parse(api_url)
+
+    @property
+    def account(self) -> str:
+        # The default port is omitted so `https://example.test` and `https://example.test:443`
+        # resolve to one entry rather than two credentials that silently disagree.
+        port = self.origin.port
+        scheme = self.origin.scheme
+        is_default_port = port is None or (scheme, port) in {("https", 443), ("http", 80)}
+        host = self.origin.host if is_default_port else f"{self.origin.host}:{port}"
+        return f"{self.profile}@{host}"
+
+
+class KeyringCredentialStore:
+    """Secret store backed by the active system keyring."""
+
+    def __init__(self, backend: KeyringBackend | None = None) -> None:
+        self._backend = backend
+
+    def available(self) -> bool:
+        # Availability is a question, not a failure: callers branch on it to choose the
+        # fallback path, so a broken backend answers False instead of raising.
+        try:
+            return float(self._get_backend().priority) >= _MINIMUM_BACKEND_PRIORITY
+        except (KeyringError, RuntimeError, TypeError, ValueError):
+            return False
+
+    def read(self, profile: str, api_url: str) -> Credentials | None:
+        if not self.available():
+            return None
+        try:
+            value = self._get_backend().get_password(
+                _SERVICE_NAME,
+                CredentialScope(profile, api_url).account,
+            )
+        except KeyringError as error:
+            raise CredentialStoreUnavailable(error) from error
+        if value is None:
+            return None
+        # Deferred: importing at module scope would cycle, since credentials.py needs this
+        # module's scope type to address its own entries.
+        from .credentials import Credentials
+
+        try:
+            return Credentials.from_value(value)
+        except ValidationError as error:
+            raise CredentialStoreUnavailable(error) from error
+
+    def write(self, credentials: Credentials, profile: str, api_url: str) -> None:
+        if not self.available():
+            raise CredentialStoreUnavailable()
+        account = CredentialScope(profile, api_url).account
+        try:
+            backend = self._get_backend()
+            backend.set_password(_SERVICE_NAME, account, credentials.secret_value())
+            read_back = backend.get_password(_SERVICE_NAME, account)
+        except KeyringError as error:
+            raise CredentialStoreUnavailable(error) from error
+        if read_back != credentials.secret_value():
+            raise CredentialStoreUnavailable()
+
+    def clear(self, profile: str, api_url: str) -> bool:
+        if not self.available():
+            return False
+        account = CredentialScope(profile, api_url).account
+        try:
+            backend = self._get_backend()
+            if backend.get_password(_SERVICE_NAME, account) is None:
+                return False
+            backend.delete_password(_SERVICE_NAME, account)
+            return True
+        except KeyringError as error:
+            raise CredentialStoreUnavailable(error) from error
+
+    def _get_backend(self) -> KeyringBackend:
+        # Resolved on first use and cached: backend discovery can open a keychain session,
+        # which must not happen while the command tree is being built.
+        if self._backend is None:
+            self._backend = cast(KeyringBackend, keyring.get_keyring())
+        return self._backend

vidbyte_cli/lib/auth/provider_credentials.py

@@ -0,0 +1,157 @@
+"""Secret-safe provider credential model and file document.
+
+The key is a SecretStr so it stays out of reprs and dumps by default.
+Scopes are profile@provider, not profile@host, so Vidbyte and provider keys never collide.
+"""
+
+from __future__ import annotations
+
+import json
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, ValidationError, field_validator
+
+from ...types.provider import PROVIDER_KEY_PREFIXES, Provider
+from ..config.atomic import AtomicFileWriter
+from ..config.paths import VidbytePaths
+from ..errors.failures import StoredProviderCredentialUnreadable
+from .keyring_store import CredentialScope  # noqa: F401 - re-export scope concept reference
+
+_MAX_CREDENTIAL_BYTES = 1_000_000
+_MAX_KEY_CHARACTERS = 4096
+
+
+class ProviderCredentials(BaseModel):
+    """One provider API token with secret-safe representation."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    provider: Provider
+    api_key: SecretStr
+
+    @field_validator("api_key")
+    @classmethod
+    def validate_api_key(cls, value: SecretStr) -> SecretStr:
+        # Bounds before any network or storage write.
+        if not 1 <= len(value.get_secret_value()) <= _MAX_KEY_CHARACTERS:
+            raise ValueError("API key must contain between 1 and 4096 characters")
+        return value
+
+    @classmethod
+    def is_live_format(cls, provider: Provider, value: str) -> bool:
+        # Prefix: openai/deepseek sk- not sk-ant-; claude sk-ant-; muse LLM|; gemini AIza.
+        if provider == Provider.CLAUDE:
+            return value.startswith("sk-ant-")
+        if provider in (Provider.OPENAI, Provider.DEEPSEEK):
+            return value.startswith("sk-") and not value.startswith("sk-ant-")
+        if provider == Provider.MUSE:
+            return value.startswith("LLM|")
+        if provider == Provider.GEMINI:
+            return value.startswith("AIza")
+        if provider in (Provider.GROK, Provider.GLM):
+            return bool(value)
+        prefixes = PROVIDER_KEY_PREFIXES.get(provider, ())
+        if not prefixes:
+            return bool(value)
+        return any(value.startswith(prefix) for prefix in prefixes)
+
+    def secret_value(self) -> str:
+        # Single deliberate unwrapping point outside the file encoder.
+        return self.api_key.get_secret_value()
+
+
+class ProviderStorage(StrEnum):
+    """Durable storage selected for a verified provider login."""
+
+    KEYRING = "keyring"
+    RESTRICTED_FILE = "restricted_file"
+
+
+class ProviderDocument(BaseModel):
+    """Version-one restricted fallback file for provider keys."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = 1
+    entries: dict[str, SecretStr] = Field(default_factory=dict)
+
+
+class ProviderScope:
+    """The profile and provider that one stored secret belongs to."""
+
+    def __init__(self, profile: str, provider: Provider) -> None:
+        # Minimal scope; provider is already a closed StrEnum.
+        self.profile = profile
+        self.provider = provider
+
+    @property
+    def account(self) -> str:
+        # Mirrors CredentialScope but keyed by provider name.
+        return f"{self.profile}@{self.provider.value}"
+
+
+class FileProviderStore:
+    """Permission-restricted fallback store for provider keys."""
+
+    def __init__(self, paths: VidbytePaths, writer: AtomicFileWriter | None = None) -> None:
+        # Paths injected so tests can point at a temp directory.
+        self._paths = paths
+        self._writer = writer or AtomicFileWriter()
+
+    def read(self, profile: str, provider: Provider) -> ProviderCredentials | None:
+        # Looks up one entry; missing file means no stored key.
+        secret = self._load().entries.get(ProviderScope(profile, provider).account)
+        if secret is None:
+            return None
+        return ProviderCredentials(provider=provider, api_key=secret)
+
+    def write(self, credentials: ProviderCredentials, profile: str, provider: Provider) -> None:
+        # Inserts or replaces one entry and rewrites the whole file atomically.
+        document = self._load()
+        entries = dict(document.entries)
+        entries[ProviderScope(profile, provider).account] = credentials.api_key
+        self._writer.write(
+            self._paths.provider_credentials_file(),
+            self._encode(ProviderDocument(entries=entries)),
+        )
+
+    def clear(self, profile: str, provider: Provider) -> bool:
+        # Removes one entry if present; no-op otherwise.
+        document = self._load()
+        account = ProviderScope(profile, provider).account
+        if account not in document.entries:
+            return False
+        entries = dict(document.entries)
+        del entries[account]
+        self._writer.write(
+            self._paths.provider_credentials_file(),
+            self._encode(ProviderDocument(entries=entries)),
+        )
+        return True
+
+    def _load(self) -> ProviderDocument:
+        # Reads and validates the whole file, bounded before parsing.
+        path = self._paths.provider_credentials_file()
+        if not path.exists():
+            return ProviderDocument()
+        try:
+            raw = path.read_bytes()
+            if len(raw) > _MAX_CREDENTIAL_BYTES:
+                raise ValueError("credential file exceeds the size limit")
+            parsed = json.loads(raw)
+            if isinstance(parsed, dict) and parsed.get("schema_version", 1) != 1:
+                raise ValueError("unsupported credential schema")
+            return ProviderDocument.model_validate(parsed)
+        except (OSError, json.JSONDecodeError, ValidationError, ValueError) as error:
+            raise StoredProviderCredentialUnreadable(error) from error
+
+    def _encode(self, document: ProviderDocument) -> bytes:
+        # One intentional unwrapping point for the restricted file.
+        payload = {
+            "schema_version": document.schema_version,
+            "entries": {
+                account: secret.get_secret_value() for account, secret in document.entries.items()
+            },
+        }
+        return json.dumps(payload, indent=2, sort_keys=True).encode("utf-8") + b"\n"

vidbyte_cli/lib/auth/provider_input.py

@@ -0,0 +1,54 @@
+"""Acquisition of provider tokens via hidden prompt or stdin.
+
+Mirrors CredentialInput but parameterizes by provider so prefix checks are exact.
+"""
+
+from __future__ import annotations
+
+import getpass
+
+from ...types.provider import Provider
+from ..errors.failures import (
+    InvalidProviderApiKeyInput,
+    NoninteractiveProviderLoginRequiresToken,
+    ProviderKeyNotLiveFormat,
+)
+from ..io import IOStreams
+from ..io.terminal import TerminalCapabilities
+from .provider_credentials import ProviderCredentials
+
+_MAX_TOKEN_CHARACTERS = 4096
+
+
+class ProviderCredentialInput:
+    """Acquire one provider token through an explicit secret-safe channel."""
+
+    def __init__(
+        self,
+        streams: IOStreams,
+        terminal: TerminalCapabilities,
+        *,
+        no_input: bool,
+        provider: Provider,
+    ) -> None:
+        # No_input and provider are fixed per command construction.
+        self._streams = streams
+        self._terminal = terminal
+        self._no_input = no_input
+        self._provider = provider
+
+    def read(self, *, from_stdin: bool) -> ProviderCredentials:
+        # Bounded read, then prefix check, so an accidental file redirect fails clearly.
+        if from_stdin:
+            value = self._streams.stdin.read(_MAX_TOKEN_CHARACTERS + 1)
+        else:
+            if self._no_input or not self._terminal.interactive:
+                raise NoninteractiveProviderLoginRequiresToken(self._provider.value)
+            prompt = f"{self._provider.value} API key: "
+            value = getpass.getpass(prompt, stream=self._streams.stderr)
+        token = value.strip()
+        if not token or len(token) > _MAX_TOKEN_CHARACTERS:
+            raise InvalidProviderApiKeyInput(self._provider.value)
+        if not ProviderCredentials.is_live_format(self._provider, token):
+            raise ProviderKeyNotLiveFormat(self._provider.value)
+        return ProviderCredentials(provider=self._provider, api_key=token)  # type: ignore[arg-type]