secrefs 0.2.0__py3-none-any.whl

secrefs/resolver.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from dataclasses import dataclass
+from typing import Dict, List, Mapping, Optional, Tuple
+
+from .parser import ParsedSecretRef, is_secret_ref, parse_secret_ref
+from .providers.base import SecretFetchRequest, SecretProvider
+
+ProviderRegistry = Mapping[str, SecretProvider]
+
+
+@dataclass(frozen=True)
+class ResolutionFailure:
+    key: str
+    ref: str
+    message: str
+
+
+class SecRefsResolutionError(Exception):
+    def __init__(self, errors: List[ResolutionFailure]) -> None:
+        self.errors = errors
+        lines = "\n".join(f"  - {e.key}: {e.ref} -> {e.message}" for e in errors)
+        super().__init__(f"Failed to resolve {len(errors)} secret reference(s):\n{lines}")
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    key: str
+    ref: str
+    provider: str
+    ok: bool
+    message: Optional[str] = None  # present only when ok is False; never a secret value
+
+
+async def _resolve_one(ref: ParsedSecretRef, providers: ProviderRegistry) -> str:
+    provider = providers.get(ref.provider)
+    if provider is None:
+        available = ", ".join(providers.keys()) or "none configured"
+        raise ValueError(f'unknown provider "{ref.provider}" (available: {available})')
+    return await provider.fetch_one(SecretFetchRequest(path=ref.path, field=ref.field))
+
+
+async def expand_key_value_map(
+    input_map: Mapping[str, Optional[str]],
+    providers: ProviderRegistry,
+    *,
+    strict: bool = True,
+) -> Dict[str, str]:
+    """
+    Expands every `sec://` value in a plain key/value map, resolving all
+    references concurrently. Non-reference values pass through untouched.
+    Raises SecRefsResolutionError aggregating every failed reference.
+    """
+    output: Dict[str, str] = {}
+    pending: List[Tuple[str, ParsedSecretRef]] = []
+
+    for key, value in input_map.items():
+        if value is None:
+            continue
+        if not is_secret_ref(value):
+            output[key] = value
+            continue
+        try:
+            pending.append((key, parse_secret_ref(value)))
+        except ValueError:
+            if strict:
+                raise
+            output[key] = value
+
+    if not pending:
+        return output
+
+    results = await asyncio.gather(
+        *(_resolve_one(ref, providers) for _, ref in pending), return_exceptions=True
+    )
+
+    errors: List[ResolutionFailure] = []
+    for (key, ref), result in zip(pending, results):
+        if isinstance(result, BaseException):
+            errors.append(ResolutionFailure(key=key, ref=ref.raw, message=str(result)))
+        else:
+            output[key] = result
+
+    if errors:
+        raise SecRefsResolutionError(errors)
+
+    return output
+
+
+async def expand_environ(providers: ProviderRegistry, *, strict: bool = True) -> List[str]:
+    """Expands sec:// values found in os.environ, mutating it in place."""
+    resolved = await expand_key_value_map(dict(os.environ), providers, strict=strict)
+    changed_keys: List[str] = []
+    for key, value in resolved.items():
+        if os.environ.get(key) != value:
+            os.environ[key] = value
+            changed_keys.append(key)
+    return changed_keys
+
+
+async def check_references(
+    input_map: Mapping[str, Optional[str]], providers: ProviderRegistry
+) -> List[CheckResult]:
+    """
+    Dry-run validation: resolves every sec:// reference in `input_map` but
+    reports only ok/failure - secret values are never returned or logged.
+    """
+    results: List[CheckResult] = []
+    parsed_entries: List[Tuple[str, ParsedSecretRef]] = []
+
+    for key, value in input_map.items():
+        if not isinstance(value, str) or not is_secret_ref(value):
+            continue
+        try:
+            parsed_entries.append((key, parse_secret_ref(value)))
+        except ValueError as exc:
+            results.append(
+                CheckResult(key=key, ref=value, provider="unknown", ok=False, message=str(exc))
+            )
+
+    outcomes = await asyncio.gather(
+        *(_resolve_one(ref, providers) for _, ref in parsed_entries), return_exceptions=True
+    )
+
+    for (key, ref), outcome in zip(parsed_entries, outcomes):
+        results.append(
+            CheckResult(
+                key=key,
+                ref=ref.raw,
+                provider=ref.provider,
+                ok=not isinstance(outcome, BaseException),
+                message=str(outcome) if isinstance(outcome, BaseException) else None,
+            )
+        )
+
+    return results

