mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/credential_native.py

@@ -0,0 +1,551 @@
+"""Zero-third-party native protected-store adapters.
+
+The adapter selected for an operating system is final.  A missing, locked, timed-out, or refusing
+native facility is a typed error; this module never catches one and substitutes secure-file.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Protocol
+
+from mostlyright.data_harness.ux.credential_store import (
+    MAX_CREDENTIAL_ENVELOPE_BYTES,
+    CredentialBackend,
+    CredentialStoreError,
+    SecureFileBackend,
+)
+
+_SERVICE = "md.mostlyright.cli"
+_ACCOUNT = "default"
+_SECRET_TOOL_TIMEOUT_SECONDS = 8.0
+_SECRET_TOOL_ATTRIBUTES = ("application", "mostlyright-cli", "profile", "default")
+_DPAPI_FLAGS = 0x1  # CRYPTPROTECT_UI_FORBIDDEN; intentionally excludes LOCAL_MACHINE (0x4).
+
+
+class KeychainFFI(Protocol):
+    def read(self, *, service: str, account: str) -> bytes | None: ...
+
+    def write(self, payload: bytearray, *, service: str, account: str) -> None: ...
+
+    def delete(self, *, service: str, account: str) -> None: ...
+
+
+class DPAPIFFI(Protocol):
+    def protect(self, plaintext: bytearray, *, flags: int) -> bytes: ...
+
+    def unprotect(self, ciphertext: bytes, *, flags: int) -> bytearray: ...
+
+
+class MacOSKeychainBackend:
+    """One Keychain generic-password item through Security.framework item APIs."""
+
+    name = "keychain"
+
+    def __init__(self, *, ffi: KeychainFFI | None = None) -> None:
+        try:
+            self._ffi = ffi or _MacOSSecurityFramework()
+        except Exception:
+            raise _native_refusal("Keychain", "initialization") from None
+
+    def read(self) -> bytes | None:
+        try:
+            payload = self._ffi.read(service=_SERVICE, account=_ACCOUNT)
+            if payload is not None and len(payload) > MAX_CREDENTIAL_ENVELOPE_BYTES:
+                raise ValueError("oversized item")
+            return payload
+        except Exception:
+            raise _native_refusal("Keychain", "copy") from None
+
+    def write(self, payload: bytes) -> None:
+        if len(payload) > MAX_CREDENTIAL_ENVELOPE_BYTES:
+            raise CredentialStoreError(
+                "CREDENTIAL_STORE_CORRUPT", "the protected credential envelope exceeds its limit"
+            )
+        mutable = bytearray(payload)
+        try:
+            self._ffi.write(mutable, service=_SERVICE, account=_ACCOUNT)
+        except Exception:
+            raise _native_refusal("Keychain", "store") from None
+        finally:
+            _zero(mutable)
+
+    def delete(self) -> None:
+        try:
+            self._ffi.delete(service=_SERVICE, account=_ACCOUNT)
+        except Exception:
+            raise _native_refusal("Keychain", "delete") from None
+
+
+class DPAPIBackend:
+    """Current-user DPAPI protection with only the encrypted blob stored atomically."""
+
+    name = "dpapi"
+
+    def __init__(self, config_dir: Path, *, ffi: DPAPIFFI | None = None) -> None:
+        try:
+            self._ffi = ffi or _WindowsDPAPI()
+            # This file contains only DPAPI ciphertext.  Reusing the atomic private-file writer
+            # keeps replace/fsync/link checks identical without making secure-file a fallback.
+            self._blob = SecureFileBackend(
+                config_dir,
+                explicit=True,
+                filename="credentials.dpapi",
+            )
+        except Exception:
+            raise _native_refusal("DPAPI", "initialization") from None
+
+    def read(self) -> bytes | None:
+        plaintext: bytearray | None = None
+        try:
+            ciphertext = self._blob.read()
+            if ciphertext is None:
+                return None
+            plaintext = self._ffi.unprotect(ciphertext, flags=_DPAPI_FLAGS)
+            if len(plaintext) > MAX_CREDENTIAL_ENVELOPE_BYTES:
+                raise ValueError("oversized plaintext")
+            return bytes(plaintext)
+        except Exception:
+            raise _native_refusal("DPAPI", "unprotect") from None
+        finally:
+            if plaintext is not None:
+                _zero(plaintext)
+
+    def write(self, payload: bytes) -> None:
+        if len(payload) > MAX_CREDENTIAL_ENVELOPE_BYTES:
+            raise CredentialStoreError(
+                "CREDENTIAL_STORE_CORRUPT", "the protected credential envelope exceeds its limit"
+            )
+        plaintext = bytearray(payload)
+        try:
+            ciphertext = self._ffi.protect(plaintext, flags=_DPAPI_FLAGS)
+            if not ciphertext or len(ciphertext) > MAX_CREDENTIAL_ENVELOPE_BYTES:
+                raise ValueError("invalid DPAPI ciphertext")
+            self._blob.write(ciphertext)
+        except Exception:
+            raise _native_refusal("DPAPI", "protect") from None
+        finally:
+            _zero(plaintext)
+
+    def delete(self) -> None:
+        try:
+            self._blob.delete()
+        except Exception:
+            raise _native_refusal("DPAPI", "delete") from None
+
+
+class _ProcessResult(Protocol):
+    returncode: int
+    stdout: bytes
+    stderr: bytes
+
+
+_ProcessRunner = Callable[..., _ProcessResult]
+
+
+class SecretServiceBackend:
+    """Linux Secret Service through bounded ``secret-tool`` subprocesses."""
+
+    name = "secret-service"
+
+    def __init__(
+        self,
+        *,
+        executable: str,
+        process_runner: _ProcessRunner | None = None,
+    ) -> None:
+        if not executable:
+            raise _native_refusal("Secret Service", "probe")
+        if process_runner is None:
+            import subprocess
+
+            process_runner = subprocess.run
+        self._executable = executable
+        self._run = process_runner
+
+    def _invoke(self, operation: str, *, payload: bytes | None) -> _ProcessResult:
+        import subprocess
+
+        if operation == "store":
+            args = [
+                self._executable,
+                "store",
+                "--label=Mostly Right CLI",
+                *_SECRET_TOOL_ATTRIBUTES,
+            ]
+        else:
+            args = [self._executable, operation, *_SECRET_TOOL_ATTRIBUTES]
+        try:
+            completed = self._run(
+                args,
+                input=payload,
+                capture_output=True,
+                timeout=_SECRET_TOOL_TIMEOUT_SECONDS,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            raise _native_refusal("Secret Service", operation) from None
+        # Never retain or render subprocess diagnostics.  They may contain the item value, D-Bus
+        # details, a user name, or a hostile canary emitted by an injected executable.
+        if len(completed.stdout or b"") > MAX_CREDENTIAL_ENVELOPE_BYTES:
+            raise _native_refusal("Secret Service", operation)
+        if len(completed.stderr or b"") > MAX_CREDENTIAL_ENVELOPE_BYTES:
+            raise _native_refusal("Secret Service", operation)
+        return completed
+
+    def read(self) -> bytes | None:
+        completed = self._invoke("lookup", payload=None)
+        if completed.returncode == 1 and not completed.stdout and not completed.stderr:
+            return None
+        if completed.returncode != 0:
+            raise _native_refusal("Secret Service", "lookup")
+        if not completed.stdout:
+            raise _native_refusal("Secret Service", "lookup")
+        # ``secret-tool lookup`` appends a newline to its printed secret.  Canonical envelopes do
+        # not contain trailing whitespace, so remove exactly that transport newline and no other
+        # byte.
+        return completed.stdout[:-1] if completed.stdout.endswith(b"\n") else completed.stdout
+
+    def write(self, payload: bytes) -> None:
+        if len(payload) > MAX_CREDENTIAL_ENVELOPE_BYTES:
+            raise CredentialStoreError(
+                "CREDENTIAL_STORE_CORRUPT", "the protected credential envelope exceeds its limit"
+            )
+        completed = self._invoke("store", payload=payload)
+        if completed.returncode != 0:
+            raise _native_refusal("Secret Service", "store")
+
+    def delete(self) -> None:
+        completed = self._invoke("clear", payload=None)
+        if completed.returncode == 1 and not completed.stdout and not completed.stderr:
+            return
+        if completed.returncode != 0:
+            raise _native_refusal("Secret Service", "clear")
+
+
+def native_backend(
+    config_dir: Path,
+    *,
+    platform_name: str | None = None,
+    executable_finder: Callable[[str], str | None] | None = None,
+) -> CredentialBackend:
+    """Select the current OS protected backend, with no fallback on absence or failure."""
+
+    selected = sys.platform if platform_name is None else platform_name
+    try:
+        if selected == "darwin":
+            return MacOSKeychainBackend()
+        if selected == "win32":
+            return DPAPIBackend(config_dir)
+        if selected.startswith("linux"):
+            if executable_finder is None:
+                import shutil
+
+                executable_finder = shutil.which
+            executable = executable_finder("secret-tool")
+            if executable is None:
+                raise CredentialStoreError(
+                    "CREDENTIAL_STORE_UNAVAILABLE",
+                    "Secret Service probe failed; explicitly select "
+                    "--credential-store secure-file to use an owner-controlled file",
+                )
+            return SecretServiceBackend(executable=executable)
+    except CredentialStoreError:
+        raise
+    except Exception:
+        pass
+    raise CredentialStoreError(
+        "CREDENTIAL_STORE_UNAVAILABLE",
+        "native protected storage is unavailable; explicitly select "
+        "--credential-store secure-file to use an owner-controlled file",
+    )
+
+
+def _native_refusal(adapter: str, outcome: str) -> CredentialStoreError:
+    return CredentialStoreError(
+        "CREDENTIAL_STORE_UNAVAILABLE",
+        f"{adapter} {outcome} failed",
+    )
+
+
+def _zero(value: bytearray) -> None:
+    for index in range(len(value)):
+        value[index] = 0
+
+
+class _WindowsDPAPI:
+    def __init__(self) -> None:
+        import ctypes
+
+        if sys.platform != "win32":
+            raise OSError("DPAPI is not available")
+        self._ctypes = ctypes
+
+        class DataBlob(ctypes.Structure):
+            _fields_ = [
+                ("cbData", ctypes.c_uint32),
+                ("pbData", ctypes.POINTER(ctypes.c_ubyte)),
+            ]
+
+        self._blob_type = DataBlob
+        self._crypt32 = ctypes.WinDLL("crypt32", use_last_error=True)
+        self._kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        self._crypt32.CryptProtectData.argtypes = [
+            ctypes.POINTER(DataBlob),
+            ctypes.c_wchar_p,
+            ctypes.POINTER(DataBlob),
+            ctypes.c_void_p,
+            ctypes.c_void_p,
+            ctypes.c_uint32,
+            ctypes.POINTER(DataBlob),
+        ]
+        self._crypt32.CryptProtectData.restype = ctypes.c_int
+        self._crypt32.CryptUnprotectData.argtypes = [
+            ctypes.POINTER(DataBlob),
+            ctypes.c_void_p,
+            ctypes.POINTER(DataBlob),
+            ctypes.c_void_p,
+            ctypes.c_void_p,
+            ctypes.c_uint32,
+            ctypes.POINTER(DataBlob),
+        ]
+        self._crypt32.CryptUnprotectData.restype = ctypes.c_int
+        self._kernel32.LocalFree.argtypes = [ctypes.c_void_p]
+        self._kernel32.LocalFree.restype = ctypes.c_void_p
+
+    def _input_blob(self, value: bytearray | bytes) -> tuple[object, object]:
+        ctypes = self._ctypes
+        if isinstance(value, bytearray):
+            buffer = (ctypes.c_ubyte * len(value)).from_buffer(value)
+        else:
+            buffer = (ctypes.c_ubyte * len(value)).from_buffer_copy(value)
+        return (
+            self._blob_type(len(value), ctypes.cast(buffer, ctypes.POINTER(ctypes.c_ubyte))),
+            buffer,
+        )
+
+    def protect(self, plaintext: bytearray, *, flags: int) -> bytes:
+        ctypes = self._ctypes
+        source, keepalive = self._input_blob(plaintext)
+        result = self._blob_type()
+        if not self._crypt32.CryptProtectData(
+            ctypes.byref(source), None, None, None, None, flags, ctypes.byref(result)
+        ):
+            raise OSError("CryptProtectData failed")
+        try:
+            return ctypes.string_at(result.pbData, result.cbData)
+        finally:
+            del keepalive
+            self._kernel32.LocalFree(result.pbData)
+
+    def unprotect(self, ciphertext: bytes, *, flags: int) -> bytearray:
+        ctypes = self._ctypes
+        source, keepalive = self._input_blob(ciphertext)
+        result = self._blob_type()
+        if not self._crypt32.CryptUnprotectData(
+            ctypes.byref(source), None, None, None, None, flags, ctypes.byref(result)
+        ):
+            raise OSError("CryptUnprotectData failed")
+        try:
+            plaintext = bytearray(ctypes.string_at(result.pbData, result.cbData))
+            ctypes.memset(result.pbData, 0, result.cbData)
+            return plaintext
+        finally:
+            del keepalive
+            self._kernel32.LocalFree(result.pbData)
+
+
+class _MacOSSecurityFramework:
+    """Small CoreFoundation bridge for four Security.framework item operations."""
+
+    _SUCCESS = 0
+    _DUPLICATE = -25299
+    _NOT_FOUND = -25300
+    _UTF8 = 0x08000100
+
+    def __init__(self) -> None:
+        import ctypes
+        import ctypes.util
+
+        if sys.platform != "darwin":
+            raise OSError("Security.framework is not available")
+        self._ctypes = ctypes
+        security_path = ctypes.util.find_library("Security")
+        core_path = ctypes.util.find_library("CoreFoundation")
+        if not security_path or not core_path:
+            raise OSError("framework unavailable")
+        self._security = ctypes.CDLL(security_path)
+        self._core = ctypes.CDLL(core_path)
+        self._configure()
+        self._class = self._constant(self._security, "kSecClass")
+        self._generic = self._constant(self._security, "kSecClassGenericPassword")
+        self._service = self._constant(self._security, "kSecAttrService")
+        self._account = self._constant(self._security, "kSecAttrAccount")
+        self._value = self._constant(self._security, "kSecValueData")
+        self._return_data = self._constant(self._security, "kSecReturnData")
+        self._match_limit = self._constant(self._security, "kSecMatchLimit")
+        self._match_one = self._constant(self._security, "kSecMatchLimitOne")
+        self._true = self._constant(self._core, "kCFBooleanTrue")
+
+    def _constant(self, library: object, name: str) -> int:
+        ctypes = self._ctypes
+        value = ctypes.c_void_p.in_dll(library, name).value
+        if value is None:
+            raise OSError("framework constant unavailable")
+        return value
+
+    def _configure(self) -> None:
+        ctypes = self._ctypes
+        self._core.CFStringCreateWithBytes.argtypes = [
+            ctypes.c_void_p,
+            ctypes.c_void_p,
+            ctypes.c_long,
+            ctypes.c_uint32,
+            ctypes.c_bool,
+        ]
+        self._core.CFStringCreateWithBytes.restype = ctypes.c_void_p
+        self._core.CFDataCreate.argtypes = [ctypes.c_void_p, ctypes.c_void_p, ctypes.c_long]
+        self._core.CFDataCreate.restype = ctypes.c_void_p
+        self._core.CFDataGetLength.argtypes = [ctypes.c_void_p]
+        self._core.CFDataGetLength.restype = ctypes.c_long
+        self._core.CFDataGetBytePtr.argtypes = [ctypes.c_void_p]
+        self._core.CFDataGetBytePtr.restype = ctypes.POINTER(ctypes.c_ubyte)
+        self._core.CFDictionaryCreate.argtypes = [
+            ctypes.c_void_p,
+            ctypes.c_void_p,
+            ctypes.c_void_p,
+            ctypes.c_long,
+            ctypes.c_void_p,
+            ctypes.c_void_p,
+        ]
+        self._core.CFDictionaryCreate.restype = ctypes.c_void_p
+        self._core.CFRelease.argtypes = [ctypes.c_void_p]
+        self._security.SecItemCopyMatching.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
+        self._security.SecItemCopyMatching.restype = ctypes.c_int32
+        self._security.SecItemAdd.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
+        self._security.SecItemAdd.restype = ctypes.c_int32
+        self._security.SecItemUpdate.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
+        self._security.SecItemUpdate.restype = ctypes.c_int32
+        self._security.SecItemDelete.argtypes = [ctypes.c_void_p]
+        self._security.SecItemDelete.restype = ctypes.c_int32
+
+    def _string(self, value: str) -> int:
+        ctypes = self._ctypes
+        raw = value.encode("utf-8")
+        buffer = ctypes.create_string_buffer(raw)
+        result = self._core.CFStringCreateWithBytes(None, buffer, len(raw), self._UTF8, False)
+        if not result:
+            raise OSError("CFString allocation failed")
+        return result
+
+    def _data(self, value: bytearray) -> int:
+        ctypes = self._ctypes
+        buffer = (ctypes.c_ubyte * len(value)).from_buffer(value)
+        result = self._core.CFDataCreate(None, buffer, len(value))
+        if not result:
+            raise OSError("CFData allocation failed")
+        return result
+
+    def _dictionary(self, items: list[tuple[int, int]]) -> int:
+        ctypes = self._ctypes
+        keys = (ctypes.c_void_p * len(items))(*(key for key, _ in items))
+        values = (ctypes.c_void_p * len(items))(*(value for _, value in items))
+        result = self._core.CFDictionaryCreate(None, keys, values, len(items), None, None)
+        if not result:
+            raise OSError("CFDictionary allocation failed")
+        return result
+
+    def _query(self, service: str, account: str) -> tuple[int, list[int]]:
+        service_ref = self._string(service)
+        account_ref = self._string(account)
+        query = self._dictionary(
+            [
+                (self._class, self._generic),
+                (self._service, service_ref),
+                (self._account, account_ref),
+            ]
+        )
+        return query, [service_ref, account_ref]
+
+    def _release_all(self, values: list[int]) -> None:
+        for value in reversed(values):
+            self._core.CFRelease(value)
+
+    def read(self, *, service: str, account: str) -> bytes | None:
+        ctypes = self._ctypes
+        query, owned = self._query(service, account)
+        rich_query = self._dictionary(
+            [
+                (self._class, self._generic),
+                (self._service, owned[0]),
+                (self._account, owned[1]),
+                (self._return_data, self._true),
+                (self._match_limit, self._match_one),
+            ]
+        )
+        self._core.CFRelease(query)
+        result = ctypes.c_void_p()
+        try:
+            status = self._security.SecItemCopyMatching(rich_query, ctypes.byref(result))
+            if status == self._NOT_FOUND:
+                return None
+            if status != self._SUCCESS or not result.value:
+                raise OSError("SecItemCopyMatching failed")
+            length = self._core.CFDataGetLength(result)
+            if length < 0 or length > MAX_CREDENTIAL_ENVELOPE_BYTES:
+                raise OSError("invalid Keychain item size")
+            return ctypes.string_at(self._core.CFDataGetBytePtr(result), length)
+        finally:
+            if result.value:
+                self._core.CFRelease(result)
+            self._core.CFRelease(rich_query)
+            self._release_all(owned)
+
+    def write(self, payload: bytearray, *, service: str, account: str) -> None:
+        query, owned = self._query(service, account)
+        data = self._data(payload)
+        attributes = self._dictionary([(self._value, data)])
+        try:
+            status = self._security.SecItemUpdate(query, attributes)
+            if status == self._NOT_FOUND:
+                add = self._dictionary(
+                    [
+                        (self._class, self._generic),
+                        (self._service, owned[0]),
+                        (self._account, owned[1]),
+                        (self._value, data),
+                    ]
+                )
+                try:
+                    status = self._security.SecItemAdd(add, None)
+                finally:
+                    self._core.CFRelease(add)
+                if status == self._DUPLICATE:
+                    status = self._security.SecItemUpdate(query, attributes)
+            if status != self._SUCCESS:
+                raise OSError("Keychain write failed")
+        finally:
+            self._core.CFRelease(attributes)
+            self._core.CFRelease(data)
+            self._core.CFRelease(query)
+            self._release_all(owned)
+
+    def delete(self, *, service: str, account: str) -> None:
+        query, owned = self._query(service, account)
+        try:
+            status = self._security.SecItemDelete(query)
+            if status not in {self._SUCCESS, self._NOT_FOUND}:
+                raise OSError("SecItemDelete failed")
+        finally:
+            self._core.CFRelease(query)
+            self._release_all(owned)
+
+
+__all__ = [
+    "DPAPIBackend",
+    "MacOSKeychainBackend",
+    "SecretServiceBackend",
+    "native_backend",
+]