mevault 0.1.0__tar.gz

mevault-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.egg

mevault-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: mevault
+Version: 0.1.0
+Summary: MeVault Python SDK — request secrets from the local MeVault broker
+Project-URL: Homepage, https://github.com/thecalebyte/mevault-cli
+Project-URL: Documentation, https://github.com/thecalebyte/mevault-cli/blob/main/docs/sdk.md
+Project-URL: Bug Tracker, https://github.com/thecalebyte/mevault-cli/issues
+License: Apache-2.0
+Keywords: credentials,mevault,secrets,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# MeVault Python SDK
+
+Request secrets from the [MeVault](https://github.com/thecalebyte/mevault-cli) broker in Python — no passwords, no env-var leakage, no subprocesses.
+
+## Requirements
+
+- Python 3.9+
+- Windows (the broker communicates over a Windows named pipe)
+- MeVault broker running and vault unlocked
+
+## Installation
+
+```bash
+pip install mevault
+```
+
+Or from source:
+
+```bash
+cd sdk/python
+pip install -e .
+```
+
+## Usage
+
+### Synchronous
+
+```python
+from mevault import get_secret, get_optional_secret
+from mevault.exceptions import VaultLocked, SecretNotFound, MeVaultUnavailable
+
+# Raises SecretNotFound if the secret doesn't exist.
+db_password = get_secret("DB_PASSWORD")
+
+# Returns None (or a custom default) if the secret doesn't exist.
+api_key = get_optional_secret("OPTIONAL_API_KEY", default="")
+```
+
+### Asynchronous
+
+```python
+import asyncio
+from mevault import async_get_secret
+
+async def main():
+    token = await async_get_secret("AUTH_TOKEN")
+    # use token ...
+
+asyncio.run(main())
+```
+
+## Error handling
+
+| Exception | When raised |
+|---|---|
+| `MeVaultUnavailable` | Broker not running / pipe not found |
+| `VaultLocked` | Vault is locked — user must unlock MeVault |
+| `SecretNotFound` | No secret with that name |
+| `AccessDenied` | Process not permitted to read the secret |
+| `SessionExpired` | Broker session expired — user must re-authenticate |
+| `ProtocolError` | Malformed or oversized broker response |
+
+All exceptions derive from `MeVaultError`.
+
+```python
+from mevault.exceptions import MeVaultError
+
+try:
+    value = get_secret("MY_SECRET")
+except MeVaultError as exc:
+    # Handle any MeVault error generically.
+    print(f"MeVault error: {exc}")
+```
+
+## Security notes
+
+- Secret values are **never** logged or printed by the SDK.
+- `SecretValue.__repr__` and `__str__` return `<redacted>` to prevent accidental exposure in logs or tracebacks.
+- The SDK does **not** accept vault passwords and does **not** spawn subprocesses.
+- The SDK does **not** place secrets in environment variables.
+- Each request uses a fresh pipe connection, closed immediately after the response is received.

mevault-0.1.0/README.md

@@ -0,0 +1,81 @@
+# MeVault Python SDK
+
+Request secrets from the [MeVault](https://github.com/thecalebyte/mevault-cli) broker in Python — no passwords, no env-var leakage, no subprocesses.
+
+## Requirements
+
+- Python 3.9+
+- Windows (the broker communicates over a Windows named pipe)
+- MeVault broker running and vault unlocked
+
+## Installation
+
+```bash
+pip install mevault
+```
+
+Or from source:
+
+```bash
+cd sdk/python
+pip install -e .
+```
+
+## Usage
+
+### Synchronous
+
+```python
+from mevault import get_secret, get_optional_secret
+from mevault.exceptions import VaultLocked, SecretNotFound, MeVaultUnavailable
+
+# Raises SecretNotFound if the secret doesn't exist.
+db_password = get_secret("DB_PASSWORD")
+
+# Returns None (or a custom default) if the secret doesn't exist.
+api_key = get_optional_secret("OPTIONAL_API_KEY", default="")
+```
+
+### Asynchronous
+
+```python
+import asyncio
+from mevault import async_get_secret
+
+async def main():
+    token = await async_get_secret("AUTH_TOKEN")
+    # use token ...
+
+asyncio.run(main())
+```
+
+## Error handling
+
+| Exception | When raised |
+|---|---|
+| `MeVaultUnavailable` | Broker not running / pipe not found |
+| `VaultLocked` | Vault is locked — user must unlock MeVault |
+| `SecretNotFound` | No secret with that name |
+| `AccessDenied` | Process not permitted to read the secret |
+| `SessionExpired` | Broker session expired — user must re-authenticate |
+| `ProtocolError` | Malformed or oversized broker response |
+
+All exceptions derive from `MeVaultError`.
+
+```python
+from mevault.exceptions import MeVaultError
+
+try:
+    value = get_secret("MY_SECRET")
+except MeVaultError as exc:
+    # Handle any MeVault error generically.
+    print(f"MeVault error: {exc}")
+```
+
+## Security notes
+
+- Secret values are **never** logged or printed by the SDK.
+- `SecretValue.__repr__` and `__str__` return `<redacted>` to prevent accidental exposure in logs or tracebacks.
+- The SDK does **not** accept vault passwords and does **not** spawn subprocesses.
+- The SDK does **not** place secrets in environment variables.
+- Each request uses a fresh pipe connection, closed immediately after the response is received.

mevault-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mevault"
+version = "0.1.0"
+description = "MeVault Python SDK — request secrets from the local MeVault broker"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.9"
+keywords = ["secrets", "security", "mevault", "credentials"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/thecalebyte/mevault-cli"
+Documentation = "https://github.com/thecalebyte/mevault-cli/blob/main/docs/sdk.md"
+"Bug Tracker" = "https://github.com/thecalebyte/mevault-cli/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mevault"]

mevault-0.1.0/src/mevault/__init__.py

@@ -0,0 +1,53 @@
+"""
+mevault — Python SDK for requesting secrets from the local MeVault broker.
+
+Quickstart
+----------
+
+Synchronous::
+
+    from mevault import get_secret, get_optional_secret
+    from mevault.exceptions import VaultLocked, SecretNotFound
+
+    db_password = get_secret("DB_PASSWORD")
+    api_key = get_optional_secret("OPTIONAL_API_KEY", default="")
+
+Asynchronous::
+
+    import asyncio
+    from mevault import async_get_secret
+
+    async def main():
+        token = await async_get_secret("AUTH_TOKEN")
+
+    asyncio.run(main())
+"""
+
+from .client import async_get_secret, get_optional_secret, get_secret
+from .exceptions import (
+    AccessDenied,
+    MeVaultError,
+    MeVaultUnavailable,
+    ProtocolError,
+    SecretNotFound,
+    SessionExpired,
+    VaultLocked,
+)
+from .types import SecretValue
+
+__all__ = [
+    # Functions
+    "get_secret",
+    "get_optional_secret",
+    "async_get_secret",
+    # Exceptions
+    "MeVaultError",
+    "MeVaultUnavailable",
+    "VaultLocked",
+    "SecretNotFound",
+    "AccessDenied",
+    "ProtocolError",
+    "SessionExpired",
+    # Types
+    "SecretValue",
+]

mevault-0.1.0/src/mevault/client.py

@@ -0,0 +1,343 @@
+"""
+MeVault client — synchronous and asyncio interfaces.
+
+Design constraints
+------------------
+- Named-pipe transport only (no subprocess, no env-var injection).
+- No vault password accepted or stored.
+- Secret values are NEVER logged; only error codes are logged.
+- Hard 10-second timeout on every operation.
+- Hard 1 MiB cap on response size.
+- One connection per request; connection closed immediately after response.
+"""
+
+import asyncio
+import json
+import logging
+import sys
+from typing import Optional
+
+from .exceptions import (
+    AccessDenied,
+    MeVaultUnavailable,
+    ProtocolError,
+    SecretNotFound,
+    SessionExpired,
+    VaultLocked,
+)
+from .protocol import (
+    KNOWN_ERROR_CODES,
+    MAX_RESPONSE_BYTES,
+    PIPE_NAME,
+    PROTOCOL_VERSION,
+    BrokerResponse,
+    GetSecretRequest,
+)
+from .types import SecretValue
+
+logger = logging.getLogger(__name__)
+
+# Default timeout for all I/O operations (seconds).
+_TIMEOUT: float = 10.0
+
+# Windows error code: pipe server is busy (all instances occupied).
+_ERROR_PIPE_BUSY: int = 231
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _map_error(error_code: Optional[str], message: Optional[str]) -> Exception:
+    """Convert a broker error code into the appropriate SDK exception."""
+    detail = message or error_code or "unknown error"
+    mapping = {
+        "vault_locked": VaultLocked,
+        "session_expired": SessionExpired,
+        "access_denied": AccessDenied,
+        "secret_not_found": SecretNotFound,
+    }
+    exc_class = mapping.get(error_code or "", MeVaultUnavailable)  # type: ignore[arg-type]
+    # Log only the error code, never the message (which might contain secret names).
+    logger.debug("broker returned error code: %s", error_code)
+    return exc_class(detail)
+
+
+def _parse_response(raw_bytes: bytes) -> BrokerResponse:
+    """
+    Parse a raw response line from the broker.
+
+    Raises ProtocolError on any malformed or oversized payload.
+    """
+    if len(raw_bytes) > MAX_RESPONSE_BYTES:
+        raise ProtocolError(
+            f"Response exceeded maximum allowed size of {MAX_RESPONSE_BYTES} bytes"
+        )
+
+    try:
+        data = json.loads(raw_bytes.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise ProtocolError(f"Malformed JSON response from broker: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise ProtocolError("Broker response was not a JSON object")
+
+    ok = data.get("ok")
+    if not isinstance(ok, bool):
+        raise ProtocolError("Broker response missing boolean 'ok' field")
+
+    # Validate protocol version if the broker echoes it.
+    version = data.get("version")
+    if version is not None and version != PROTOCOL_VERSION:
+        raise ProtocolError(
+            f"Protocol version mismatch: expected {PROTOCOL_VERSION}, got {version}"
+        )
+
+    return BrokerResponse(
+        ok=ok,
+        value=data.get("value"),
+        error=data.get("error"),
+        message=data.get("message"),
+        version=version,
+    )
+
+
+def _build_request(name: str) -> bytes:
+    """Serialise a GetSecretRequest to a newline-terminated JSON byte string."""
+    req = GetSecretRequest(name=name)
+    return (json.dumps(req.to_dict()) + "\n").encode("utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Platform guard — MeVault only runs on Windows
+# ---------------------------------------------------------------------------
+
+if sys.platform != "win32":
+    def get_secret(name: str) -> str:
+        """Raise MeVaultUnavailable: MeVault only runs on Windows."""
+        raise MeVaultUnavailable("MeVault is only supported on Windows")
+
+    def get_optional_secret(name: str, default: Optional[str] = None) -> Optional[str]:
+        """Return *default*: MeVault only runs on Windows."""
+        return default
+
+    async def async_get_secret(name: str) -> str:
+        """Raise MeVaultUnavailable: MeVault only runs on Windows."""
+        raise MeVaultUnavailable("MeVault is only supported on Windows")
+
+else:
+    # ------------------------------------------------------------------
+    # Windows-only transport
+    # ------------------------------------------------------------------
+
+    import ctypes
+    import ctypes.wintypes
+
+    def _wait_and_open(pipe_name: str, timeout_ms: int = 10000):  # type: ignore[return]
+        """
+        Open a Windows named pipe, waiting if all server instances are busy.
+
+        Uses WaitNamedPipeW from kernel32 so the caller blocks instead of
+        busy-looping when the broker is serving another connection.
+
+        Returns a raw binary file object (unbuffered) on success.
+        Raises MeVaultUnavailable if the pipe cannot be opened within *timeout_ms*.
+        """
+        deadline_ms = timeout_ms
+        while True:
+            try:
+                # Named pipes opened via open() in binary+unbuffered mode work
+                # correctly on Windows for byte-stream pipes.
+                return open(pipe_name, "r+b", buffering=0)  # noqa: WPS515
+            except OSError as exc:
+                winerr = getattr(exc, "winerror", None)
+                if winerr == _ERROR_PIPE_BUSY:
+                    # All pipe instances are in use; ask the kernel to wait.
+                    wait_ms = min(deadline_ms, 1000)
+                    ok = ctypes.windll.kernel32.WaitNamedPipeW(pipe_name, wait_ms)
+                    if not ok:
+                        raise MeVaultUnavailable(
+                            f"MeVault broker pipe busy after {timeout_ms} ms"
+                        ) from exc
+                    deadline_ms -= wait_ms
+                    if deadline_ms <= 0:
+                        raise MeVaultUnavailable(
+                            "MeVault broker pipe wait timed out"
+                        ) from exc
+                elif exc.errno == 2 or isinstance(exc, FileNotFoundError):
+                    raise MeVaultUnavailable(
+                        "MeVault broker is not running (pipe not found)"
+                    ) from exc
+                elif isinstance(exc, PermissionError):
+                    raise MeVaultUnavailable(
+                        "Permission denied when connecting to MeVault broker"
+                    ) from exc
+                else:
+                    raise MeVaultUnavailable(
+                        f"Cannot open MeVault pipe: {exc}"
+                    ) from exc
+
+    # ---------------------------------------------------------------------------
+    # Synchronous implementation (Windows named pipe via open())
+    # ---------------------------------------------------------------------------
+
+    def _sync_transact(name: str) -> str:
+        """
+        Open the named pipe, send a get_secret request, and return the secret value.
+
+        The pipe is opened with WaitNamedPipe semantics so the call blocks
+        correctly when the broker is momentarily busy serving another client.
+        The connection is closed once the response line is read regardless of outcome.
+        """
+        request_bytes = _build_request(name)
+
+        try:
+            pipe = _wait_and_open(PIPE_NAME, timeout_ms=int(_TIMEOUT * 1000))
+        except MeVaultUnavailable:
+            raise
+        except OSError as exc:
+            raise MeVaultUnavailable(
+                f"Could not connect to MeVault broker: {exc}"
+            ) from exc
+
+        try:
+            pipe.write(request_bytes)
+
+            # Read response line by line (capped at MAX_RESPONSE_BYTES + 1).
+            response_bytes = b""
+            while True:
+                chunk = pipe.read(4096)
+                if not chunk:
+                    break
+                response_bytes += chunk
+                if b"\n" in response_bytes:
+                    break
+                if len(response_bytes) > MAX_RESPONSE_BYTES:
+                    raise ProtocolError(
+                        f"Response exceeded maximum allowed size of {MAX_RESPONSE_BYTES} bytes"
+                    )
+        except ProtocolError:
+            raise
+        except OSError as exc:
+            raise MeVaultUnavailable(
+                f"I/O error while communicating with MeVault broker: {exc}"
+            ) from exc
+        finally:
+            try:
+                pipe.close()
+            except OSError:
+                pass
+
+        if not response_bytes:
+            raise ProtocolError("Broker closed the connection without sending a response")
+
+        # Parse only the first line.
+        line = response_bytes.split(b"\n")[0]
+        response = _parse_response(line)
+
+        if response.ok:
+            if response.value is None:
+                raise ProtocolError("Broker returned ok=true but no 'value' field")
+            # Value is intentionally NOT logged here.
+            return response.value
+
+        raise _map_error(response.error, response.message)
+
+    # ---------------------------------------------------------------------------
+    # Public synchronous API
+    # ---------------------------------------------------------------------------
+
+    def get_secret(name: str) -> str:
+        """
+        Retrieve a secret from the MeVault broker synchronously.
+
+        Parameters
+        ----------
+        name:
+            The name of the secret to retrieve.
+
+        Returns
+        -------
+        str
+            The secret value as a plain string.
+
+        Raises
+        ------
+        MeVaultUnavailable
+            The broker pipe could not be reached.
+        VaultLocked
+            The vault is locked.
+        SecretNotFound
+            No secret with that name exists.
+        AccessDenied
+            The calling process is not permitted to read this secret.
+        SessionExpired
+            The broker session has expired.
+        ProtocolError
+            The broker sent a malformed response.
+        """
+        return _sync_transact(name)
+
+    def get_optional_secret(name: str, default: Optional[str] = None) -> Optional[str]:
+        """
+        Retrieve a secret, returning *default* if the secret does not exist.
+
+        All other errors (VaultLocked, AccessDenied, etc.) are still raised.
+
+        Parameters
+        ----------
+        name:
+            The name of the secret to retrieve.
+        default:
+            Value to return when the secret is not found. Defaults to ``None``.
+
+        Returns
+        -------
+        str or None
+            The secret value, or *default* if not found.
+        """
+        try:
+            return get_secret(name)
+        except SecretNotFound:
+            return default
+
+    # ---------------------------------------------------------------------------
+    # Asynchronous implementation — wraps sync call in thread pool
+    # ---------------------------------------------------------------------------
+
+    async def async_get_secret(name: str) -> str:
+        """
+        Retrieve a secret from the MeVault broker asynchronously.
+
+        Runs the synchronous named-pipe call in a thread-pool executor so the
+        event loop is never blocked.  This is the correct approach for Windows
+        named pipes: ``asyncio.open_connection()`` cannot open a UNC pipe path.
+
+        Parameters
+        ----------
+        name:
+            The name of the secret to retrieve.
+
+        Returns
+        -------
+        str
+            The secret value as a plain string.
+
+        Raises
+        ------
+        MeVaultUnavailable
+            The broker pipe could not be reached.
+        VaultLocked
+            The vault is locked.
+        SecretNotFound
+            No secret with that name exists.
+        AccessDenied
+            The calling process is not permitted to read this secret.
+        SessionExpired
+            The broker session has expired.
+        ProtocolError
+            The broker sent a malformed response.
+        """
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, get_secret, name)

mevault-0.1.0/src/mevault/exceptions.py

@@ -0,0 +1,34 @@
+"""
+MeVault exception hierarchy.
+
+All exceptions raised by the MeVault SDK derive from MeVaultError so callers
+can catch the whole family with a single except clause if they prefer.
+"""
+
+
+class MeVaultError(Exception):
+    """Base class for all MeVault SDK errors."""
+
+
+class MeVaultUnavailable(MeVaultError):
+    """The MeVault broker pipe could not be reached (not running or not found)."""
+
+
+class VaultLocked(MeVaultError):
+    """The vault is locked; the user must unlock MeVault before secrets can be read."""
+
+
+class SecretNotFound(MeVaultError):
+    """The requested secret does not exist in the vault."""
+
+
+class AccessDenied(MeVaultError):
+    """The calling process is not authorised to read this secret."""
+
+
+class ProtocolError(MeVaultError):
+    """The broker returned an unexpected or malformed response."""
+
+
+class SessionExpired(MeVaultError):
+    """The broker session has expired; the user must re-authenticate."""

mevault-0.1.0/src/mevault/protocol.py

@@ -0,0 +1,81 @@
+"""
+Wire-protocol constants and data structures for the MeVault named-pipe IPC.
+
+Protocol summary
+----------------
+- One JSON line per message, terminated with ``\\n``.
+- One connection per request; the client closes the connection after reading
+  the response.
+- The broker may include an optional ``"version"`` field in the response;
+  if present it must match PROTOCOL_VERSION.
+
+Request (client → broker)::
+
+    {"op": "get_secret", "name": "<SECRET_NAME>"}
+
+Success response (broker → client)::
+
+    {"ok": true, "value": "<secret-value>"}
+
+Error response (broker → client)::
+
+    {"ok": false, "error": "<error-code>", "message": "<optional detail>"}
+
+Known error codes
+-----------------
+vault_locked, session_expired, access_denied, secret_not_found,
+identity_unknown, grant_invalid, internal_error, invalid_request
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+PIPE_NAME: str = r"\\.\pipe\mevault-runtime"
+PROTOCOL_VERSION: int = 1
+MAX_RESPONSE_BYTES: int = 1_048_576  # 1 MiB
+
+# All error codes the broker may return.
+KNOWN_ERROR_CODES: frozenset = frozenset(
+    {
+        "vault_locked",
+        "session_expired",
+        "access_denied",
+        "secret_not_found",
+        "identity_unknown",
+        "grant_invalid",
+        "internal_error",
+        "invalid_request",
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Request / response dataclasses
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class GetSecretRequest:
+    """Represents a ``get_secret`` request sent to the broker."""
+
+    name: str
+    op: str = field(default="get_secret", init=False)
+
+    def to_dict(self) -> dict:
+        return {"op": self.op, "name": self.name}
+
+
+@dataclass
+class BrokerResponse:
+    """Parsed broker response."""
+
+    ok: bool
+    value: Optional[str] = None      # present when ok is True
+    error: Optional[str] = None      # error code when ok is False
+    message: Optional[str] = None    # optional human-readable detail
+    version: Optional[int] = None    # optional protocol version echo

mevault-0.1.0/src/mevault/types.py

@@ -0,0 +1,32 @@
+"""
+Value types used by the MeVault SDK.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class SecretValue:
+    """
+    Wraps a secret string.
+
+    The repr and str are deliberately redacted so that logging framework
+    calls, exception tracebacks, and interactive sessions never accidentally
+    expose the underlying value.
+
+    Retrieve the raw string only when you genuinely need it:
+
+        value = secret.get()
+    """
+
+    _value: str
+
+    def get(self) -> str:
+        """Return the raw secret string."""
+        return self._value
+
+    def __repr__(self) -> str:
+        return "SecretValue(<redacted>)"
+
+    def __str__(self) -> str:
+        return "<redacted>"

mevault-0.1.0/tests/test_client.py

@@ -0,0 +1,358 @@
+"""
+Unit tests for the MeVault Python SDK.
+
+All tests mock the named-pipe connection so no live broker is required.
+"""
+
+import asyncio
+import json
+import unittest
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from mevault.client import (
+    _build_request,
+    _map_error,
+    _parse_response,
+    _sync_transact,
+    _wait_and_open,
+    async_get_secret,
+    get_optional_secret,
+    get_secret,
+)
+from mevault.exceptions import (
+    AccessDenied,
+    MeVaultUnavailable,
+    ProtocolError,
+    SecretNotFound,
+    SessionExpired,
+    VaultLocked,
+)
+from mevault.protocol import MAX_RESPONSE_BYTES
+from mevault.types import SecretValue
+
+
+# ---------------------------------------------------------------------------
+# Helper
+# ---------------------------------------------------------------------------
+
+
+def _json_line(payload: dict) -> bytes:
+    return (json.dumps(payload) + "\n").encode("utf-8")
+
+
+def _make_mock_pipe(response_payload: dict):
+    """
+    Return a mock file object that yields a single JSON response line.
+
+    The mock is wired to behave like an unbuffered binary pipe: the first
+    read() returns the full response line (including the trailing newline),
+    and subsequent reads return b'' to signal EOF.
+    """
+    raw = _json_line(response_payload)
+    m = MagicMock()
+    m.__enter__ = MagicMock(return_value=m)
+    m.__exit__ = MagicMock(return_value=False)
+    # First read returns data, second signals EOF so the read-loop terminates.
+    m.read.side_effect = [raw, b""]
+    m.write.return_value = None
+    m.close.return_value = None
+    return m
+
+
+# ---------------------------------------------------------------------------
+# SecretValue tests
+# ---------------------------------------------------------------------------
+
+
+class TestSecretValue(unittest.TestCase):
+    def test_get_returns_raw_value(self):
+        sv = SecretValue(_value="s3cr3t")
+        self.assertEqual(sv.get(), "s3cr3t")
+
+    def test_repr_is_redacted(self):
+        sv = SecretValue(_value="s3cr3t")
+        self.assertNotIn("s3cr3t", repr(sv))
+        self.assertEqual(repr(sv), "SecretValue(<redacted>)")
+
+    def test_str_is_redacted(self):
+        sv = SecretValue(_value="s3cr3t")
+        self.assertNotIn("s3cr3t", str(sv))
+        self.assertEqual(str(sv), "<redacted>")
+
+    def test_repr_never_contains_value_for_any_input(self):
+        # Empty string is always "in" any string by Python semantics, so skip it.
+        for value in ["password", "tok_abc123", "super-secret"]:
+            sv = SecretValue(_value=value)
+            self.assertNotIn(value, repr(sv), f"repr leaked value: {value!r}")
+
+    def test_str_never_contains_value_for_any_input(self):
+        for value in ["password", "tok_abc123", "super-secret"]:
+            sv = SecretValue(_value=value)
+            self.assertNotIn(value, str(sv), f"str leaked value: {value!r}")
+
+
+# ---------------------------------------------------------------------------
+# _parse_response tests
+# ---------------------------------------------------------------------------
+
+
+class TestParseResponse(unittest.TestCase):
+    def test_success_response(self):
+        raw = _json_line({"ok": True, "value": "the-secret"})
+        resp = _parse_response(raw)
+        self.assertTrue(resp.ok)
+        self.assertEqual(resp.value, "the-secret")
+
+    def test_error_response(self):
+        raw = _json_line({"ok": False, "error": "vault_locked", "message": "unlock first"})
+        resp = _parse_response(raw)
+        self.assertFalse(resp.ok)
+        self.assertEqual(resp.error, "vault_locked")
+        self.assertEqual(resp.message, "unlock first")
+
+    def test_malformed_json_raises_protocol_error(self):
+        with self.assertRaises(ProtocolError):
+            _parse_response(b"not-json\n")
+
+    def test_non_object_json_raises_protocol_error(self):
+        with self.assertRaises(ProtocolError):
+            _parse_response(b"[1, 2, 3]\n")
+
+    def test_missing_ok_field_raises_protocol_error(self):
+        raw = _json_line({"value": "something"})
+        with self.assertRaises(ProtocolError):
+            _parse_response(raw)
+
+    def test_oversized_response_raises_protocol_error(self):
+        oversized = b"x" * (MAX_RESPONSE_BYTES + 1)
+        with self.assertRaises(ProtocolError):
+            _parse_response(oversized)
+
+    def test_exactly_max_size_is_treated_as_malformed_json(self):
+        # Exactly MAX_RESPONSE_BYTES of garbage — not oversized, but not valid JSON.
+        payload = b"x" * MAX_RESPONSE_BYTES
+        with self.assertRaises(ProtocolError):
+            _parse_response(payload)
+
+    def test_protocol_version_mismatch_raises_protocol_error(self):
+        raw = _json_line({"ok": True, "value": "v", "version": 999})
+        with self.assertRaises(ProtocolError):
+            _parse_response(raw)
+
+    def test_matching_protocol_version_is_accepted(self):
+        from mevault.protocol import PROTOCOL_VERSION
+        raw = _json_line({"ok": True, "value": "v", "version": PROTOCOL_VERSION})
+        resp = _parse_response(raw)
+        self.assertTrue(resp.ok)
+
+
+# ---------------------------------------------------------------------------
+# _map_error tests
+# ---------------------------------------------------------------------------
+
+
+class TestMapError(unittest.TestCase):
+    def test_vault_locked(self):
+        exc = _map_error("vault_locked", None)
+        self.assertIsInstance(exc, VaultLocked)
+
+    def test_session_expired(self):
+        exc = _map_error("session_expired", None)
+        self.assertIsInstance(exc, SessionExpired)
+
+    def test_access_denied(self):
+        exc = _map_error("access_denied", None)
+        self.assertIsInstance(exc, AccessDenied)
+
+    def test_secret_not_found(self):
+        exc = _map_error("secret_not_found", None)
+        self.assertIsInstance(exc, SecretNotFound)
+
+    def test_unknown_error_code_maps_to_mevault_unavailable(self):
+        exc = _map_error("internal_error", "something went wrong")
+        self.assertIsInstance(exc, MeVaultUnavailable)
+
+
+# ---------------------------------------------------------------------------
+# get_secret (sync) tests — mocked at _wait_and_open level
+# ---------------------------------------------------------------------------
+
+
+class TestGetSecret(unittest.TestCase):
+    def _patch_pipe(self, mock_pipe):
+        """Patch _wait_and_open to return mock_pipe without going through open()."""
+        return patch("mevault.client._wait_and_open", return_value=mock_pipe)
+
+    def test_successful_retrieval(self):
+        mock_pipe = _make_mock_pipe({"ok": True, "value": "supersecret"})
+        with self._patch_pipe(mock_pipe):
+            result = get_secret("MY_SECRET")
+        self.assertEqual(result, "supersecret")
+
+    def test_vault_locked_raises(self):
+        mock_pipe = _make_mock_pipe({"ok": False, "error": "vault_locked"})
+        with self._patch_pipe(mock_pipe):
+            with self.assertRaises(VaultLocked):
+                get_secret("MY_SECRET")
+
+    def test_secret_not_found_raises(self):
+        mock_pipe = _make_mock_pipe({"ok": False, "error": "secret_not_found"})
+        with self._patch_pipe(mock_pipe):
+            with self.assertRaises(SecretNotFound):
+                get_secret("MISSING")
+
+    def test_access_denied_raises(self):
+        mock_pipe = _make_mock_pipe({"ok": False, "error": "access_denied"})
+        with self._patch_pipe(mock_pipe):
+            with self.assertRaises(AccessDenied):
+                get_secret("FORBIDDEN")
+
+    def test_session_expired_raises(self):
+        mock_pipe = _make_mock_pipe({"ok": False, "error": "session_expired"})
+        with self._patch_pipe(mock_pipe):
+            with self.assertRaises(SessionExpired):
+                get_secret("ANY")
+
+    def test_malformed_json_raises_protocol_error(self):
+        m = MagicMock()
+        m.__enter__ = MagicMock(return_value=m)
+        m.__exit__ = MagicMock(return_value=False)
+        m.read.side_effect = [b"this is not json\n", b""]
+        m.write.return_value = None
+        m.close.return_value = None
+        with patch("mevault.client._wait_and_open", return_value=m):
+            with self.assertRaises(ProtocolError):
+                get_secret("ANY")
+
+    def test_oversized_response_raises_protocol_error(self):
+        # Build a response larger than MAX_RESPONSE_BYTES with a newline at the end
+        # so the read loop terminates, then _parse_response rejects it.
+        oversized = b"x" * (MAX_RESPONSE_BYTES + 1) + b"\n"
+        m = MagicMock()
+        m.__enter__ = MagicMock(return_value=m)
+        m.__exit__ = MagicMock(return_value=False)
+        # Return chunks of 4096 until the loop detects overflow.
+        chunks = [oversized[i : i + 4096] for i in range(0, len(oversized), 4096)]
+        chunks.append(b"")
+        m.read.side_effect = chunks
+        m.write.return_value = None
+        m.close.return_value = None
+        with patch("mevault.client._wait_and_open", return_value=m):
+            with self.assertRaises(ProtocolError):
+                get_secret("ANY")
+
+    def test_pipe_not_found_raises_mevault_unavailable(self):
+        with patch(
+            "mevault.client._wait_and_open",
+            side_effect=MeVaultUnavailable("pipe missing"),
+        ):
+            with self.assertRaises(MeVaultUnavailable):
+                get_secret("ANY")
+
+    def test_empty_response_raises_protocol_error(self):
+        m = MagicMock()
+        m.__enter__ = MagicMock(return_value=m)
+        m.__exit__ = MagicMock(return_value=False)
+        m.read.return_value = b""
+        m.write.return_value = None
+        m.close.return_value = None
+        with patch("mevault.client._wait_and_open", return_value=m):
+            with self.assertRaises(ProtocolError):
+                get_secret("ANY")
+
+    def test_ok_true_without_value_raises_protocol_error(self):
+        mock_pipe = _make_mock_pipe({"ok": True})
+        with self._patch_pipe(mock_pipe):
+            with self.assertRaises(ProtocolError):
+                get_secret("ANY")
+
+
+# ---------------------------------------------------------------------------
+# get_optional_secret tests
+# ---------------------------------------------------------------------------
+
+
+class TestGetOptionalSecret(unittest.TestCase):
+    def test_returns_value_when_found(self):
+        mock_pipe = _make_mock_pipe({"ok": True, "value": "found"})
+        with patch("mevault.client._wait_and_open", return_value=mock_pipe):
+            result = get_optional_secret("KEY")
+        self.assertEqual(result, "found")
+
+    def test_returns_none_when_not_found(self):
+        mock_pipe = _make_mock_pipe({"ok": False, "error": "secret_not_found"})
+        with patch("mevault.client._wait_and_open", return_value=mock_pipe):
+            result = get_optional_secret("MISSING")
+        self.assertIsNone(result)
+
+    def test_returns_custom_default_when_not_found(self):
+        mock_pipe = _make_mock_pipe({"ok": False, "error": "secret_not_found"})
+        with patch("mevault.client._wait_and_open", return_value=mock_pipe):
+            result = get_optional_secret("MISSING", default="fallback")
+        self.assertEqual(result, "fallback")
+
+    def test_still_raises_vault_locked(self):
+        mock_pipe = _make_mock_pipe({"ok": False, "error": "vault_locked"})
+        with patch("mevault.client._wait_and_open", return_value=mock_pipe):
+            with self.assertRaises(VaultLocked):
+                get_optional_secret("ANY")
+
+    def test_still_raises_access_denied(self):
+        mock_pipe = _make_mock_pipe({"ok": False, "error": "access_denied"})
+        with patch("mevault.client._wait_and_open", return_value=mock_pipe):
+            with self.assertRaises(AccessDenied):
+                get_optional_secret("ANY")
+
+
+# ---------------------------------------------------------------------------
+# async_get_secret tests — mock get_secret (sync) since async uses run_in_executor
+# ---------------------------------------------------------------------------
+
+
+class TestAsyncGetSecret(unittest.IsolatedAsyncioTestCase):
+    async def test_successful_retrieval(self):
+        with patch("mevault.client.get_secret", return_value="async-secret"):
+            result = await async_get_secret("MY_SECRET")
+        self.assertEqual(result, "async-secret")
+
+    async def test_vault_locked_raises(self):
+        with patch("mevault.client.get_secret", side_effect=VaultLocked("locked")):
+            with self.assertRaises(VaultLocked):
+                await async_get_secret("ANY")
+
+    async def test_secret_not_found_raises(self):
+        with patch("mevault.client.get_secret", side_effect=SecretNotFound("MISSING")):
+            with self.assertRaises(SecretNotFound):
+                await async_get_secret("MISSING")
+
+    async def test_malformed_json_raises_protocol_error(self):
+        with patch("mevault.client.get_secret", side_effect=ProtocolError("bad json")):
+            with self.assertRaises(ProtocolError):
+                await async_get_secret("ANY")
+
+    async def test_pipe_not_found_raises_mevault_unavailable(self):
+        with patch(
+            "mevault.client.get_secret",
+            side_effect=MeVaultUnavailable("pipe missing"),
+        ):
+            with self.assertRaises(MeVaultUnavailable):
+                await async_get_secret("ANY")
+
+    async def test_oversized_response_raises_protocol_error(self):
+        with patch("mevault.client.get_secret", side_effect=ProtocolError("oversized")):
+            with self.assertRaises(ProtocolError):
+                await async_get_secret("ANY")
+
+    async def test_access_denied_raises(self):
+        with patch("mevault.client.get_secret", side_effect=AccessDenied("denied")):
+            with self.assertRaises(AccessDenied):
+                await async_get_secret("ANY")
+
+    async def test_session_expired_raises(self):
+        with patch("mevault.client.get_secret", side_effect=SessionExpired("expired")):
+            with self.assertRaises(SessionExpired):
+                await async_get_secret("ANY")
+
+
+if __name__ == "__main__":
+    unittest.main()