secrefs/ttl_cache.py

@@ -0,0 +1,109 @@
+"""
+A cache that expires, used by every provider that fetches over the network.
+
+The default TTL is **zero** - every read re-fetches. That's deliberate and
+it's the whole point of the product: a `sec://` reference is a stable name
+for a value that changes underneath it. A consumer holding the reference is
+supposed to see a rotated secret without being redeployed, and a cache with
+no expiry silently breaks exactly that. Before this existed, a long-running
+process fetched a secret once and held the pre-rotation value until restart.
+
+A non-zero TTL is a real tradeoff, not a mistake: every expansion is a
+network round trip, so a busy caller may want to trade a bounded window of
+staleness for latency and API-rate-limit headroom. `ttl_ms=30_000` means "a
+rotation reaches me within 30 seconds" - usually fine, and it should be a
+decision someone made rather than a default they inherited.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Dict, Generic, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+def _monotonic_ms() -> float:
+    """Monotonic rather than wall clock: a TTL is a duration, and an NTP
+    step or a DST change shouldn't stretch or collapse one."""
+    return time.monotonic() * 1000
+
+
+@dataclass
+class _Entry(Generic[T]):
+    value: T
+    stored_at: float
+
+
+class TtlCache(Generic[T]):
+    def __init__(
+        self,
+        ttl_ms: float = 0.0,
+        now: Optional[Callable[[], float]] = None,
+    ) -> None:
+        """`ttl_ms` is how long an entry stays fresh; 0 (the default)
+        disables caching entirely - every `fetch` call goes to the source.
+        `now` is injected in tests so expiry doesn't require real waiting."""
+        self._ttl_ms = ttl_ms
+        self._now = now or _monotonic_ms
+        # Settled values, only ever populated when a TTL is configured.
+        self._entries: Dict[str, _Entry[T]] = {}
+        # Requests currently in flight, tracked separately from `_entries`
+        # because coalescing and caching are different things: sharing an
+        # unsettled request holds no value past the moment it resolves, so
+        # it stays correct even with caching fully disabled.
+        self._in_flight: Dict[str, "asyncio.Future[T]"] = {}
+
+    async def fetch(self, key: str, load: Callable[[], Awaitable[T]]) -> T:
+        """
+        Returns the cached value for `key` if it's still fresh, otherwise
+        awaits `load()` and caches that. In-flight requests are shared, so N
+        concurrent expansions of the same reference make one request rather
+        than N even when the TTL is zero - that's request coalescing, not
+        caching, and it doesn't hold a value past its use.
+
+        A failed load is dropped rather than remembered, so a transient
+        failure doesn't become a sticky one.
+        """
+        # Always join an in-flight request, whatever the TTL.
+        pending = self._in_flight.get(key)
+        if pending is None:
+            entry = self._entries.get(key)
+            if (
+                entry is not None
+                and self._ttl_ms > 0
+                and self._now() - entry.stored_at < self._ttl_ms
+            ):
+                return entry.value
+
+            pending = asyncio.ensure_future(load())
+            self._in_flight[key] = pending
+            # Cleared by the request itself rather than in a `finally` below,
+            # so the entry disappears exactly when the request settles even
+            # if the caller that started it was cancelled first.
+            pending.add_done_callback(lambda _task: self._in_flight.pop(key, None))
+
+        try:
+            # Shielded: one caller giving up (a cancelled `expand_string`,
+            # say) must not cancel the request every other caller joined.
+            value = await asyncio.shield(pending)
+        except Exception:
+            # Never remember a failure - a transient outage shouldn't become
+            # a sticky one for the length of the TTL.
+            self._entries.pop(key, None)
+            raise
+
+        if self._ttl_ms > 0:
+            # The settled value, not the future it came from: a retained
+            # entry can outlive the event loop that produced it, and an
+            # awaitable can't be awaited from a different one.
+            self._entries[key] = _Entry(value=value, stored_at=self._now())
+        return value
+
+    def clear(self) -> None:
+        """Drops everything retained - used when a credential changes
+        underneath the cache and anything fetched with the old one is
+        suspect."""
+        self._entries.clear()

