credchain 0.1.0__py3-none-any.whl

credchain/__init__.py

@@ -0,0 +1,38 @@
+"""credchain: read credentials from a chain of sources, with automatic fallback.
+
+Providers (import directly):
+    CredentialsProviderChain        — tries providers in order until one succeeds
+    EnvironmentCredentialsProvider  — reads from environment variables
+    FileCredentialsProvider         — reads from files, e.g. mounted container secrets
+    KeyringCredentialsProvider      — reads from the OS keychain (requires credchain[keyring])
+
+Usage::
+
+    from credchain import CredentialsProviderChain, EnvironmentCredentialsProvider
+    from credchain.keyring import KeyringCredentialsProvider  # optional dep
+
+    chain = CredentialsProviderChain([
+        EnvironmentCredentialsProvider("MY_USERNAME", "MY_PASSWORD"),
+        KeyringCredentialsProvider("my-service"),
+    ])
+    username, password = chain.get_credentials()
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .chain import CredentialsProviderChain
+from .env import EnvironmentCredentialsProvider
+from .file import FileCredentialsProvider
+from .protocol import CredentialsProvider
+
+try:
+    __version__ = version("credchain")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"
+
+__all__ = [
+    "CredentialsProvider",
+    "CredentialsProviderChain",
+    "EnvironmentCredentialsProvider",
+    "FileCredentialsProvider",
+]

credchain/chain.py

@@ -0,0 +1,38 @@
+import logging
+
+from .protocol import CredentialsProvider
+
+logger = logging.getLogger(__name__)
+
+
+class CredentialsProviderChain:
+    """Chain of credentials providers invoked in priority order until one succeeds.
+
+    Nothing derived from a credential is logged, not even a prefix: in token
+    mode a provider returns the token in both positions, so a "username" may
+    be a secret.
+    """
+
+    def __init__(self, providers: list[CredentialsProvider]):
+        self.providers = providers
+
+    def get_credentials(self) -> tuple[str | None, str | None]:
+        logger.debug("Retrieving credentials using credentials provider chain...")
+        for i, provider in enumerate(self.providers):
+            name = provider.__class__.__name__
+            try:
+                logger.debug(
+                    f"Trying provider {i + 1}/{len(self.providers)}: {name}..."
+                )
+                username, password = provider.get_credentials()
+                if username and password:
+                    logger.debug(f"Retrieved credentials from {name}")
+                    return username, password
+                logger.debug(f"No credentials found from {name}")
+            except Exception as e:
+                # The exception type only: a message may quote the secret or a path to it.
+                logger.error(
+                    f"Error retrieving credentials from {name}: {type(e).__name__}"
+                )
+        logger.debug("No credentials found from any provider in the chain")
+        return None, None

credchain/env.py

@@ -0,0 +1,50 @@
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+class EnvironmentCredentialsProvider:
+    """Provider for credentials from environment variables.
+
+    Two-var mode (username + password)::
+
+        EnvironmentCredentialsProvider("MY_USERNAME", "MY_PASSWORD")
+
+    Token mode (single env var)::
+
+        EnvironmentCredentialsProvider.for_token("MY_TOKEN")
+    """
+
+    def __init__(self, username_env_var_name: str, password_env_var_name: str):
+        self.username_env_var_name: str | None = username_env_var_name
+        self.password_env_var_name = password_env_var_name
+
+    @classmethod
+    def for_token(cls, token_env_var_name: str) -> "EnvironmentCredentialsProvider":
+        """Create a token-mode provider that reads a single environment variable."""
+        instance = cls.__new__(cls)
+        instance.username_env_var_name = None
+        instance.password_env_var_name = token_env_var_name
+        return instance
+
+    def get_credentials(self) -> tuple[str | None, str | None]:
+        if self.username_env_var_name is None:
+            token = os.environ.get(self.password_env_var_name)
+            if token:
+                logger.debug(f"Read token from ${self.password_env_var_name}")
+                return token, token
+            logger.debug(f"No token in ${self.password_env_var_name}")
+            return None, None
+
+        username = os.environ.get(self.username_env_var_name)
+        password = os.environ.get(self.password_env_var_name)
+        if username and password:
+            logger.debug(
+                f"Read credentials from ${self.username_env_var_name} and ${self.password_env_var_name}"
+            )
+            return username, password
+        logger.debug(
+            f"No credentials in ${self.username_env_var_name} and ${self.password_env_var_name}"
+        )
+        return None, None

credchain/file.py

@@ -0,0 +1,65 @@
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class FileCredentialsProvider:
+    """Provider for credentials stored in files, such as mounted container secrets.
+
+    Two-file mode (username + password)::
+
+        FileCredentialsProvider("/run/secrets/username", "/run/secrets/password")
+
+    Token mode (single file)::
+
+        FileCredentialsProvider.for_token("/run/secrets/token")
+
+    Each file holds one value; one trailing line break is removed, because
+    secret files are often written with one. A missing file means no
+    credentials, so a provider chain falls through to its next provider;
+    any other read error propagates.
+    """
+
+    def __init__(self, username_file: str | Path, password_file: str | Path):
+        self.username_file: Path | None = Path(username_file)
+        self.password_file = Path(password_file)
+
+    @classmethod
+    def for_token(cls, token_file: str | Path) -> "FileCredentialsProvider":
+        """Create a token-mode provider that reads a single file."""
+        instance = cls.__new__(cls)
+        instance.username_file = None
+        instance.password_file = Path(token_file)
+        return instance
+
+    def get_credentials(self) -> tuple[str | None, str | None]:
+        if self.username_file is None:
+            token = _read(self.password_file)
+            if token:
+                logger.debug(f"Read token from {self.password_file}")
+                return token, token
+            logger.debug(f"No token in {self.password_file}")
+            return None, None
+
+        username = _read(self.username_file)
+        password = _read(self.password_file)
+        if username and password:
+            logger.debug(
+                f"Read credentials from {self.username_file} and {self.password_file}"
+            )
+            return username, password
+        logger.debug(f"No credentials in {self.username_file} and {self.password_file}")
+        return None, None
+
+
+def _read(path: Path) -> str | None:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    if text.endswith("\r\n"):
+        return text[:-2]
+    if text.endswith("\n"):
+        return text[:-1]
+    return text

credchain/keyring.py

@@ -0,0 +1,115 @@
+import logging
+import threading
+
+try:
+    import keyring as _keyring
+except ImportError as e:
+    raise ImportError(
+        "keyring is required for KeyringCredentialsProvider. "
+        "Install it with: pip install credchain[keyring]"
+    ) from e
+
+logger = logging.getLogger(__name__)
+
+# A hung OS keychain call (e.g. a locked keychain waiting for an unlock prompt
+# that never appears in a headless session) must not stall the caller forever.
+DEFAULT_KEYRING_TIMEOUT = 5.0
+
+
+class KeyringCredentialsProvider:
+    """Provider for credentials stored in the OS keychain via keyring.
+
+    Two-key mode (username + password stored under separate account keys)::
+
+        KeyringCredentialsProvider("my-service")
+        # reads: keyring get my-service username
+        #        keyring get my-service password
+
+    Token mode (single keyring entry)::
+
+        KeyringCredentialsProvider.for_token("my-service")
+        # reads: keyring get my-service token
+
+    Or with a custom key name::
+
+        KeyringCredentialsProvider.for_token("my-service", token_key="jwt")
+        # reads: keyring get my-service jwt
+
+    The keychain lookup is bounded by ``timeout`` seconds (default 5). When the
+    keychain does not answer in time, a warning is logged and no credentials are
+    returned, so a provider chain falls through to its next provider. Pass
+    ``timeout=None`` to wait indefinitely.
+    """
+
+    def __init__(
+        self,
+        service: str,
+        username_key: str = "username",
+        password_key: str = "password",
+        timeout: float | None = DEFAULT_KEYRING_TIMEOUT,
+    ):
+        self.service = service
+        self.username_key: str | None = username_key
+        self.password_key = password_key
+        self.timeout = timeout
+
+    @classmethod
+    def for_token(
+        cls,
+        service: str,
+        token_key: str = "token",
+        timeout: float | None = DEFAULT_KEYRING_TIMEOUT,
+    ) -> "KeyringCredentialsProvider":
+        """Create a token-mode provider that reads a single keyring entry."""
+        instance = cls.__new__(cls)
+        instance.service = service
+        instance.username_key = None
+        instance.password_key = token_key
+        instance.timeout = timeout
+        return instance
+
+    def get_credentials(self) -> tuple[str | None, str | None]:
+        if self.timeout is None:
+            return self._read_credentials()
+
+        # The keyring API is synchronous and cannot be cancelled, so run it in a
+        # daemon thread and stop waiting after the timeout. A thread left hanging
+        # in the keychain does not keep the process alive on exit.
+        outcome: dict = {}
+
+        def read() -> None:
+            try:
+                outcome["result"] = self._read_credentials()
+            except BaseException as e:
+                outcome["error"] = e
+
+        thread = threading.Thread(
+            target=read, name=f"keyring-{self.service}", daemon=True
+        )
+        thread.start()
+        thread.join(self.timeout)
+        if thread.is_alive():
+            logger.warning(
+                f"Keyring service '{self.service}' did not respond within {self.timeout}s, skipping it"
+            )
+            return None, None
+        if "error" in outcome:
+            raise outcome["error"]
+        return outcome["result"]
+
+    def _read_credentials(self) -> tuple[str | None, str | None]:
+        if self.username_key is None:
+            token = _keyring.get_password(self.service, self.password_key)
+            if token:
+                logger.debug(f"Read token from keyring service '{self.service}'")
+                return token, token
+            logger.debug(f"No token in keyring service '{self.service}'")
+            return None, None
+
+        username = _keyring.get_password(self.service, self.username_key)
+        password = _keyring.get_password(self.service, self.password_key)
+        if username and password:
+            logger.debug(f"Read credentials from keyring service '{self.service}'")
+            return username, password
+        logger.debug(f"No credentials in keyring service '{self.service}'")
+        return None, None

credchain/protocol.py

@@ -0,0 +1,5 @@
+from typing import Protocol
+
+
+class CredentialsProvider(Protocol):
+    def get_credentials(self) -> tuple[str | None, str | None]: ...

credchain-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: credchain
+Version: 0.1.0
+Summary: Credential provider chain: read usernames, passwords and tokens from environment variables, the OS keychain or secret files, with automatic fallback.
+Author-email: Stephan Eberle <stephaneberle9@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Provides-Extra: keyring
+Requires-Dist: keyring>=25.0.0; extra == 'keyring'
+Description-Content-Type: text/markdown
+
+# credchain <!-- omit in toc -->
+
+Read the credentials an application needs — a username and password, or an
+API token — from environment variables, the OS keychain or secret files, with
+automatic fallback through a priority chain.
+
+`credchain` has no framework dependency. FastMCP servers that also take
+credentials from HTTP headers use
+[fastmcp-creds](https://github.com/stephaneberle9/fastmcp-creds), which builds
+on it.
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Credential provider chain](#credential-provider-chain)
+  - [Environment variables](#environment-variables)
+  - [OS keychain](#os-keychain)
+  - [Secret files](#secret-files)
+- [Logging](#logging)
+- [API Reference](#api-reference)
+  - [`CredentialsProvider`](#credentialsprovider)
+  - [`CredentialsProviderChain`](#credentialsproviderchain)
+  - [`EnvironmentCredentialsProvider`](#environmentcredentialsprovider)
+  - [`KeyringCredentialsProvider`](#keyringcredentialsprovider)
+  - [`FileCredentialsProvider`](#filecredentialsprovider)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+The package is not published to PyPI yet. Install it from its Git repository
+or a local checkout:
+
+```bash
+uv add "credchain @ git+https://github.com/stephaneberle9/python-credchain.git"
+# with the OS keychain provider:
+uv add "credchain[keyring] @ git+https://github.com/stephaneberle9/python-credchain.git"
+```
+
+Requires Python 3.10+.
+
+## Usage
+
+### Credential provider chain
+
+Compose providers in priority order. The chain tries each in sequence and
+returns the first result where both username and password (or token) are
+non-empty.
+
+```python
+from credchain import CredentialsProviderChain, EnvironmentCredentialsProvider
+from credchain.keyring import KeyringCredentialsProvider  # optional dep
+
+chain = CredentialsProviderChain([
+    EnvironmentCredentialsProvider("MY_USERNAME", "MY_PASSWORD"),
+    KeyringCredentialsProvider("my-service"),
+])
+
+username, password = chain.get_credentials()
+```
+
+A provider that raises is logged (exception type only) and skipped.
+
+### Environment variables
+
+```python
+from credchain import EnvironmentCredentialsProvider
+
+provider = EnvironmentCredentialsProvider("MY_USERNAME", "MY_PASSWORD")
+token_provider = EnvironmentCredentialsProvider.for_token("MY_API_TOKEN")
+```
+
+### OS keychain
+
+Reads credentials stored in the OS keychain via
+[`keyring`](https://pypi.org/project/keyring/). Requires `credchain[keyring]`.
+
+```python
+from credchain.keyring import KeyringCredentialsProvider
+
+provider = KeyringCredentialsProvider("my-service")            # "username" + "password" entries
+provider = KeyringCredentialsProvider.for_token("my-service")  # one "token" entry
+provider = KeyringCredentialsProvider("my-service", timeout=10)
+```
+
+The keychain lookup is bounded by a timeout (default 5 seconds), so a locked
+or unresponsive keychain, e.g. one waiting for an unlock prompt in a headless
+session, cannot hang the caller. On timeout, a warning is logged and
+`(None, None)` is returned, so a chain falls through to its next provider.
+
+### Secret files
+
+Reads one value per file, such as a secret mounted into a container. One
+trailing line break is removed; a missing file means no credentials.
+
+```python
+from credchain import FileCredentialsProvider
+
+provider = FileCredentialsProvider("/run/secrets/username", "/run/secrets/password")
+token_provider = FileCredentialsProvider.for_token("/run/secrets/api-token")
+```
+
+## Logging
+
+Providers log at debug level where they looked and whether they found
+something, never a credential or any part of one: in token mode the token is
+returned in both positions, so even a "username" can be a secret. Errors are
+logged with their exception type only, because messages may quote values.
+
+## API Reference
+
+### `CredentialsProvider`
+
+A `Protocol`: any object with a
+`get_credentials() -> tuple[str | None, str | None]` method satisfies it.
+
+### `CredentialsProviderChain`
+
+`CredentialsProviderChain(providers)` — tries each provider in order and
+returns the first result where both values are non-empty, else
+`(None, None)`.
+
+### `EnvironmentCredentialsProvider`
+
+`EnvironmentCredentialsProvider(username_env_var_name, password_env_var_name)`
+reads two environment variables;
+`EnvironmentCredentialsProvider.for_token(token_env_var_name)` reads one and
+returns it as both elements.
+
+### `KeyringCredentialsProvider`
+
+`KeyringCredentialsProvider(service, username_key="username", password_key="password", timeout=5.0)`
+reads two keychain entries of `service`;
+`KeyringCredentialsProvider.for_token(service, token_key="token", timeout=5.0)`
+reads one. `timeout=None` waits indefinitely. Requires `credchain[keyring]`.
+
+### `FileCredentialsProvider`
+
+`FileCredentialsProvider(username_file, password_file)` reads two files;
+`FileCredentialsProvider.for_token(token_file)` reads one. Errors other than a
+missing file propagate.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

credchain-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+credchain/__init__.py,sha256=FB50Ct0oPjKBB87EPsn9boQ-Bz_MjMiWVz9_7DXtzEw,1330
+credchain/chain.py,sha256=8G1MvqtqLBRyHBF-arLrzmHaWYQGrTwukUEER6rBgec,1535
+credchain/env.py,sha256=-zrHsKsJiYAx9FkbGGVtoS4w1Jh0xsziRdDGqng9DUc,1855
+credchain/file.py,sha256=Q0bigjHBlzrObXfSAokkqP0K-Tr4kJmbJf5kfNrq2Aw,2228
+credchain/keyring.py,sha256=YZBJa2Q1UCo92QDo9cspT42htEVuu-Nz7998xC078H4,4134
+credchain/protocol.py,sha256=QMZ4brqsqjzs5b-jh1BBGcvSbpZzSGBQ5wPXCK628b0,135
+credchain/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+credchain-0.1.0.dist-info/METADATA,sha256=1UH2vueRnffQX2pfB1NobVKMRDa17tGBaSrebdV0HzQ,5492
+credchain-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+credchain-0.1.0.dist-info/licenses/LICENSE,sha256=gj8yMQmXVQ-u8qsZ6UdnofKnIp2wv0tBByT9E-mkpYE,1071
+credchain-0.1.0.dist-info/RECORD,,

credchain-0.1.0.dist-info/WHEEL

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

credchain-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephan Eberle
+
+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.