secrefs 0.2.0__py3-none-any.whl

secrefs/__init__.py

@@ -0,0 +1,110 @@
+import os
+from typing import Dict, List, Optional
+
+from .control_plane_client import (
+    ControlPlaneClient,
+    ControlPlaneCredentialSource,
+    ControlPlaneRequestError,
+    MintCredentialResponse,
+    MintedAWSCredentials,
+    MintedBitwardenCredentials,
+)
+from .parser import (
+    ParsedSecretRef,
+    SecRefParseError,
+    is_secret_ref,
+    parse_secret_ref,
+    try_parse_secret_ref,
+)
+from .providers.aws import AWSSecretsManagerProvider
+from .providers.base import ProviderHealth, SecretFetchError, SecretFetchRequest, SecretProvider
+from .providers.bitwarden import BitwardenProvider
+from .providers.local import LocalProvider
+from .providers.vault import VaultProvider
+from .resolver import (
+    CheckResult,
+    ProviderRegistry,
+    ResolutionFailure,
+    SecRefsResolutionError,
+    check_references,
+    expand_environ,
+    expand_key_value_map,
+)
+from .ttl_cache import TtlCache
+
+
+def create_default_providers() -> Dict[str, SecretProvider]:
+    """Builds the default provider registry: aws, vault, local, bitwarden."""
+    return {
+        "aws": AWSSecretsManagerProvider(),
+        "vault": VaultProvider(),
+        "local": LocalProvider(),
+        "bitwarden": BitwardenProvider(),
+    }
+
+
+class SecRefs:
+    """Mirrors the Node SDK's `secRefs.init()` / `expandEnv()` / `expandString()` API."""
+
+    def __init__(
+        self,
+        providers: Optional[Dict[str, SecretProvider]] = None,
+        strict: bool = True,
+    ) -> None:
+        self.providers: Dict[str, SecretProvider] = providers or create_default_providers()
+        self.strict = strict
+
+    async def init(self) -> List[str]:
+        """Expands sec:// values found in os.environ, mutating it in place."""
+        return await expand_environ(self.providers, strict=self.strict)
+
+    async def expand_env(self, env: Dict[str, Optional[str]]) -> Dict[str, str]:
+        """Expands sec:// values in an arbitrary key/value map without touching os.environ."""
+        return await expand_key_value_map(env, self.providers, strict=self.strict)
+
+    async def expand_string(self, value: str) -> str:
+        """Expands a single string if it's a sec:// reference; otherwise returns it unchanged."""
+        if not is_secret_ref(value):
+            return value
+        result = await expand_key_value_map({"__value__": value}, self.providers, strict=True)
+        return result["__value__"]
+
+    async def check(self, env: Optional[Dict[str, Optional[str]]] = None) -> List[CheckResult]:
+        """Dry-run validation of every sec:// reference in `env` (defaults to os.environ)."""
+        return await check_references(env if env is not None else dict(os.environ), self.providers)
+
+
+sec_refs = SecRefs()
+
+__all__ = [
+    "SecRefs",
+    "sec_refs",
+    "create_default_providers",
+    "ParsedSecretRef",
+    "SecRefParseError",
+    "is_secret_ref",
+    "parse_secret_ref",
+    "try_parse_secret_ref",
+    "AWSSecretsManagerProvider",
+    "VaultProvider",
+    "LocalProvider",
+    "BitwardenProvider",
+    "SecretProvider",
+    "SecretFetchRequest",
+    "SecretFetchError",
+    "ProviderHealth",
+    "TtlCache",
+    "ControlPlaneClient",
+    "ControlPlaneCredentialSource",
+    "ControlPlaneRequestError",
+    "MintCredentialResponse",
+    "MintedAWSCredentials",
+    "MintedBitwardenCredentials",
+    "SecRefsResolutionError",
+    "ResolutionFailure",
+    "CheckResult",
+    "ProviderRegistry",
+    "expand_environ",
+    "expand_key_value_map",
+    "check_references",
+]