secrefs-0.2.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: secrefs
+Version: 0.2.0
+Summary: BYOV secret reference engine - expand sec:// references in memory at runtime
+License: MIT
+License-File: LICENSE
+Author: SecRefs
+Author-email: hello@secrefs.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: bitwarden
+Requires-Dist: bitwarden-sdk (>=2.1,<3.0) ; extra == "bitwarden"
+Requires-Dist: boto3 (>=1.34,<2.0)
+Requires-Dist: hvac (>=2.1,<3.0)
+Project-URL: Homepage, https://secrefs.com
+Project-URL: Repository, https://github.com/secrefs/secrefs
+Description-Content-Type: text/markdown
+
+# secrefs (Python)
+
+Python SDK/CLI parity with `@secrefs/node`. See the repo root README for the
+full `sec://` reference spec and provider list.
+
+## Install
+
+```bash
+pip install secrefs
+# Bitwarden Secrets Manager support is an extra - see "Providers" below:
+pip install 'secrefs[bitwarden]'
+# or, in this monorepo:
+poetry install
+```
+
+## Library usage
+
+```python
+import asyncio
+import os
+from secrefs import sec_refs
+
+async def main():
+    await sec_refs.init()  # expands sec:// values in os.environ, in place
+    print(os.environ["DB_PASSWORD"])
+
+asyncio.run(main())
+```
+
+## Two ways to expand, and when each is wrong
+
+A `sec://` reference is a **stable name for a value that changes**. Which of
+these you use decides whether that actually holds:
+
+**At use (recommended).** Expand where the secret is consumed. Every call
+re-fetches, so rotating the value at the source reaches this consumer with
+no redeploy:
+
+```python
+async def call_vendor_api():
+    key = await sec_refs.expand_string("sec://aws/hackerone#api_key")
+    ...
+```
+
+**At load (`secrefs-py run`).** Expands once at startup and bakes plain
+strings into the child's environment. Convenient, and the right choice for
+short-lived processes like a CI job — but an environment variable is a
+static string, so **a long-running process keeps the pre-rotation value
+until it restarts**.
+
+Network-backed providers re-fetch on every expansion by default. Concurrent
+expansions of the same reference still share one request, and `cache_ttl_ms`
+trades a bounded window of staleness for fewer round trips if you need it:
+
+```python
+AWSSecretsManagerProvider(cache_ttl_ms=30_000)  # rotation lands within 30s
+```
+
+`LocalProvider` re-reads its JSON file per fetch for the same reason, so
+editing `.secrefs.local.json` mid-session takes effect; `cache_file=True`
+restores the old behavior.
+
+## Providers
+
+| Alias | Backend | Ambient auth |
+|---|---|---|
+| `aws` | AWS Secrets Manager | boto3's default credential chain |
+| `vault` | HashiCorp Vault (KV v1/v2) | `VAULT_ADDR` / `VAULT_TOKEN` |
+| `bitwarden` | Bitwarden Secrets Manager | `BWS_ACCESS_TOKEN` / `BWS_ORGANIZATION_ID` |
+| `local` | gitignored JSON file | n/a - development only |
+
+`bitwarden` needs the `secrefs[bitwarden]` extra: Bitwarden secrets are
+end-to-end encrypted, so only Bitwarden's own SDK can decrypt them, and it
+ships as prebuilt native wheels for a fixed set of platforms. It's an extra
+rather than a hard dependency so a platform it doesn't build for can still
+install SecRefs.
+
+## Control-plane-sourced credentials
+
+`AWSSecretsManagerProvider` and `BitwardenProvider` can source credentials
+per request from a running control plane instead of the ambient environment
+(see `docs/control-plane-design.md`), so each fetch is authenticated,
+RBAC-checked and audited on the control plane's side:
+
+```python
+from secrefs import AWSSecretsManagerProvider, ControlPlaneCredentialSource
+
+AWSSecretsManagerProvider(
+    control_plane=ControlPlaneCredentialSource(
+        base_url=os.environ["SECREFS_CONTROL_PLANE_URL"],
+        token=os.environ["SECREFS_CONTROL_PLANE_TOKEN"],
+        alias="aws-prod",
+    )
+)
+```
+
+## CLI usage
+
+```bash
+secrefs-py run -- python app.py
+secrefs-py check
+```
+

