secrefs 0.2.0__tar.gz

secrefs-0.2.0/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.

secrefs-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,102 @@
+# 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/pyproject.toml

@@ -0,0 +1,56 @@
+[tool.poetry]
+name = "secrefs"
+version = "0.2.0"
+description = "BYOV secret reference engine - expand sec:// references in memory at runtime"
+authors = ["SecRefs <hello@secrefs.com>"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://secrefs.com"
+repository = "https://github.com/secrefs/secrefs"
+packages = [{ include = "secrefs" }]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+boto3 = "^1.34"
+hvac = "^2.1"
+# Optional, unlike boto3/hvac: bitwarden-sdk publishes only prebuilt native
+# wheels for a fixed set of platform tags with no source distribution, so a
+# hard dependency would break installing secrefs at all on any platform
+# Bitwarden doesn't build for - including for the many users who never write
+# a sec://bitwarden/... reference. providers/bitwarden.py imports it at
+# first use and explains how to install it if it's absent.
+bitwarden-sdk = { version = "^2.1", optional = true }
+
+[tool.poetry.extras]
+bitwarden = ["bitwarden-sdk"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.2"
+pytest-asyncio = "^0.23"
+mypy = "^1.10"
+
+[tool.poetry.scripts]
+secrefs-py = "secrefs.cli:main"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_unused_configs = true
+strict = true
+
+# boto3/hvac/bitwarden_sdk ship without inline type stubs (py.typed) or a
+# matching stub-only package pinned in this project; suppress the import
+# warning for just these rather than pulling in a heavy generated-stub
+# dependency (e.g. boto3-stubs) not called for in the project spec.
+# bitwarden_sdk is additionally an optional extra, so it may legitimately
+# not be installed in the environment mypy runs in.
+[[tool.mypy.overrides]]
+module = ["boto3.*", "hvac.*", "bitwarden_sdk.*"]
+ignore_missing_imports = true
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

secrefs-0.2.0/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-0.2.0/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()