mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/credentials.py

@@ -0,0 +1,631 @@
+"""Effective credential resolution and one-way protected-store migration.
+
+``~/.mostlyright/credentials`` is either the strict seven-field legacy object (only until verified
+migration) or a two-field non-secret backend manifest.  Raw keys otherwise exist only in the
+selected protected backend and in the explicitly redacted values returned to cloud transports.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import secrets
+import stat
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.canonical import (
+    CanonicalJSONError,
+    canonical_json_bytes,
+    parse_canonical_json,
+)
+from mostlyright.data_harness.key_seam import LEGACY_API_KEY_ENV
+from mostlyright.data_harness.ux.credential_native import native_backend
+from mostlyright.data_harness.ux.credential_store import (
+    CredentialBackend,
+    CredentialEnvelope,
+    CredentialStore,
+    CredentialStoreError,
+    ProtectedCredential,
+    SecureFileBackend,
+    _windows_acl_is_private,
+    credential_lock,
+)
+
+CREDENTIALS_DIR_NAME = ".mostlyright"
+CREDENTIALS_FILENAME = "credentials"
+MAX_CREDENTIALS_FILE_BYTES = 64 * 1024
+CREDENTIAL_MANIFEST_SCHEMA = "mr-data-credential-manifest.v1"
+
+_REQUIRED_FIELDS = frozenset(
+    {"cloud_url", "key_id", "prefix", "last_four", "device_name", "created_at", "raw_key"}
+)
+_MANIFEST_FIELDS = frozenset({"schema_version", "backend"})
+_BACKENDS = frozenset({"keychain", "dpapi", "secret-service", "secure-file"})
+
+CLOUD_URL_ENV = "MOSTLYRIGHT_CLOUD_URL"
+DEFAULT_CLOUD_URL = "https://mostlyright.md"
+
+
+class LoginError(RuntimeError):
+    """A fail-closed login/storage failure whose detail is always safe to print."""
+
+    def __init__(self, code: str, detail: str) -> None:
+        super().__init__(f"{code}: {detail}")
+        self.code = code
+        self.detail = detail
+
+
+@dataclass(frozen=True)
+class StoredCredentials:
+    """One stored 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 __repr__(self) -> str:
+        return (
+            "StoredCredentials("
+            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 to_receipt(self) -> dict[str, Any]:
+        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,
+        }
+
+    def _protected(self) -> ProtectedCredential:
+        try:
+            return ProtectedCredential(
+                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,
+            )
+        except CredentialStoreError as error:
+            raise LoginError(
+                "LOGIN_CREDENTIALS_UNREADABLE", "the credential contains an invalid field"
+            ) from error
+
+    @classmethod
+    def _from_protected(cls, value: ProtectedCredential) -> StoredCredentials:
+        return cls(
+            cloud_url=value.cloud_url,
+            key_id=value.key_id,
+            prefix=value.prefix,
+            last_four=value.last_four,
+            device_name=value.device_name,
+            created_at=value.created_at,
+            raw_key=value.raw_key,
+        )
+
+
+@dataclass(frozen=True)
+class ResolvedCloudCredentials:
+    """One raw transport credential with safe receipt and representation projections."""
+
+    cloud_url: str
+    raw_key: str
+    source: str
+
+    def __repr__(self) -> str:
+        return (
+            "ResolvedCloudCredentials("
+            f"cloud_url={self.cloud_url!r}, raw_key='<redacted>', source={self.source!r})"
+        )
+
+    def to_receipt(self) -> dict[str, str]:
+        return {"cloud_url": self.cloud_url, "source": self.source}
+
+
+def default_credentials_dir() -> Path:
+    return Path.home() / CREDENTIALS_DIR_NAME
+
+
+def credentials_path(config_dir: Path | None = None) -> Path:
+    return (config_dir or default_credentials_dir()) / CREDENTIALS_FILENAME
+
+
+def refuse_existing_credentials(*, config_dir: Path | None = None) -> None:
+    path = credentials_path(config_dir)
+    if os.path.lexists(path):
+        raise LoginError(
+            "LOGIN_CREDENTIALS_EXIST",
+            f"a stored credential already exists at {path}; pass --force to overwrite it",
+        )
+
+
+def store_credentials(
+    credentials: StoredCredentials,
+    *,
+    config_dir: Path | None = None,
+    force: bool = False,
+    credential_store: str | None = None,
+) -> Path:
+    """Install one active credential in the selected protected backend."""
+
+    directory = config_dir or default_credentials_dir()
+    path = directory / CREDENTIALS_FILENAME
+    selector = _selector(credential_store)
+    try:
+        with credential_lock(directory):
+            if os.path.lexists(path) and not force:
+                # This remains a second direct raise site because the preflight above is only a
+                # courtesy check; a competing writer may win between it and this locked gate.
+                raise LoginError(
+                    "LOGIN_CREDENTIALS_EXIST",
+                    f"a stored credential already exists at {path}; pass --force to overwrite it",
+                )
+            control = _read_control(path)
+            if control is None:
+                backend = _backend_for(directory, selector or _native_backend_name(directory))
+                current = None
+            else:
+                kind, value = _parse_control(control, path)
+                if kind == "legacy":
+                    backend = _backend_for(directory, selector or _native_backend_name(directory))
+                    current = None
+                else:
+                    backend_name = value["backend"]
+                    _require_selector_agrees(selector, backend_name)
+                    backend = _backend_for(directory, backend_name)
+                    current = _load_envelope(directory, backend)
+            generation = 1 if current is None else current.generation + 1
+            envelope = CredentialEnvelope.active_envelope(
+                generation=generation,
+                active=credentials._protected(),
+            )
+            _write_envelope(directory, backend, envelope)
+            _require_readback(directory, backend, envelope)
+            _install_manifest(path, backend.name)
+            return path
+    except LoginError:
+        raise
+    except CredentialStoreError as error:
+        raise _login_store_error(error) from None
+    except OSError:
+        raise LoginError(
+            "LOGIN_CREDENTIAL_MIGRATION_FAILED",
+            f"the credential manifest at {path} could not be installed",
+        ) from None
+
+
+def read_credentials(
+    *,
+    config_dir: Path | None = None,
+    credential_store: str | None = None,
+) -> StoredCredentials | None:
+    """Read active protected credentials, migrating an exact safe legacy file once."""
+
+    directory = config_dir or default_credentials_dir()
+    path = directory / CREDENTIALS_FILENAME
+    selector = _selector(credential_store)
+    if not os.path.lexists(path):
+        return None
+    try:
+        with credential_lock(directory):
+            raw = _read_control(path)
+            if raw is None:
+                return None
+            kind, value = _parse_control(raw, path)
+            if kind == "manifest":
+                backend_name = value["backend"]
+                _require_selector_agrees(selector, backend_name)
+                envelope = _load_envelope(directory, _backend_for(directory, backend_name))
+                return _active_credentials(envelope)
+
+            legacy = _legacy_credentials(value, path)
+            backend = _backend_for(directory, selector or _native_backend_name(directory))
+            envelope = CredentialEnvelope.active_envelope(
+                generation=1,
+                active=legacy._protected(),
+            )
+            _write_envelope(directory, backend, envelope)
+            _require_readback(directory, backend, envelope)
+            try:
+                _install_manifest(path, backend.name)
+            except OSError:
+                raise LoginError(
+                    "LOGIN_CREDENTIAL_MIGRATION_FAILED",
+                    f"the legacy credential at {path} remains recoverable because migration "
+                    "could not finish",
+                ) from None
+            return legacy
+    except LoginError:
+        raise
+    except CredentialStoreError as error:
+        raise _login_store_error(error) from None
+    except OSError:
+        raise LoginError(
+            "LOGIN_CREDENTIALS_UNREADABLE",
+            f"the stored credential at {path} could not be read",
+        ) from None
+
+
+def resolve_cloud_credentials(
+    *,
+    environment: Mapping[str, str] | None = None,
+    config_dir: Path | None = None,
+    credential_store: str | None = None,
+) -> ResolvedCloudCredentials:
+    values = os.environ if environment is None else environment
+    if LEGACY_API_KEY_ENV in values:
+        raw_key = values[LEGACY_API_KEY_ENV]
+        if not isinstance(raw_key, str) or not raw_key.strip():
+            raise LoginError(
+                "LOGIN_API_KEY_INVALID",
+                f"{LEGACY_API_KEY_ENV} is set but does not contain a credential",
+            )
+        return ResolvedCloudCredentials(
+            cloud_url=values.get(CLOUD_URL_ENV) or DEFAULT_CLOUD_URL,
+            raw_key=raw_key,
+            source="environment",
+        )
+    stored = read_credentials(config_dir=config_dir, credential_store=credential_store)
+    if stored is None:
+        raise LoginError(
+            "LOGIN_REQUIRED",
+            "this cloud command needs a device credential; run mr-data login first",
+        )
+    return ResolvedCloudCredentials(
+        cloud_url=stored.cloud_url,
+        raw_key=stored.raw_key,
+        source="stored_device",
+    )
+
+
+def credential_transaction_store(
+    *,
+    config_dir: Path | None = None,
+    credential_store: str | None = None,
+) -> tuple[CredentialStore, Path] | None:
+    """Return the selected protected store and its non-secret manifest path.
+
+    Mutating lifecycle commands use this narrow helper rather than reimplementing backend
+    selection.  A legacy control file is migrated through the existing verified migration path
+    before its backend is returned; a pending envelope is deliberately returned rather than
+    flattened through :func:`read_credentials`.
+    """
+
+    directory = config_dir or default_credentials_dir()
+    path = directory / CREDENTIALS_FILENAME
+    selector = _selector(credential_store)
+    if not os.path.lexists(path):
+        backend = _backend_for(directory, selector or _native_backend_name(directory))
+        return CredentialStore(directory, backend), path
+    raw = _read_control(path)
+    if raw is None:
+        return None
+    kind, value = _parse_control(raw, path)
+    if kind == "legacy":
+        # This call owns the migration lock and preserves the legacy bytes on every failure.
+        read_credentials(config_dir=directory, credential_store=selector)
+        raw = _read_control(path)
+        if raw is None:
+            return None
+        kind, value = _parse_control(raw, path)
+    if kind != "manifest":
+        raise LoginError("LOGIN_CREDENTIALS_UNREADABLE", "the stored credential is unreadable")
+    backend_name = value["backend"]
+    _require_selector_agrees(selector, backend_name)
+    return CredentialStore(directory, _backend_for(directory, backend_name)), path
+
+
+def remove_credential_manifest_under_held_lock(path: Path) -> None:
+    """Delete the non-secret control record after protected cleanup succeeds.
+
+    Callers hold the matching per-config lock.  Validate the exact regular manifest immediately
+    before unlinking so a lifecycle cleanup cannot remove a substituted filesystem object.
+    """
+
+    raw = _read_control(path)
+    if raw is None:
+        return
+    kind, _value = _parse_control(raw, path)
+    if kind != "manifest":
+        raise LoginError("LOGIN_CREDENTIALS_UNREADABLE", "the stored credential is unreadable")
+    try:
+        path.unlink()
+    except OSError:
+        raise LoginError(
+            "LOGIN_CREDENTIAL_MIGRATION_FAILED",
+            "the local credential manifest could not be removed",
+        ) from None
+
+
+def install_credential_manifest(path: Path, backend_name: str) -> None:
+    """Durably publish the non-secret backend selector after a protected write."""
+
+    _install_manifest(path, backend_name)
+
+
+def whoami_payload(
+    *,
+    config_dir: Path | None = None,
+    credential_store: str | None = None,
+) -> dict[str, Any]:
+    path = credentials_path(config_dir)
+    credentials = read_credentials(config_dir=config_dir, credential_store=credential_store)
+    if credentials is None:
+        return {
+            "schema_version": "mr-data-whoami.v1",
+            "status": "not_authenticated",
+            "credentials_path": str(path),
+        }
+    return {
+        "schema_version": "mr-data-whoami.v1",
+        "status": "authenticated",
+        **credentials.to_receipt(),
+        "credentials_path": str(path),
+    }
+
+
+def _selector(value: str | None) -> str | None:
+    if value is None:
+        return None
+    if value != "secure-file":
+        raise LoginError(
+            "LOGIN_CREDENTIAL_STORE_INVALID",
+            "credential store must be the exact value secure-file when explicitly selected",
+        )
+    return value
+
+
+def _native_backend_name(directory: Path) -> str:
+    try:
+        return native_backend(directory).name
+    except CredentialStoreError as error:
+        raise _login_store_error(error) from None
+
+
+def _backend_for(directory: Path, backend_name: str) -> CredentialBackend:
+    if backend_name == "secure-file":
+        return SecureFileBackend(directory, explicit=True)
+    try:
+        backend = native_backend(directory)
+    except CredentialStoreError as error:
+        raise _login_store_error(error) from None
+    if backend.name != backend_name:
+        raise LoginError(
+            "LOGIN_CREDENTIAL_STORE_UNAVAILABLE",
+            f"the credential manifest names {backend_name}, which is unavailable on this system",
+        )
+    return backend
+
+
+def _require_selector_agrees(selector: str | None, backend_name: str) -> None:
+    if selector is not None and selector != backend_name:
+        raise LoginError(
+            "LOGIN_CREDENTIAL_STORE_CONFLICT",
+            f"the stored credential uses {backend_name}; the explicit selector does not agree",
+        )
+
+
+def _load_envelope(directory: Path, backend: CredentialBackend) -> CredentialEnvelope | None:
+    return CredentialStore(directory, backend).load_under_held_lock()
+
+
+def _write_envelope(
+    directory: Path,
+    backend: CredentialBackend,
+    envelope: CredentialEnvelope,
+) -> None:
+    CredentialStore(directory, backend).write_under_held_lock(envelope)
+
+
+def _active_credentials(envelope: CredentialEnvelope | None) -> StoredCredentials | None:
+    if envelope is None:
+        return None
+    if envelope.state != "active" or envelope.active is None:
+        detail = (
+            "a device login is pending and its remote mint outcome is unproved"
+            if envelope.state == "login_pending"
+            else "the stored credential has a pending recovery operation"
+        )
+        raise LoginError("LOGIN_CREDENTIAL_RECOVERY_REQUIRED", detail)
+    return StoredCredentials._from_protected(envelope.active)
+
+
+def _require_readback(
+    directory: Path,
+    backend: CredentialBackend,
+    expected: CredentialEnvelope,
+) -> None:
+    actual = _load_envelope(directory, backend)
+    if actual != expected or actual is None or actual.to_bytes() != expected.to_bytes():
+        raise CredentialStoreError(
+            "CREDENTIAL_STORE_READBACK_FAILED",
+            "the protected credential did not verify after write",
+        )
+
+
+def _read_control(path: Path) -> bytes | None:
+    try:
+        descriptor = os.open(
+            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(path):
+            raise LoginError(
+                "LOGIN_CREDENTIALS_UNREADABLE",
+                f"the stored credential at {path} could not be read",
+            ) from None
+        return None
+    except OSError:
+        raise LoginError(
+            "LOGIN_CREDENTIALS_UNREADABLE", f"the stored credential at {path} could not be read"
+        ) from None
+    try:
+        info = os.fstat(descriptor)
+        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 = valid and _windows_acl_is_private(path)
+        if not valid or info.st_size > MAX_CREDENTIALS_FILE_BYTES:
+            raise LoginError(
+                "LOGIN_CREDENTIALS_UNREADABLE",
+                f"the stored credential at {path} could not be read",
+            )
+        raw = bytearray()
+        while len(raw) <= MAX_CREDENTIALS_FILE_BYTES:
+            chunk = os.read(descriptor, min(16 * 1024, MAX_CREDENTIALS_FILE_BYTES + 1 - len(raw)))
+            if not chunk:
+                break
+            raw.extend(chunk)
+        if len(raw) > MAX_CREDENTIALS_FILE_BYTES:
+            raise LoginError(
+                "LOGIN_CREDENTIALS_UNREADABLE",
+                f"the stored credential at {path} could not be read",
+            )
+        return bytes(raw)
+    finally:
+        os.close(descriptor)
+
+
+def _parse_control(raw: bytes, path: Path) -> tuple[str, dict[str, Any]]:
+    try:
+        value = parse_canonical_json(raw)
+    except CanonicalJSONError:
+        raise LoginError(
+            "LOGIN_CREDENTIALS_UNREADABLE",
+            f"the stored credential at {path} is not the file this command writes",
+        ) from None
+    if not isinstance(value, dict):
+        raise LoginError(
+            "LOGIN_CREDENTIALS_UNREADABLE",
+            f"the stored credential at {path} is not the file this command writes",
+        )
+    if set(value) == _MANIFEST_FIELDS:
+        if (
+            value.get("schema_version") != CREDENTIAL_MANIFEST_SCHEMA
+            or value.get("backend") not in _BACKENDS
+        ):
+            raise LoginError(
+                "LOGIN_CREDENTIALS_UNREADABLE",
+                f"the stored credential at {path} is not the file this command writes",
+            )
+        return "manifest", value
+    if set(value) == _REQUIRED_FIELDS:
+        return "legacy", value
+    raise LoginError(
+        "LOGIN_CREDENTIALS_UNREADABLE",
+        f"the stored credential at {path} is not the file this command writes",
+    )
+
+
+def _legacy_credentials(value: dict[str, Any], path: Path) -> StoredCredentials:
+    if any(not isinstance(value[field], str) or not value[field] for field in _REQUIRED_FIELDS):
+        raise LoginError(
+            "LOGIN_CREDENTIALS_UNREADABLE",
+            f"the stored credential at {path} is not the file this command writes",
+        )
+    return StoredCredentials(**{field: value[field] for field in _REQUIRED_FIELDS})
+
+
+def _install_manifest(path: Path, backend_name: str) -> None:
+    payload = canonical_json_bytes(
+        {"backend": backend_name, "schema_version": CREDENTIAL_MANIFEST_SCHEMA}
+    )
+    stage = path.parent / f".{path.name}.{secrets.token_hex(16)}.stage"
+    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 manifest write")
+            offset += written
+        os.fsync(descriptor)
+        os.close(descriptor)
+        descriptor = None
+        os.replace(stage, path)
+        if os.name == "posix":
+            directory_fd = os.open(
+                path.parent,
+                os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
+            )
+            os.fsync(directory_fd)
+    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 _login_store_error(error: CredentialStoreError) -> LoginError:
+    suffix = error.code.removeprefix("CREDENTIAL_")
+    details = {
+        "CREDENTIAL_STORE_UNAVAILABLE": (
+            "native protected storage is unavailable; explicitly select "
+            "--credential-store secure-file to use an owner-controlled file"
+        ),
+        "CREDENTIAL_STORE_WRITE_FAILED": "the protected credential could not be written",
+        "CREDENTIAL_STORE_READBACK_FAILED": (
+            "the protected credential could not be verified after writing"
+        ),
+        "CREDENTIAL_STORE_PERMISSIONS": ("the selected credential store is not owner controlled"),
+        "CREDENTIAL_STORE_CORRUPT": "the protected credential is unreadable",
+        "CREDENTIAL_LOCKED": "another credential operation is already running",
+        "CREDENTIAL_LOCK_UNAVAILABLE": "the credential operation lock is unavailable",
+    }
+    return LoginError(
+        f"LOGIN_CREDENTIAL_{suffix}",
+        details.get(error.code, "the protected credential operation failed"),
+    )
+
+
+__all__ = [
+    "CLOUD_URL_ENV",
+    "CREDENTIALS_DIR_NAME",
+    "CREDENTIALS_FILENAME",
+    "DEFAULT_CLOUD_URL",
+    "LoginError",
+    "ResolvedCloudCredentials",
+    "StoredCredentials",
+    "credential_transaction_store",
+    "credentials_path",
+    "default_credentials_dir",
+    "install_credential_manifest",
+    "read_credentials",
+    "refuse_existing_credentials",
+    "remove_credential_manifest_under_held_lock",
+    "resolve_cloud_credentials",
+    "store_credentials",
+    "whoami_payload",
+]