secrefs-0.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+secrefs/__init__.py,sha256=PRo1iW0AUziMChVjaLvrLmTxaXTVdGhn_XcmoxWJQag,3458
+secrefs/cli.py,sha256=1mVzX900pUUnuteDO5xmqnCSIbGBXq5gTIIMepcQXdg,4286
+secrefs/control_plane_client.py,sha256=LShXrxOIjx7Hf_yXh_jyKtpKFC42pvcqdeJRSsOFXaM,8209
+secrefs/envfile.py,sha256=2JeZfxOkS1wkbZHumzTQVNprp3N43RgdIyBoRTlaPMI,2992
+secrefs/parser.py,sha256=5U7hrjXDdn9_zKmgD3BHlsFdEZgyBHzvDsmq4fK__VU,2190
+secrefs/providers/__init__.py,sha256=CckreWD7Uge_g34-X19PkCB4CwE_hNsMLDM2MTpbou8,446
+secrefs/providers/aws.py,sha256=Rv2BA959YCIKxWCpBxxJAbVBdm-s3nLoOqXQwUYjPm8,7444
+secrefs/providers/base.py,sha256=3bxDXQO-CXLnOAw3kaRA6mRdtEMQBQkEcX9c5mJSIIA,2784
+secrefs/providers/bitwarden.py,sha256=6v4nHedtgtxhHKpbb8A4hvBGoVqoU5RjdBQk5zYjEJk,12531
+secrefs/providers/local.py,sha256=CL-Iih0PmK4zQvoj6halK-jXi28BPmwtddCT8ijT9Yg,3022
+secrefs/providers/vault.py,sha256=fzie33D_wQQhRCqbwFJ0fWF7BuEvxC6Z1SPCVMmWjB4,4051
+secrefs/resolver.py,sha256=_hURsbWCcnxVBZz-PNrBYnpXyxrFwkxeR6_z9uMBPn4,4453
+secrefs/ttl_cache.py,sha256=o1_JLkUr7Ayc4f-14JM7Fe2ZUgm8hcChUttauvoPcbc,4621
+secrefs-0.2.0.dist-info/METADATA,sha256=n1NjRbij0YuDA-L1AGGgrNTFMlf6mS51JbYYwHwZFQU,4125
+secrefs-0.2.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+secrefs-0.2.0.dist-info/entry_points.txt,sha256=lkHYgN1oW8WFP7O1cLaszl3QUI-UhZzHN8fPN-hAbXg,47
+secrefs-0.2.0.dist-info/licenses/LICENSE,sha256=YxxxY7FGq0yNW4kXF-EjJCam-lq1XndIn8GS17fDQrk,1072
+secrefs-0.2.0.dist-info/RECORD,,

secrefs-0.2.0.dist-info/WHEEL

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

secrefs-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+secrefs-py=secrefs.cli:main
+

secrefs-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Armistice Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.