flowbyte-secrets 1.0.1__tar.gz

flowbyte_secrets-1.0.1/.gitignore

@@ -0,0 +1,25 @@
+bin/
+obj/
+node_modules/
+.vs/
+*.user
+appsettings.*.local.json
+.env
+*.db
+appsettings.Secrets.json
+Application/wwwroot/app.css
+Application.Email/.next/
+**/.react-email/
+clients/python/.venv/
+clients/python/dist/
+**/__pycache__/
+*.egg-info/
+*.nupkg
+TestResults/
+.claude/worktrees/
+*.snupkg
+*.tsbuildinfo
+.pytest_cache/
+nupkg/
+Application/appsettings.json
+Application/appsettings.Development.json

flowbyte_secrets-1.0.1/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.5
+Name: flowbyte-secrets
+Version: 1.0.1
+Summary: Python client for the Flowbyte Secrets machine API (fbs_ access tokens), with an optional Dagster resource.
+Author: Flowbyte
+License: Proprietary
+Keywords: configuration,dagster,flowbyte,secrets
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dagster
+Requires-Dist: dagster>=1.7; extra == 'dagster'
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# flowbyte-secrets
+
+Python client for the Flowbyte Secrets machine API (`fbs_` access tokens), with an optional Dagster resource.
+
+```bash
+pip install flowbyte-secrets            # or: pip install "flowbyte-secrets[dagster]"
+```
+
+```python
+import os
+from flowbyte_secrets import SecretsClient, SecretNotFound
+
+c = SecretsClient(base_url="https://secrets.gmrlapp.com", token=os.environ["FBS_TOKEN"], project="dagster-prod")
+c.get("DB_PASSWORD")           # str, raises SecretNotFound
+c.list()                       # [Secret(key, value, version, modified_on)]
+c.set("K", "v")                # ReadWrite tokens only
+c.load_into_env(prefix="")     # os.environ injection
+```
+
+`base_url`, `token` and `project` fall back to `FBS_URL`, `FBS_TOKEN` and `FBS_PROJECT`.
+
+Dagster:
+
+```python
+from dagster import Definitions, EnvVar, asset
+from flowbyte_secrets.dagster import FlowbyteSecretsResource
+
+@asset
+def my_asset(secrets: FlowbyteSecretsResource):
+    pw = secrets.get("DB_PASSWORD")
+
+defs = Definitions(assets=[my_asset], resources={
+    "secrets": FlowbyteSecretsResource(base_url=EnvVar("FBS_URL"), token=EnvVar("FBS_TOKEN"), project="dagster-prod"),
+})
+```
+
+See `docs/CLIENTS.md` in the repository for details.

flowbyte_secrets-1.0.1/README.md

@@ -0,0 +1,37 @@
+# flowbyte-secrets
+
+Python client for the Flowbyte Secrets machine API (`fbs_` access tokens), with an optional Dagster resource.
+
+```bash
+pip install flowbyte-secrets            # or: pip install "flowbyte-secrets[dagster]"
+```
+
+```python
+import os
+from flowbyte_secrets import SecretsClient, SecretNotFound
+
+c = SecretsClient(base_url="https://secrets.gmrlapp.com", token=os.environ["FBS_TOKEN"], project="dagster-prod")
+c.get("DB_PASSWORD")           # str, raises SecretNotFound
+c.list()                       # [Secret(key, value, version, modified_on)]
+c.set("K", "v")                # ReadWrite tokens only
+c.load_into_env(prefix="")     # os.environ injection
+```
+
+`base_url`, `token` and `project` fall back to `FBS_URL`, `FBS_TOKEN` and `FBS_PROJECT`.
+
+Dagster:
+
+```python
+from dagster import Definitions, EnvVar, asset
+from flowbyte_secrets.dagster import FlowbyteSecretsResource
+
+@asset
+def my_asset(secrets: FlowbyteSecretsResource):
+    pw = secrets.get("DB_PASSWORD")
+
+defs = Definitions(assets=[my_asset], resources={
+    "secrets": FlowbyteSecretsResource(base_url=EnvVar("FBS_URL"), token=EnvVar("FBS_TOKEN"), project="dagster-prod"),
+})
+```
+
+See `docs/CLIENTS.md` in the repository for details.

