mevault 0.1.0__py3-none-any.whl

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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+mevault/__init__.py,sha256=r7Ntpq9p5pb_He7-UHZ7-A18dVOtYIfYyC9TTpxW0K8,1149
+mevault/client.py,sha256=yiTwBD_v_3EsaExk5XbRkkYyzSdowAjAO4cwjR1Uhvg,12043
+mevault/exceptions.py,sha256=2GslvhceJVU-Ho7s-jJT891fMEJBvEMzX_MMy-_-O7Y,968
+mevault/protocol.py,sha256=ZriFt6bFj0lTaoK8rEm20S8cgOTvX4vjnwYvH-opYMA,2376
+mevault/types.py,sha256=az7yvWqxg-h6aOgxL2hzg8z7nqJePfj5WPyUSSVHiYE,710
+mevault-0.1.0.dist-info/METADATA,sha256=TcUXRkPB_wc70TpfnWWTXf7NWcpS3yKZ3BMEWnTgyek,3166
+mevault-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+mevault-0.1.0.dist-info/RECORD,,

mevault-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any