secrefs/cli.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import signal
+import subprocess
+import sys
+from pathlib import Path
+from typing import List
+
+from . import SecRefs, SecRefsResolutionError
+from .envfile import parse_env_file_text
+
+
+def _load_dotenv(path: Path) -> None:
+    """Loads a `.env` file into `os.environ`, correctly preserving
+    `sec://...#field` fragments (see `envfile.py`). Mirrors dotenv.config()'s
+    default precedence: never overrides a value already present in
+    `os.environ` (e.g. set explicitly by the shell/CI)."""
+    if not path.exists():
+        return
+    parsed = parse_env_file_text(path.read_text(encoding="utf-8"))
+    for key, value in parsed.items():
+        os.environ.setdefault(key, value)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="secrefs-py",
+        description="BYOV secret reference engine - expand sec:// references in memory at runtime",
+    )
+    subparsers = parser.add_subparsers(dest="subcommand", required=True)
+
+    run_parser = subparsers.add_parser(
+        "run", help="Resolve sec:// references and spawn a child process"
+    )
+    run_parser.add_argument("--env-file", default=".env", help="path to a .env file to load first")
+    run_parser.add_argument(
+        "--no-env-file", action="store_true", help="skip loading a .env file"
+    )
+    run_parser.add_argument(
+        "command", nargs=argparse.REMAINDER, help="command to run, e.g. -- python app.py"
+    )
+
+    check_parser = subparsers.add_parser(
+        "check", help="Validate sec:// references and provider reachability"
+    )
+    check_parser.add_argument("--env-file", default=".env", help="path to a .env file to load first")
+    check_parser.add_argument(
+        "--no-env-file", action="store_true", help="skip loading a .env file"
+    )
+
+    return parser
+
+
+async def _run(args: argparse.Namespace) -> int:
+    command: List[str] = [c for c in args.command if c != "--"]
+    if not command:
+        print(
+            "secrefs-py run: no command given. Usage: secrefs-py run -- <command> [args...]",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not args.no_env_file:
+        _load_dotenv(Path(args.env_file))
+
+    instance = SecRefs()
+    try:
+        changed = await instance.init()
+        if changed:
+            print(
+                f"secrefs-py: resolved {len(changed)} secret reference(s): {', '.join(changed)}",
+                file=sys.stderr,
+            )
+    except SecRefsResolutionError as exc:
+        print("secrefs-py: failed to resolve one or more secret references:", file=sys.stderr)
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    process = subprocess.Popen(command, env=os.environ.copy())
+
+    forwarded_signals = [
+        s for s in (signal.SIGINT, signal.SIGTERM, getattr(signal, "SIGHUP", None)) if s is not None
+    ]
+
+    def _forward(sig: int, _frame: object) -> None:
+        if process.poll() is None:
+            process.send_signal(sig)
+
+    original_handlers = {sig: signal.getsignal(sig) for sig in forwarded_signals}
+    for sig in forwarded_signals:
+        signal.signal(sig, _forward)
+
+    try:
+        return process.wait()
+    finally:
+        for sig, handler in original_handlers.items():
+            signal.signal(sig, handler)
+
+
+async def _check(args: argparse.Namespace) -> int:
+    if not args.no_env_file:
+        _load_dotenv(Path(args.env_file))
+
+    instance = SecRefs()
+    results = await instance.check()
+
+    if not results:
+        print("secrefs-py check: no sec:// references found in the environment.")
+        return 0
+
+    ok_count = 0
+    for result in results:
+        icon = "✓" if result.ok else "✗"
+        print(f"{icon} {result.key} -> {result.ref}")
+        if result.ok:
+            ok_count += 1
+        else:
+            print(f"    {result.message}")
+
+    print(f"\n{ok_count}/{len(results)} reference(s) resolved successfully.")
+    return 0 if ok_count == len(results) else 1
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    if args.subcommand == "run":
+        exit_code = asyncio.run(_run(args))
+    else:
+        exit_code = asyncio.run(_check(args))
+
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

secrefs/control_plane_client.py

@@ -0,0 +1,206 @@
+"""
+Thin HTTP client for a running control plane's credential-broker endpoint
+(docs/control-plane-design.md §7). This is the piece §10 flagged as the
+missing link: every provider that supports control-plane-sourced credentials
+(AWSSecretsManagerProvider, BitwardenProvider - see their `control_plane`
+constructor option) constructs one of these instead of only ever reading
+ambient env vars.
+
+Deliberately just an HTTP wrapper with no retry/backoff/circuit-breaking
+logic - a mint failure surfaces as a normal raised exception, same as any
+other provider fetch failure, and the caller's existing error handling
+(resolver.py's asyncio.gather aggregation) already does the right thing
+with it.
+
+The default transport is `urllib` from the standard library, offloaded to a
+thread with `asyncio.to_thread` exactly the way boto3 and hvac calls are.
+One POST to one endpoint doesn't justify making every SecRefs install carry
+an HTTP client dependency it otherwise has no use for; a caller who wants
+their own (httpx, aiohttp, a test double) passes `transport`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Dict, Optional, Tuple, Union
+
+MINT_ENDPOINT = "/v1/credentials/mint"
+
+
+@dataclass(frozen=True)
+class MintedAWSCredentials:
+    access_key_id: str
+    secret_access_key: str
+    session_token: str
+    expiration: str  # ISO-8601 timestamp
+
+
+@dataclass(frozen=True)
+class MintedBitwardenCredentials:
+    access_token: str
+    # Explicitly not a TTL promise - see
+    # apps/control-plane/src/providers/bitwarden.ts.
+    note: str = ""
+    organization_id: Optional[str] = None
+
+
+MintedCredentials = Union[MintedAWSCredentials, MintedBitwardenCredentials]
+
+
+@dataclass(frozen=True)
+class MintCredentialResponse:
+    provider: str
+    # None when the control plane names a provider this SDK doesn't know how
+    # to parse credentials for. Left to the calling provider to reject, so
+    # the error it raises is the same "returned a X credential, expected Y"
+    # one it raises for a known-but-wrong provider rather than a second,
+    # differently-worded failure mode.
+    credentials: Optional[MintedCredentials] = None
+
+
+@dataclass(frozen=True)
+class ControlPlaneCredentialSource:
+    """What a provider's `control_plane` constructor option needs - shared
+    shape between AWSSecretsManagerProvider and BitwardenProvider (and any
+    future control-plane-aware provider)."""
+
+    base_url: str
+    """Base URL of a running control plane, e.g. from $SECREFS_CONTROL_PLANE_URL."""
+    token: str
+    """Bootstrap token or a verified OIDC token, e.g. from $SECREFS_CONTROL_PLANE_TOKEN."""
+    alias: str
+    """Which VaultConnection alias this provider instance represents - this
+    is what the control plane's RBAC grants are scoped against, not the
+    `sec://` alias this provider happens to be registered under (though in
+    practice they're usually the same string)."""
+    client: Optional["ControlPlaneClient"] = None
+    """Injected for testing - defaults to a real ControlPlaneClient."""
+
+
+# (url, headers, body) -> (status, body). A non-2xx status is a *response*,
+# not an exception: the body carries the control plane's denial reason and
+# the caller needs it verbatim.
+ControlPlaneTransport = Callable[[str, Dict[str, str], bytes], Awaitable[Tuple[int, bytes]]]
+
+
+async def _urllib_transport(url: str, headers: Dict[str, str], body: bytes) -> Tuple[int, bytes]:
+    def send() -> Tuple[int, bytes]:
+        request = urllib.request.Request(url, data=body, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(request) as response:  # noqa: S310 - caller-supplied https URL
+                return int(response.status), bytes(response.read())
+        except urllib.error.HTTPError as exc:
+            # urllib raises on 4xx/5xx; a denial is a well-formed answer
+            # here, so hand the status and body back rather than the error.
+            return int(exc.code), bytes(exc.read())
+
+    return await asyncio.to_thread(send)
+
+
+class ControlPlaneRequestError(Exception):
+    """Raised for a well-formed error response from the control plane (401,
+    403, 502, ...) - `status` and the message come straight from its
+    `{"error": ...}` body, so a denial reason (e.g. 'no grant authorizes
+    path...') reaches the caller verbatim rather than as an opaque HTTP
+    failure."""
+
+    def __init__(self, status: int, message: str) -> None:
+        self.status = status
+        super().__init__(message)
+
+
+class ControlPlaneClient:
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        transport: Optional[ControlPlaneTransport] = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._transport: ControlPlaneTransport = transport or _urllib_transport
+
+    async def mint_credential(self, alias: str, path: str) -> MintCredentialResponse:
+        """Authenticates, authorizes, and resolves a credential for
+        `alias`/`path` - see the control plane's POST /v1/credentials/mint.
+        Raises ControlPlaneRequestError for any non-2xx response."""
+        url = f"{self._base_url}{MINT_ENDPOINT}"
+        headers = {
+            "content-type": "application/json",
+            "authorization": f"Bearer {self._token}",
+        }
+        body = json.dumps({"alias": alias, "path": path}).encode("utf-8")
+
+        try:
+            status, raw = await self._transport(url, headers, body)
+        except Exception as exc:  # noqa: BLE001 - re-raised with the URL for context
+            raise ValueError(f"could not reach control plane at {self._base_url}: {exc}") from exc
+
+        if not 200 <= status < 300:
+            raise ControlPlaneRequestError(
+                status,
+                _error_message(raw)
+                or f'control plane returned {status} for alias "{alias}" path "{path}"',
+            )
+
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(
+                f"control plane returned a non-JSON success response for alias "
+                f'"{alias}" path "{path}": {exc}'
+            ) from exc
+
+        return _parse_mint_response(payload)
+
+
+def _error_message(raw: bytes) -> Optional[str]:
+    """The `{"error": ...}` body an error response is supposed to carry.
+    None if it isn't there - a proxy or load balancer in front of the
+    control plane may return HTML or nothing at all."""
+    try:
+        payload = json.loads(raw)
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return None
+    if isinstance(payload, dict) and isinstance(payload.get("error"), str):
+        return str(payload["error"])
+    return None
+
+
+def _parse_mint_response(payload: Any) -> MintCredentialResponse:
+    if not isinstance(payload, dict):
+        raise ValueError("control plane returned a malformed mint response")
+
+    provider = str(payload.get("provider", ""))
+    raw = payload.get("credentials")
+    fields: Dict[str, Any] = raw if isinstance(raw, dict) else {}
+
+    # Wire format is camelCase - it's produced by the control plane's
+    # TypeScript (apps/control-plane/src/routes/credentials.ts).
+    if provider == "aws":
+        return MintCredentialResponse(
+            provider=provider,
+            credentials=MintedAWSCredentials(
+                access_key_id=str(fields.get("accessKeyId", "")),
+                secret_access_key=str(fields.get("secretAccessKey", "")),
+                session_token=str(fields.get("sessionToken", "")),
+                expiration=str(fields.get("expiration", "")),
+            ),
+        )
+
+    if provider == "bitwarden":
+        organization_id = fields.get("organizationId")
+        return MintCredentialResponse(
+            provider=provider,
+            credentials=MintedBitwardenCredentials(
+                access_token=str(fields.get("accessToken", "")),
+                note=str(fields.get("note", "")),
+                organization_id=str(organization_id) if organization_id else None,
+            ),
+        )
+
+    return MintCredentialResponse(provider=provider)

secrefs/envfile.py

@@ -0,0 +1,79 @@
+"""`.env` file parsing, kept at parity with the Node SDK's `envFile.ts`.
+
+A naive line-based `.env` parser treats `#` as a start-of-comment marker
+mid-value, which silently truncates the `#field` fragment off an unquoted
+`sec://provider/path#field` reference - the exact format SecRefs itself
+uses. This module strips inline comments the way `.env` conventionally
+works (including on quoted values), then restores the untruncated value
+for any unquoted `sec://` assignment, since there `#` is URI syntax, not a
+comment marker.
+
+Note: because of this, an unquoted `sec://` value can't have a trailing
+inline comment on the same line - put comments on their own line instead.
+Quoted values (`KEY="sec://...#field"`) are unaffected either way.
+"""
+from __future__ import annotations
+
+import re
+from typing import Dict
+
+# Matches an *unquoted* `KEY=sec://...` assignment, capturing the rest of
+# the line verbatim as the value.
+_UNQUOTED_SEC_REF_LINE = re.compile(
+    r"^[ \t]*(?:export[ \t]+)?([A-Za-z_][A-Za-z0-9_]*)[ \t]*=[ \t]*(sec://\S.*)$"
+)
+
+
+def _strip_inline_comment(value: str) -> str:
+    """Truncates an *unquoted* value at its first `#`, mirroring conventional
+    `.env` comment handling (e.g. `dotenv`'s own default behavior)."""
+    idx = value.find("#")
+    if idx == -1:
+        return value.rstrip()
+    return value[:idx].rstrip()
+
+
+def recover_truncated_sec_refs(raw_text: str, parsed: Dict[str, str]) -> Dict[str, str]:
+    """Restores the full, untruncated value for any line that assigns an
+    unquoted `sec://...` reference, undoing `_strip_inline_comment`'s
+    truncation for exactly the cases where `#` is part of the URI rather
+    than a comment marker."""
+    result = dict(parsed)
+    for line in re.split(r"\r?\n", raw_text):
+        match = _UNQUOTED_SEC_REF_LINE.match(line)
+        if not match:
+            continue
+        key, value = match.group(1), match.group(2)
+        result[key] = value.rstrip()
+    return result
+
+
+def parse_env_file_text(raw_text: str) -> Dict[str, str]:
+    """Parses a `.env` file's contents, correctly preserving
+    `sec://...#field` fragments."""
+    parsed: Dict[str, str] = {}
+
+    for raw_line in raw_text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        if not key:
+            continue
+
+        if value and value[0] in ("'", '"'):
+            # A quoted value ends at its matching closing quote - anything
+            # after that (typically a trailing comment) is discarded,
+            # whether or not the quotes span the whole rest of the line.
+            quote = value[0]
+            end = value.find(quote, 1)
+            value = value[1:end] if end != -1 else value[1:]
+        else:
+            value = _strip_inline_comment(value)
+
+        parsed[key] = value
+
+    return recover_truncated_sec_refs(raw_text, parsed)

secrefs/parser.py

@@ -0,0 +1,70 @@
+"""
+URI parser for SecRefs' `sec://` reference format:
+
+    sec://<provider-alias>/<secret-path-or-id>[#<json-field>]
+
+    sec://aws/prod/db#password
+    sec://vault/secret/data/stripe#key
+    sec://local/mock-db#password
+
+Mirrors packages/node/src/parser.ts exactly (same regex, same semantics),
+so a `sec://` string means the same thing regardless of which SDK reads it.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+_SEC_REF_PATTERN = re.compile(r"^sec://([a-zA-Z0-9][a-zA-Z0-9_-]*)/([^\s#]+)(?:#([^\s#]+))?$")
+
+
+class SecRefParseError(ValueError):
+    def __init__(self, raw: str, reason: str) -> None:
+        self.raw = raw
+        self.reason = reason
+        super().__init__(f'Invalid secret reference "{raw}": {reason}')
+
+
+@dataclass(frozen=True)
+class ParsedSecretRef:
+    raw: str
+    provider: str
+    path: str
+    field: Optional[str] = None
+
+
+def is_secret_ref(value: object) -> bool:
+    """True if `value` is a string that looks like a `sec://` reference at all."""
+    return isinstance(value, str) and value.startswith("sec://")
+
+
+def parse_secret_ref(raw: object) -> ParsedSecretRef:
+    """Parses a `sec://` reference string, raising SecRefParseError on any malformed input."""
+    if not isinstance(raw, str):
+        raise SecRefParseError(str(raw), "reference must be a string")
+
+    trimmed = raw.strip()
+    if not trimmed.startswith("sec://"):
+        raise SecRefParseError(raw, 'must start with "sec://"')
+
+    match = _SEC_REF_PATTERN.match(trimmed)
+    if not match:
+        raise SecRefParseError(raw, "does not match sec://<provider>/<path>[#field] format")
+
+    provider, path, field = match.groups()
+    if not provider:
+        raise SecRefParseError(raw, "missing provider alias")
+    if not path:
+        raise SecRefParseError(raw, "missing secret path")
+
+    return ParsedSecretRef(raw=raw, provider=provider.lower(), path=path, field=field or None)
+
+
+def try_parse_secret_ref(raw: object) -> Optional[ParsedSecretRef]:
+    """Best-effort parse that returns None instead of raising."""
+    try:
+        return parse_secret_ref(raw)
+    except SecRefParseError:
+        return None

secrefs/providers/__init__.py

@@ -0,0 +1,16 @@
+from .aws import AWSSecretsManagerProvider
+from .base import ProviderHealth, SecretFetchError, SecretFetchRequest, SecretProvider
+from .bitwarden import BitwardenProvider
+from .local import LocalProvider
+from .vault import VaultProvider
+
+__all__ = [
+    "AWSSecretsManagerProvider",
+    "BitwardenProvider",
+    "LocalProvider",
+    "VaultProvider",
+    "ProviderHealth",
+    "SecretFetchError",
+    "SecretFetchRequest",
+    "SecretProvider",
+]