flowbyte_secrets-1.0.1/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flowbyte-secrets"
+dynamic = ["version"]
+description = "Python client for the Flowbyte Secrets machine API (fbs_ access tokens), with an optional Dagster resource."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "Flowbyte" }]
+keywords = ["secrets", "configuration", "dagster", "flowbyte"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+dagster = ["dagster>=1.7"]
+dev = ["pytest>=8", "respx>=0.21"]
+
+[tool.hatch.version]
+path = "src/flowbyte_secrets/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flowbyte_secrets"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/flowbyte_secrets", "tests", "README.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

flowbyte_secrets-1.0.1/src/flowbyte_secrets/__init__.py

@@ -0,0 +1,40 @@
+"""Flowbyte Secrets Python client.
+
+>>> from flowbyte_secrets import SecretsClient
+>>> c = SecretsClient(base_url="https://secrets.gmrlapp.com", token=os.environ["FBS_TOKEN"], project="dagster-prod")
+>>> c.get("DB_PASSWORD")
+
+The Dagster resource lives in :mod:`flowbyte_secrets.dagster` (``pip install flowbyte-secrets[dagster]``).
+"""
+
+from ._version import __version__
+from .client import Project, Secret, SecretsClient, TokenScope, WhoAmI
+from .env import load_into_env, to_env, to_env_name
+from .errors import (
+    SecretNotFound,
+    SecretsAuthError,
+    SecretsConfigError,
+    SecretsConnectionError,
+    SecretsError,
+    SecretsForbiddenError,
+    SecretsRateLimitError,
+)
+
+__all__ = [
+    "__version__",
+    "SecretsClient",
+    "Secret",
+    "Project",
+    "TokenScope",
+    "WhoAmI",
+    "load_into_env",
+    "to_env",
+    "to_env_name",
+    "SecretsError",
+    "SecretsConfigError",
+    "SecretsConnectionError",
+    "SecretsAuthError",
+    "SecretsForbiddenError",
+    "SecretNotFound",
+    "SecretsRateLimitError",
+]

flowbyte_secrets-1.0.1/src/flowbyte_secrets/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.1"

flowbyte_secrets-1.0.1/src/flowbyte_secrets/client.py

@@ -0,0 +1,363 @@
+"""HTTP client for the Flowbyte Secrets machine API (``/api/v1/*``)."""
+
+from __future__ import annotations
+
+import os
+import random
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from email.utils import parsedate_to_datetime
+from typing import Any, Callable, Dict, List, MutableMapping, Optional
+from urllib.parse import quote, urlsplit
+
+import httpx
+
+
+def _is_loopback(url: str) -> bool:
+    host = (urlsplit(url).hostname or "").lower()
+    return host in ("localhost", "::1") or host.startswith("127.")
+
+from ._version import __version__
+from .errors import (
+    SecretNotFound,
+    SecretsAuthError,
+    SecretsConfigError,
+    SecretsConnectionError,
+    SecretsError,
+    SecretsForbiddenError,
+    SecretsRateLimitError,
+)
+
+USER_AGENT = f"flowbyte-secrets-python/{__version__}"
+ENV_URL = "FBS_URL"
+ENV_TOKEN = "FBS_TOKEN"
+ENV_PROJECT = "FBS_PROJECT"
+
+_LEVELS = {1: "Read", 2: "ReadWrite", 3: "Manage"}
+
+
+def _level(value: Any) -> str:
+    if isinstance(value, int):
+        return _LEVELS.get(value, str(value))
+    return "" if value is None else str(value)
+
+
+def _parse_dt(value: Any) -> Optional[datetime]:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _json(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError:
+        # Never include the payload (it may contain secret values).
+        raise SecretsError("The server returned a response that could not be parsed.", response.status_code) from None
+
+
+@dataclass(frozen=True)
+class Secret:
+    key: str
+    value: str = field(repr=False)  # never shown in repr/logs
+    version: int = 0
+    modified_on: Optional[datetime] = None
+
+
+@dataclass(frozen=True)
+class Project:
+    id: str
+    slug: str
+    name: str
+    level: str
+
+    @property
+    def can_write(self) -> bool:
+        return self.level in ("ReadWrite", "Manage")
+
+
+@dataclass(frozen=True)
+class TokenScope:
+    project_id: str
+    level: str
+    slug: Optional[str] = None
+    name: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class WhoAmI:
+    machine_account: str
+    token_name: str
+    company_id: str
+    scopes: List[TokenScope]
+
+
+class SecretsClient:
+    """Client for the Flowbyte Secrets machine API.
+
+    ``base_url``, ``token`` and ``project`` fall back to ``FBS_URL``, ``FBS_TOKEN`` and ``FBS_PROJECT``.
+    Requests are retried (``max_retries``, exponential backoff) on connection errors, 5xx and 429
+    (honouring ``Retry-After``). Writes are only retried when the request cannot have been applied
+    (connection refused, 429, 503).
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        token: Optional[str] = None,
+        project: Optional[str] = None,
+        *,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        backoff_factor: float = 0.5,
+        max_retry_delay: float = 30.0,
+        transport: Optional[httpx.BaseTransport] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        base_url = (base_url or os.environ.get(ENV_URL) or "").strip()
+        token = (token or os.environ.get(ENV_TOKEN) or "").strip()
+        project = (project or os.environ.get(ENV_PROJECT) or "").strip() or None
+
+        if not base_url:
+            raise SecretsConfigError(f"base_url is required (or set {ENV_URL}).")
+        if not base_url.startswith(("https://", "http://")):
+            raise SecretsConfigError("base_url must be an absolute http(s) URL.")
+        if base_url.startswith("http://") and not _is_loopback(base_url):
+            # The token is a bearer credential: plain http is only acceptable on this machine.
+            raise SecretsConfigError("base_url must use https (http is only allowed for localhost).")
+        if not token:
+            raise SecretsConfigError(f"token is required (or set {ENV_TOKEN}).")
+        if not token.startswith("fbs_") or any(c.isspace() for c in token):
+            raise SecretsConfigError("token is not a Flowbyte Secrets access token (expected 'fbs_...').")
+
+        self.base_url = base_url.rstrip("/") + "/"
+        self.project = project
+        self.timeout = timeout
+        self.max_retries = max(0, int(max_retries))
+        self.backoff_factor = backoff_factor
+        self.max_retry_delay = max_retry_delay
+        self._token = token
+        self._sleep: Callable[[float], None] = time.sleep
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout, transport=transport)
+
+    # ------------------------------------------------------------------ public API
+
+    def projects(self) -> List[Project]:
+        """Projects the token is scoped to."""
+        data = _json(self._request("GET", "api/v1/projects", project=None, idempotent=True))
+        return [
+            Project(id=str(p.get("id", "")), slug=p.get("slug", ""), name=p.get("name", ""), level=_level(p.get("level")))
+            for p in data
+        ]
+
+    def list(self, project: Optional[str] = None) -> List[Secret]:
+        """All secrets (with values) of ``project`` / the default project / the token's only project."""
+        project = self._project(project)
+        data = _json(self._request("GET", "api/v1/secrets", project=project, idempotent=True))
+        return [
+            Secret(
+                key=s.get("key", ""),
+                value=s.get("value", ""),
+                version=int(s.get("version") or 0),
+                modified_on=_parse_dt(s.get("modifiedOn")),
+            )
+            for s in data
+        ]
+
+    def as_dict(self, project: Optional[str] = None) -> Dict[str, str]:
+        """``{key: value}`` for all secrets of the project."""
+        return {s.key: s.value for s in self.list(project)}
+
+    def get_secret(self, key: str, project: Optional[str] = None) -> Secret:
+        """One secret with its version. Raises :class:`SecretNotFound`."""
+        self._check_key(key)
+        project = self._project(project)
+        s = _json(self._request("GET", self._secret_path(key), project=project, idempotent=True, key=key))
+        return Secret(key=s.get("key", key), value=s.get("value", ""), version=int(s.get("version") or 0))
+
+    def get(self, key: str, project: Optional[str] = None) -> str:
+        """One secret's value. Raises :class:`SecretNotFound`."""
+        return self.get_secret(key, project).value
+
+    def get_or_default(self, key: str, default: Optional[str] = None, project: Optional[str] = None) -> Optional[str]:
+        """One secret's value, or ``default`` when it does not exist."""
+        try:
+            return self.get(key, project)
+        except SecretNotFound:
+            return default
+
+    def set(self, key: str, value: str, note: Optional[str] = None, project: Optional[str] = None) -> None:
+        """Create or update a secret (ReadWrite token)."""
+        self._check_key(key)
+        if value is None:
+            raise ValueError("value is required")
+        body: Dict[str, Any] = {"value": value}
+        if note is not None:
+            body["note"] = note
+        self._request("PUT", self._secret_path(key), project=self._project(project), idempotent=False, key=key, json=body)
+
+    def delete(self, key: str, project: Optional[str] = None) -> None:
+        """Delete a secret (ReadWrite token). Raises :class:`SecretNotFound`."""
+        self._check_key(key)
+        self._request("DELETE", self._secret_path(key), project=self._project(project), idempotent=False, key=key)
+
+    def whoami(self) -> WhoAmI:
+        """Machine account, token name, company and scopes of the token."""
+        d = _json(self._request("GET", "api/v1/whoami", project=None, idempotent=True))
+        scopes: List[TokenScope] = []
+        for s in d.get("scopes") or []:
+            if isinstance(s, str):
+                pid, _, lvl = s.rpartition(":")
+                scopes.append(TokenScope(project_id=pid or s, level=lvl if pid else ""))
+            elif isinstance(s, dict):
+                scopes.append(
+                    TokenScope(
+                        project_id=str(s.get("projectId") or s.get("id") or ""),
+                        level=_level(s.get("level")),
+                        slug=s.get("slug"),
+                        name=s.get("name"),
+                    )
+                )
+        return WhoAmI(
+            machine_account=d.get("machineAccount", ""),
+            token_name=d.get("tokenName", ""),
+            company_id=d.get("companyId", ""),
+            scopes=scopes,
+        )
+
+    def load_into_env(
+        self,
+        prefix: str = "",
+        project: Optional[str] = None,
+        *,
+        override: bool = True,
+        map_dots: bool = False,
+        environ: Optional[MutableMapping[str, str]] = None,
+    ) -> List[str]:
+        """Inject all secrets into ``os.environ`` (or ``environ``). Returns the variable names set."""
+        from .env import load_into_env
+
+        return load_into_env(self.list(project), prefix=prefix, override=override, map_dots=map_dots, environ=environ)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> "SecretsClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"SecretsClient(base_url={self.base_url!r}, project={self.project!r}, token=<redacted>)"
+
+    # ------------------------------------------------------------------ internals
+
+    def _project(self, project: Optional[str]) -> Optional[str]:
+        return (project or "").strip() or self.project
+
+    @staticmethod
+    def _check_key(key: str) -> None:
+        if not key or not key.strip():
+            raise ValueError("key is required")
+
+    @staticmethod
+    def _secret_path(key: str) -> str:
+        return "api/v1/secrets/" + quote(key, safe="")
+
+    def _backoff(self, attempt: int) -> float:
+        return min(self.max_retry_delay, self.backoff_factor * (2**attempt) + random.uniform(0, 0.1))
+
+    @staticmethod
+    def _retry_after(response: httpx.Response) -> Optional[float]:
+        value = response.headers.get("Retry-After")
+        if not value:
+            return None
+        try:
+            return max(0.0, float(value))
+        except ValueError:
+            pass
+        try:
+            when = parsedate_to_datetime(value)
+            return max(0.0, when.timestamp() - time.time())
+        except (TypeError, ValueError):
+            return None
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        project: Optional[str],
+        idempotent: bool,
+        key: Optional[str] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> httpx.Response:
+        url = self.base_url + path
+        params = {"project": project} if project else None
+        headers = {
+            "Authorization": f"Bearer {self._token}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(method, url, params=params, headers=headers, json=json, timeout=self.timeout)
+            except (httpx.ConnectError, httpx.ConnectTimeout) as exc:
+                # Request never reached the server: safe to retry for any method.
+                if attempt < self.max_retries:
+                    self._sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise SecretsConnectionError(f"Could not reach {self.base_url}: {type(exc).__name__}") from None
+            except httpx.TransportError as exc:  # read timeouts, protocol errors, ...
+                if idempotent and attempt < self.max_retries:
+                    self._sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise SecretsConnectionError(f"Request to {self.base_url} failed: {type(exc).__name__}") from None
+
+            status = response.status_code
+            retryable = status in (429, 503) or (idempotent and status >= 500)
+            if retryable and attempt < self.max_retries:
+                delay = self._retry_after(response) if status in (429, 503) else None
+                self._sleep(min(self.max_retry_delay, delay if delay is not None else self._backoff(attempt)))
+                attempt += 1
+                continue
+
+            if status < 400:
+                return response
+            self._raise_for_status(response, key, project)
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response, key: Optional[str], project: Optional[str]) -> None:
+        status = response.status_code
+        where = f"project '{project}'" if project else "the token's project"
+        if status == 401:
+            raise SecretsAuthError("Unauthorized (401): the access token is invalid, expired or revoked.", 401)
+        if status == 403:
+            raise SecretsForbiddenError(f"Forbidden (403): the token is not allowed to perform this operation on {where}.", 403)
+        if status == 404:
+            if key is None:
+                raise SecretNotFound(f"Not found (404): {where} does not exist or is not in the token's scope.")
+            raise SecretNotFound(f"Not found (404): secret '{key}' does not exist in {where}.", key=key)
+        if status == 429:
+            raise SecretsRateLimitError("Rate limited (429): too many requests; retries exhausted.",
+                                        SecretsClient._retry_after(response))
+        # Only the ProblemDetails title is used: the body/detail could echo a submitted value.
+        title = None
+        try:
+            body = response.json()
+            if isinstance(body, dict) and isinstance(body.get("title"), str):
+                title = body["title"][:200]
+        except ValueError:
+            pass
+        raise SecretsError(f"The Flowbyte Secrets server returned {status} ({title or response.reason_phrase}).", status)

flowbyte_secrets-1.0.1/src/flowbyte_secrets/dagster.py

@@ -0,0 +1,73 @@
+"""Dagster resource (requires ``pip install flowbyte-secrets[dagster]``).
+
+.. code-block:: python
+
+    from dagster import Definitions, EnvVar, asset
+    from flowbyte_secrets.dagster import FlowbyteSecretsResource
+
+    @asset
+    def my_asset(secrets: FlowbyteSecretsResource):
+        pw = secrets.get("DB_PASSWORD")
+
+    defs = Definitions(
+        assets=[my_asset],
+        resources={"secrets": FlowbyteSecretsResource(base_url=EnvVar("FBS_URL"), token=EnvVar("FBS_TOKEN"), project="dagster-prod")},
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+try:
+    from dagster import ConfigurableResource
+    from pydantic import Field, PrivateAttr
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise ImportError(
+        "flowbyte_secrets.dagster requires Dagster. Install with: pip install 'flowbyte-secrets[dagster]'"
+    ) from exc
+
+from .client import Secret, SecretsClient
+
+
+class FlowbyteSecretsResource(ConfigurableResource):
+    """Reads secrets from Flowbyte Secrets with a machine access token."""
+
+    base_url: str = Field(description="Server URL, e.g. https://secrets.gmrlapp.com (use EnvVar('FBS_URL')).")
+    token: str = Field(description="Access token fbs_... (use EnvVar('FBS_TOKEN'); never hard-code).")
+    project: Optional[str] = Field(default=None, description="Project slug or id; optional for single-project tokens.")
+    timeout: float = Field(default=10.0, description="HTTP timeout in seconds.")
+    max_retries: int = Field(default=3, description="Retries on connection errors, 5xx and 429.")
+
+    _client: Optional[SecretsClient] = PrivateAttr(default=None)
+
+    def _get_client(self) -> SecretsClient:
+        if self._client is None:
+            self._client = SecretsClient(
+                base_url=self.base_url,
+                token=self.token,
+                project=self.project,
+                timeout=self.timeout,
+                max_retries=self.max_retries,
+            )
+        return self._client
+
+    def teardown_after_execution(self, context) -> None:  # type: ignore[override]
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    def get(self, key: str, project: Optional[str] = None) -> str:
+        return self._get_client().get(key, project)
+
+    def get_or_default(self, key: str, default: Optional[str] = None, project: Optional[str] = None) -> Optional[str]:
+        return self._get_client().get_or_default(key, default, project)
+
+    def list(self, project: Optional[str] = None) -> List[Secret]:
+        return self._get_client().list(project)
+
+    def as_dict(self, project: Optional[str] = None) -> Dict[str, str]:
+        return self._get_client().as_dict(project)
+
+    def load_into_env(self, prefix: str = "", project: Optional[str] = None, *, override: bool = True, map_dots: bool = False) -> List[str]:
+        return self._get_client().load_into_env(prefix, project, override=override, map_dots=map_dots)

flowbyte_secrets-1.0.1/src/flowbyte_secrets/env.py

@@ -0,0 +1,58 @@
+"""Environment-variable helpers (same mapping rules as ``fbs run``)."""
+
+from __future__ import annotations
+
+import os
+import re
+import warnings
+from typing import Dict, Iterable, List, MutableMapping, Optional
+
+from .client import Secret
+
+_INVALID = re.compile(r"[^A-Za-z0-9_]")
+
+
+def to_env_name(key: str, prefix: str = "", map_dots: bool = False) -> str:
+    """Map a secret key to an environment variable name.
+
+    With ``map_dots``, ``.`` becomes ``__`` (``Database.Password`` -> ``Database__Password``);
+    every other character outside ``[A-Za-z0-9_]`` (including ``.`` and ``-``) becomes ``_``.
+    ``prefix`` is prepended verbatim; case is preserved.
+    """
+    name = key.replace(".", "__") if map_dots else key
+    name = (prefix or "") + _INVALID.sub("_", name)
+    if name[:1].isdigit():
+        name = "_" + name
+    return name
+
+
+def to_env(secrets: Iterable[Secret], prefix: str = "", map_dots: bool = False) -> Dict[str, str]:
+    """``{ENV_NAME: value}``; on name collisions the later key wins (a warning names the keys, never values)."""
+    result: Dict[str, str] = {}
+    origin: Dict[str, str] = {}
+    for s in secrets:
+        name = to_env_name(s.key, prefix, map_dots)
+        if name in origin:
+            warnings.warn(f"secret keys '{origin[name]}' and '{s.key}' both map to {name}; using '{s.key}'", stacklevel=2)
+        result[name] = s.value
+        origin[name] = s.key
+    return result
+
+
+def load_into_env(
+    secrets: Iterable[Secret],
+    prefix: str = "",
+    *,
+    override: bool = True,
+    map_dots: bool = False,
+    environ: Optional[MutableMapping[str, str]] = None,
+) -> List[str]:
+    """Set the secrets in ``os.environ`` (or ``environ``). Returns the names that were set."""
+    target = os.environ if environ is None else environ
+    names: List[str] = []
+    for name, value in to_env(secrets, prefix, map_dots).items():
+        if not override and name in target:
+            continue
+        target[name] = value
+        names.append(name)
+    return names

flowbyte_secrets-1.0.1/src/flowbyte_secrets/errors.py

@@ -0,0 +1,45 @@
+"""Typed errors. Messages never contain secret values or the access token."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class SecretsError(Exception):
+    """Base class for Flowbyte Secrets errors."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class SecretsConfigError(SecretsError):
+    """Missing or malformed client settings (base URL, token)."""
+
+
+class SecretsConnectionError(SecretsError):
+    """The server could not be reached (after retries) or timed out."""
+
+
+class SecretsAuthError(SecretsError):
+    """401 (bad/expired/revoked token) or 403 (token not scoped for this project/operation)."""
+
+
+class SecretsForbiddenError(SecretsAuthError):
+    """403: the token is valid but lacks the scope (e.g. a Read token writing)."""
+
+
+class SecretNotFound(SecretsError):
+    """404: the secret or project does not exist (or is outside the token's scope)."""
+
+    def __init__(self, message: str, key: Optional[str] = None) -> None:
+        super().__init__(message, 404)
+        self.key = key
+
+
+class SecretsRateLimitError(SecretsError):
+    """429 after retries were exhausted."""
+
+    def __init__(self, message: str, retry_after: Optional[float] = None) -> None:
+        super().__init__(message, 429)
+        self.retry_after = retry_after

flowbyte_secrets-1.0.1/tests/test_client.py

@@ -0,0 +1,254 @@
+import json
+import os
+
+import httpx
+import pytest
+import respx
+
+from flowbyte_secrets import (
+    SecretNotFound,
+    SecretsAuthError,
+    SecretsClient,
+    SecretsConfigError,
+    SecretsConnectionError,
+    SecretsError,
+    SecretsForbiddenError,
+    SecretsRateLimitError,
+    __version__,
+    load_into_env,
+    to_env_name,
+)
+from flowbyte_secrets.client import Secret
+
+BASE = "https://secrets.test"
+TOKEN = "fbs_" + "A" * 43
+VALUE = "s3cr3t-never-in-messages"
+
+
+@pytest.fixture
+def client():
+    c = SecretsClient(base_url=BASE, token=TOKEN, project="demo", max_retries=3)
+    c._sleep = lambda _s: None  # no real backoff in tests
+    yield c
+    c.close()
+
+
+@pytest.fixture(autouse=True)
+def _clean_env(monkeypatch):
+    for name in ("FBS_URL", "FBS_TOKEN", "FBS_PROJECT"):
+        monkeypatch.delenv(name, raising=False)
+
+
+@respx.mock
+def test_list_sends_auth_user_agent_and_project(client):
+    route = respx.get(f"{BASE}/api/v1/secrets").mock(
+        return_value=httpx.Response(200, json=[
+            {"key": "DB_PASSWORD", "value": "pw", "version": 3, "modifiedOn": "2026-01-02T03:04:05Z"},
+            {"key": "Api__Key", "value": "k", "version": 1, "modifiedOn": None},
+        ])
+    )
+    items = client.list()
+    assert [s.key for s in items] == ["DB_PASSWORD", "Api__Key"]
+    assert items[0].value == "pw" and items[0].version == 3
+    assert items[0].modified_on.year == 2026
+    req = route.calls.last.request
+    assert req.headers["Authorization"] == f"Bearer {TOKEN}"
+    assert req.headers["User-Agent"] == f"flowbyte-secrets-python/{__version__}"
+    assert req.url.params["project"] == "demo"
+
+
+@respx.mock
+def test_get_escapes_key_and_returns_value(client):
+    route = respx.get(f"{BASE}/api/v1/secrets/a%2Fb%20c").mock(
+        return_value=httpx.Response(200, json={"key": "a/b c", "value": "v", "version": 2})
+    )
+    assert client.get("a/b c") == "v"
+    assert route.called
+
+
+@respx.mock
+def test_set_and_delete(client):
+    put = respx.put(f"{BASE}/api/v1/secrets/K").mock(return_value=httpx.Response(204))
+    delete = respx.delete(f"{BASE}/api/v1/secrets/K").mock(return_value=httpx.Response(204))
+    client.set("K", "v1", note="n")
+    client.set("K", "v2")
+    client.delete("K")
+    assert json.loads(put.calls[0].request.content) == {"value": "v1", "note": "n"}
+    assert json.loads(put.calls[1].request.content) == {"value": "v2"}
+    assert delete.called
+
+
+@respx.mock
+def test_401_and_403_raise_auth_errors_without_secrets(client):
+    respx.get(f"{BASE}/api/v1/secrets").mock(return_value=httpx.Response(401))
+    respx.put(f"{BASE}/api/v1/secrets/K").mock(return_value=httpx.Response(403))
+    with pytest.raises(SecretsAuthError) as e401:
+        client.list()
+    assert e401.value.status_code == 401
+    assert TOKEN not in str(e401.value)
+    with pytest.raises(SecretsForbiddenError) as e403:
+        client.set("K", VALUE)
+    assert isinstance(e403.value, SecretsAuthError)
+    assert VALUE not in str(e403.value)
+
+
+@respx.mock
+def test_404_raises_not_found_and_get_or_default(client):
+    respx.get(f"{BASE}/api/v1/secrets/MISSING").mock(return_value=httpx.Response(404))
+    with pytest.raises(SecretNotFound) as exc:
+        client.get("MISSING")
+    assert exc.value.key == "MISSING"
+    assert client.get_or_default("MISSING", "fallback") == "fallback"
+
+
+@respx.mock
+def test_5xx_retried_then_succeeds(client):
+    route = respx.get(f"{BASE}/api/v1/secrets").mock(
+        side_effect=[httpx.Response(502), httpx.Response(500), httpx.Response(200, json=[])]
+    )
+    assert client.list() == []
+    assert route.call_count == 3
+
+
+@respx.mock
+def test_5xx_exhausted_raises_without_body(client):
+    route = respx.get(f"{BASE}/api/v1/secrets").mock(
+        return_value=httpx.Response(500, json={"title": "Boom", "detail": f"value {VALUE}"})
+    )
+    with pytest.raises(SecretsError) as exc:
+        client.list()
+    assert route.call_count == 4  # 1 + 3 retries
+    assert "Boom" in str(exc.value)
+    assert VALUE not in str(exc.value)
+
+
+@respx.mock
+def test_writes_not_retried_on_500(client):
+    route = respx.put(f"{BASE}/api/v1/secrets/K").mock(return_value=httpx.Response(500))
+    with pytest.raises(SecretsError):
+        client.set("K", "v")
+    assert route.call_count == 1
+
+
+@respx.mock
+def test_connection_errors_retried_then_raise(client):
+    route = respx.get(f"{BASE}/api/v1/secrets").mock(side_effect=httpx.ConnectError("refused"))
+    with pytest.raises(SecretsConnectionError):
+        client.list()
+    assert route.call_count == 4
+
+
+@respx.mock
+def test_429_honours_retry_after(client):
+    sleeps = []
+    client._sleep = sleeps.append
+    respx.get(f"{BASE}/api/v1/secrets").mock(
+        side_effect=[httpx.Response(429, headers={"Retry-After": "7"}), httpx.Response(200, json=[])]
+    )
+    client.list()
+    assert sleeps == [7.0]
+
+
+@respx.mock
+def test_429_exhausted(client):
+    respx.get(f"{BASE}/api/v1/secrets").mock(return_value=httpx.Response(429, headers={"Retry-After": "1"}))
+    with pytest.raises(SecretsRateLimitError) as exc:
+        client.list()
+    assert exc.value.retry_after == 1.0
+
+
+@respx.mock
+def test_unparseable_body_does_not_leak(client):
+    respx.get(f"{BASE}/api/v1/secrets").mock(return_value=httpx.Response(200, text=f'[{{"value":"{VALUE}"'))
+    with pytest.raises(SecretsError) as exc:
+        client.list()
+    assert VALUE not in str(exc.value)
+
+
+@respx.mock
+def test_whoami_and_projects(client):
+    respx.get(f"{BASE}/api/v1/whoami").mock(return_value=httpx.Response(200, json={
+        "machineAccount": "dagster", "tokenName": "prod", "companyId": "GMRL",
+        "scopes": ["p1:Read", {"projectId": "p2", "slug": "demo", "level": 2}],
+    }))
+    respx.get(f"{BASE}/api/v1/projects").mock(return_value=httpx.Response(200, json=[
+        {"id": "p2", "slug": "demo", "name": "Demo", "level": "ReadWrite"},
+    ]))
+    me = client.whoami()
+    assert me.company_id == "GMRL"
+    assert me.scopes[0].project_id == "p1" and me.scopes[0].level == "Read"
+    assert me.scopes[1].slug == "demo" and me.scopes[1].level == "ReadWrite"
+    assert client.projects()[0].can_write
+
+
+@respx.mock
+def test_env_fallbacks(monkeypatch):
+    monkeypatch.setenv("FBS_URL", "https://env.test/")
+    monkeypatch.setenv("FBS_TOKEN", TOKEN)
+    monkeypatch.setenv("FBS_PROJECT", "env-proj")
+    route = respx.get("https://env.test/api/v1/secrets").mock(return_value=httpx.Response(200, json=[]))
+    with SecretsClient() as c:
+        c.list()
+    assert route.calls.last.request.url.params["project"] == "env-proj"
+
+
+@respx.mock
+def test_no_project_omits_query():
+    route = respx.get(f"{BASE}/api/v1/secrets").mock(return_value=httpx.Response(200, json=[]))
+    with SecretsClient(base_url=BASE, token=TOKEN) as c:
+        c.list()
+    assert "project" not in route.calls.last.request.url.params
+
+
+def test_config_errors_do_not_echo_token():
+    with pytest.raises(SecretsConfigError):
+        SecretsClient(base_url=BASE)
+    with pytest.raises(SecretsConfigError) as exc:
+        SecretsClient(base_url=BASE, token="ghp_wrongtoken123")
+    assert "ghp_wrongtoken123" not in str(exc.value)
+    with pytest.raises(SecretsConfigError):
+        SecretsClient(base_url="ftp://x", token=TOKEN)
+
+
+def test_repr_hides_token_and_values():
+    c = SecretsClient(base_url=BASE, token=TOKEN)
+    assert TOKEN not in repr(c)
+    assert VALUE not in repr(Secret(key="K", value=VALUE))
+    c.close()
+
+
+@respx.mock
+def test_load_into_env(client):
+    respx.get(f"{BASE}/api/v1/secrets").mock(return_value=httpx.Response(200, json=[
+        {"key": "DB_PASSWORD", "value": "pw", "version": 1},
+        {"key": "api.key", "value": "k", "version": 1},
+    ]))
+    env = {"DB_PASSWORD": "existing"}
+    names = client.load_into_env(prefix="APP_", environ=env)
+    assert sorted(names) == ["APP_DB_PASSWORD", "APP_api_key"]
+    assert env["APP_DB_PASSWORD"] == "pw"
+
+    env2 = {"DB_PASSWORD": "existing"}
+    load_into_env([Secret("DB_PASSWORD", "pw")], override=False, environ=env2)
+    assert env2["DB_PASSWORD"] == "existing"
+
+
+@pytest.mark.parametrize(
+    "key,prefix,map_dots,expected",
+    [
+        ("DB_PASSWORD", "", False, "DB_PASSWORD"),
+        ("Database__Password", "", False, "Database__Password"),
+        ("db.password", "", False, "db_password"),
+        ("db.password", "", True, "db__password"),
+        ("api-key", "APP_", False, "APP_api_key"),
+    ],
+)
+def test_to_env_name(key, prefix, map_dots, expected):
+    assert to_env_name(key, prefix, map_dots) == expected
+
+
+def test_load_into_env_defaults_to_os_environ(monkeypatch):
+    monkeypatch.delenv("FBS_TEST_X", raising=False)
+    load_into_env([Secret("FBS_TEST_X", "1")])
+    assert os.environ["FBS_TEST_X"] == "1"
+    monkeypatch.delenv("FBS_TEST_X")

flowbyte_secrets-1.0.1/tests/test_dagster.py

@@ -0,0 +1,41 @@
+import httpx
+import pytest
+import respx
+
+pytest.importorskip("dagster", reason="install flowbyte-secrets[dagster] to run the Dagster resource tests")
+
+from dagster import Definitions, asset, materialize  # noqa: E402
+
+from flowbyte_secrets.dagster import FlowbyteSecretsResource  # noqa: E402
+
+BASE = "https://secrets.test"
+TOKEN = "fbs_" + "A" * 43
+
+
+@respx.mock
+def test_resource_get_inside_asset():
+    respx.get(f"{BASE}/api/v1/secrets/DB_PASSWORD").mock(
+        return_value=httpx.Response(200, json={"key": "DB_PASSWORD", "value": "pw", "version": 1})
+    )
+    seen = {}
+
+    @asset
+    def my_asset(secrets: FlowbyteSecretsResource):
+        seen["pw"] = secrets.get("DB_PASSWORD")
+
+    result = materialize(
+        [my_asset],
+        resources={"secrets": FlowbyteSecretsResource(base_url=BASE, token=TOKEN, project="demo")},
+    )
+    assert result.success
+    assert seen["pw"] == "pw"
+
+
+@respx.mock
+def test_resource_direct_use():
+    respx.get(f"{BASE}/api/v1/secrets").mock(
+        return_value=httpx.Response(200, json=[{"key": "A", "value": "1", "version": 1}])
+    )
+    r = FlowbyteSecretsResource(base_url=BASE, token=TOKEN)
+    assert r.as_dict() == {"A": "1"}
+    Definitions(resources={"secrets": r})  # resource is accepted by Definitions

flowbyte_secrets-1.0.1/tests/test_https.py

@@ -0,0 +1,17 @@
+import pytest
+
+from flowbyte_secrets import SecretsClient
+from flowbyte_secrets.errors import SecretsConfigError
+
+TOKEN = "fbs_" + "A" * 43
+
+
+@pytest.mark.parametrize("url", ["http://secrets.example.com", "http://10.0.0.5:7240"])
+def test_plain_http_to_remote_host_is_refused(url):
+    with pytest.raises(SecretsConfigError, match="https"):
+        SecretsClient(base_url=url, token=TOKEN)
+
+
+@pytest.mark.parametrize("url", ["https://secrets.example.com", "http://localhost:7240", "http://127.0.0.1:7240"])
+def test_https_and_loopback_http_are_allowed(url):
+    SecretsClient(base_url=url, token=TOKEN).close()