credential-bridge 0.1.0__py3-none-any.whl

credential_bridge/__init__.py

@@ -0,0 +1,45 @@
+# src/credential_bridge/__init__.py
+from ._version import __version__
+from .backends import BaseSecretBackend, EnvFileBackend, KeyringBackend, VaultBackend
+from .exceptions import (
+    BackendError,
+    BackendNotRegisteredError,
+    ConfigurationError,
+    CredentialBridgeError,
+    EnvFileError,
+    EnvFileKeyExistsError,
+    EnvFileNotFoundError,
+    KeyringError,
+    VaultAuthError,
+    VaultConnectionError,
+    VaultError,
+    VaultSecretNotFoundError,
+)
+from .manager import SecretsManager
+
+# Backwards-compatibility aliases
+VaultManager = VaultBackend
+KeyringManager = KeyringBackend
+
+__all__ = [
+    "__version__",
+    "SecretsManager",
+    "BaseSecretBackend",
+    "VaultBackend",
+    "KeyringBackend",
+    "EnvFileBackend",
+    "CredentialBridgeError",
+    "BackendError",
+    "VaultError",
+    "VaultAuthError",
+    "VaultConnectionError",
+    "VaultSecretNotFoundError",
+    "KeyringError",
+    "EnvFileError",
+    "EnvFileKeyExistsError",
+    "EnvFileNotFoundError",
+    "BackendNotRegisteredError",
+    "ConfigurationError",
+    "VaultManager",
+    "KeyringManager",
+]

credential_bridge/__main__.py

@@ -0,0 +1,3 @@
+from .cli.main import main
+
+main()

credential_bridge/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

credential_bridge/backends/__init__.py

@@ -0,0 +1,7 @@
+# src/credential_bridge/backends/__init__.py
+from .base import BaseSecretBackend
+from .env_file import EnvFileBackend
+from .keyring import KeyringBackend
+from .vault import VaultBackend
+
+__all__ = ["BaseSecretBackend", "EnvFileBackend", "KeyringBackend", "VaultBackend"]

credential_bridge/backends/base.py

@@ -0,0 +1,53 @@
+"""Abstract base class for all secret backends."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List
+
+
+class BaseSecretBackend(ABC):
+    """Contract that every secrets backend must fulfil."""
+
+    backend_name: str = ""
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        # __abstractmethods__ is not yet populated when __init_subclass__ runs,
+        # so we collect abstract method names from the MRO manually.
+        abstract_names = {
+            name
+            for base in cls.__mro__
+            for name, val in vars(base).items()
+            if getattr(val, "__isabstractmethod__", False)
+        }
+        # Only enforce backend_name on concrete (fully-implemented) subclasses
+        overridden = {
+            name
+            for name in abstract_names
+            if name in cls.__dict__ and not getattr(cls.__dict__[name], "__isabstractmethod__", False)
+        }
+        if abstract_names and overridden >= abstract_names:
+            # All abstract methods are implemented — this is a concrete subclass
+            if not cls.backend_name:
+                raise TypeError(
+                    f"{cls.__name__} must define a non-empty 'backend_name' class attribute."
+                )
+
+    @abstractmethod
+    def add_secret(self, name: str, secret: Dict[str, Any]) -> None:
+        """Store a new secret. Creates a new version if the secret already exists (Vault); raises if key already exists (EnvFile)."""
+
+    @abstractmethod
+    def get_secret(self, name: str) -> Dict[str, Any]:
+        """Retrieve a secret by name. Raises if not found."""
+
+    @abstractmethod
+    def update_secret(self, name: str, secret: Dict[str, Any]) -> None:
+        """Update an existing secret. Raises if not found."""
+
+    @abstractmethod
+    def delete_secret(self, name: str) -> None:
+        """Delete a secret. Raises if not found."""
+
+    @abstractmethod
+    def list_secrets(self, path: str = "") -> List[str]:
+        """List secret names, optionally under a path prefix."""

credential_bridge/backends/env_file.py

@@ -0,0 +1,120 @@
+# src/credential_bridge/backends/env_file.py
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+from dotenv import dotenv_values
+
+from ..exceptions import EnvFileError, EnvFileKeyExistsError, EnvFileNotFoundError
+from .base import BaseSecretBackend
+
+
+def _quote_value(value: str) -> str:
+    """Quote a .env value if it contains spaces or special characters."""
+    # Already properly quoted — both open and close with same quote char
+    if len(value) >= 2:
+        if (value[0] == '"' and value[-1] == '"') or \
+           (value[0] == "'" and value[-1] == "'"):
+            return value
+    # Needs quoting if contains spaces or special chars
+    if any(c in value for c in (' ', '\t', '#', '"', "'", '\\', '$', '`')):
+        escaped = value.replace('\\', '\\\\').replace('"', '\\"')
+        return f'"{escaped}"'
+    return value
+
+
+class EnvFileBackend(BaseSecretBackend):
+    """.env file secrets backend with full CRUD and atomic writes."""
+
+    backend_name = "env"
+
+    def __init__(
+        self,
+        path: Union[str, Path] = ".env",
+        load_into_environ: bool = False,
+        encoding: str = "utf-8",
+    ) -> None:
+        self.path = Path(path).resolve()
+        self.load_into_environ = load_into_environ
+        self.encoding = encoding
+
+    def _read_lines(self) -> List[str]:
+        if not self.path.exists():
+            return []
+        return self.path.read_text(encoding=self.encoding).splitlines(keepends=True)
+
+    def _write_lines(self, lines: List[str]) -> None:
+        tmp = self.path.parent / (self.path.name + ".tmp")
+        try:
+            tmp.write_text("".join(lines), encoding=self.encoding)
+            os.replace(str(tmp), str(self.path))
+        except Exception:
+            tmp.unlink(missing_ok=True)
+            raise
+
+    def _current_keys(self) -> Dict[str, str]:
+        return dict(dotenv_values(self.path)) if self.path.exists() else {}
+
+    def _sync_environ(self, keys: Dict[str, str]) -> None:
+        for k, v in keys.items():
+            os.environ[k] = str(v)
+
+    def add_secret(self, name: str, secret: Dict[str, Any]) -> None:
+        existing = self._current_keys()
+        conflicts = [k for k in secret if k in existing]
+        if conflicts:
+            raise EnvFileKeyExistsError(
+                f"Key(s) already exist in {self.path}: {conflicts}. "
+                "Use update_secret() to change them."
+            )
+        lines = self._read_lines()
+        lines.append(f"\n# {name}\n")
+        for k, v in secret.items():
+            lines.append(f"{k}={_quote_value(str(v))}\n")
+        self._write_lines(lines)
+        if self.load_into_environ:
+            self._sync_environ({k: str(v) for k, v in secret.items()})
+
+    def get_secret(self, name: str) -> Dict[str, Any]:
+        keys = self._current_keys()
+        if name not in keys:
+            raise EnvFileNotFoundError(f"Key '{name}' not found in {self.path}.")
+        return {name: keys[name]}
+
+    def update_secret(self, name: str, secret: Dict[str, Any]) -> None:
+        existing = self._current_keys()
+        missing = [k for k in secret if k not in existing]
+        if missing:
+            raise EnvFileError(
+                f"Key(s) {missing} not found in {self.path}. Use add_secret() first."
+            )
+        lines = self._read_lines()
+        updated: Dict[str, str] = {}
+        new_lines = []
+        for line in lines:
+            if "=" in line and not line.strip().startswith("#"):
+                key = line.split("=", 1)[0].strip()
+                if key in secret:
+                    new_lines.append(f"{key}={_quote_value(str(secret[key]))}\n")
+                    updated[key] = str(secret[key])
+                    continue
+            new_lines.append(line)
+        self._write_lines(new_lines)
+        if self.load_into_environ:
+            self._sync_environ(updated)
+
+    def delete_secret(self, name: str) -> None:
+        existing = self._current_keys()
+        if name not in existing:
+            raise EnvFileNotFoundError(f"Key '{name}' not found in {self.path}.")
+        lines = self._read_lines()
+        new_lines = [
+            line for line in lines
+            if not ("=" in line and not line.strip().startswith("#") and line.split("=", 1)[0].strip() == name)
+        ]
+        self._write_lines(new_lines)
+        if self.load_into_environ:
+            os.environ.pop(name, None)
+
+    def list_secrets(self, path: str = "") -> List[str]:
+        return list(self._current_keys().keys())

credential_bridge/backends/keyring.py

@@ -0,0 +1,95 @@
+"""System keyring backend for credential-bridge."""
+
+import json
+from typing import Any, Dict, List, Optional, Union
+
+import keyring
+from keyring.errors import KeyringError as _KeyringLibError
+from pylogshield import LogLevel, PyLogShield, get_logger
+
+from ..exceptions import ConfigurationError, KeyringError
+from .base import BaseSecretBackend
+
+
+class KeyringBackend(BaseSecretBackend):
+    """System keyring backend. Stores dicts as JSON strings."""
+
+    backend_name = "keyring"
+
+    def __init__(
+        self,
+        service_name: str = "default_service",
+        log_level: Union[LogLevel, str] = LogLevel.WARNING,
+        logger: Optional[PyLogShield] = None,
+        mask: bool = True,
+    ) -> None:
+        self.service_name = service_name
+        self.mask = mask
+        if logger and not isinstance(logger, PyLogShield):
+            raise ConfigurationError("logger must be a PyLogShield instance.")
+        self.logger = logger or get_logger(name="credential_bridge", log_level=log_level, force=True)
+
+    def __repr__(self) -> str:
+        return f"KeyringBackend(service_name={self.service_name!r})"
+
+    def add_secret(self, name: str, secret: Dict[str, Any]) -> None:
+        try:
+            existing = keyring.get_password(self.service_name, name)
+            if existing is not None:
+                raise KeyringError(
+                    f"Secret '{name}' already exists in keyring service '{self.service_name}'. "
+                    "Use update_secret() to change it."
+                )
+            keyring.set_password(self.service_name, name, json.dumps(secret))
+            self.logger.info(f"Keyring secret added: {name}", mask=self.mask)
+        except KeyringError:
+            raise
+        except _KeyringLibError as e:
+            raise KeyringError(f"Failed to add '{name}': {e}") from e
+
+    def get_secret(self, name: str) -> Dict[str, Any]:
+        try:
+            value = keyring.get_password(self.service_name, name)
+            if value is None:
+                raise KeyringError(
+                    f"Secret '{name}' not found in keyring service '{self.service_name}'."
+                )
+            return json.loads(value)
+        except KeyringError:
+            raise
+        except _KeyringLibError as e:
+            raise KeyringError(f"Failed to get '{name}': {e}") from e
+
+    def update_secret(self, name: str, secret: Dict[str, Any]) -> None:
+        try:
+            existing = keyring.get_password(self.service_name, name)
+            if existing is None:
+                raise KeyringError(
+                    f"Secret '{name}' does not exist — use add_secret() first."
+                )
+            keyring.set_password(self.service_name, name, json.dumps(secret))
+            self.logger.info(f"Keyring secret updated: {name}", mask=self.mask)
+        except KeyringError:
+            raise
+        except _KeyringLibError as e:
+            raise KeyringError(f"Failed to update '{name}': {e}") from e
+
+    def delete_secret(self, name: str) -> None:
+        try:
+            existing = keyring.get_password(self.service_name, name)
+            if existing is None:
+                raise KeyringError(
+                    f"Secret '{name}' not found in keyring service '{self.service_name}'."
+                )
+            keyring.delete_password(self.service_name, name)
+            self.logger.info(f"Keyring secret deleted: {name}")
+        except KeyringError:
+            raise
+        except _KeyringLibError as e:
+            raise KeyringError(f"Failed to delete '{name}': {e}") from e
+
+    def list_secrets(self, path: str = "") -> List[str]:
+        raise KeyringError(
+            "KeyringBackend.list_secrets() is not supported on this platform. "
+            "Windows Credential Manager and macOS Keychain do not expose enumeration APIs."
+        )

credential_bridge/backends/vault.py

@@ -0,0 +1,315 @@
+"""HashiCorp Vault backend for credential-bridge."""
+
+import os
+from typing import Any, Dict, List, Optional, Union
+
+import hvac
+import requests
+from pylogshield import LogLevel, PyLogShield, get_logger
+
+from credential_bridge.backends.base import BaseSecretBackend
+from credential_bridge.exceptions import (
+    ConfigurationError,
+    VaultAuthError,
+    VaultConnectionError,
+    VaultError,
+    VaultSecretNotFoundError,
+)
+from credential_bridge.utils import get_session, load_config, save_config
+
+
+class VaultBackend(BaseSecretBackend):
+    """HashiCorp Vault KV-v2 secret backend."""
+
+    backend_name: str = "vault"
+
+    def __init__(
+        self,
+        vault_url: Optional[str] = None,
+        vault_token: Optional[str] = None,
+        vault_role_id: Optional[str] = None,
+        vault_secret_id: Optional[str] = None,
+        service_name: str = "default_service",
+        mount_point: str = "secret",
+        proxies: Optional[Dict[str, str]] = None,
+        cert: Optional[str] = None,
+        log_level: Union[LogLevel, str] = LogLevel.WARNING,
+        logger: Optional[PyLogShield] = None,
+        mask: bool = True,
+        persist: bool = False,   # opt-in credential persistence to ~/.vault_config.json
+    ) -> None:
+        self.mask = mask
+        self.service_name = service_name
+        self.mount_point = mount_point
+        self.cert = cert  # None means use system CA bundle; path string means custom cert
+        self.proxies = proxies
+
+        if logger and not isinstance(logger, PyLogShield):
+            raise ConfigurationError(
+                "logger must be a PyLogShield instance. "
+                "Use: from pylogshield import PyLogShield"
+            )
+        self.logger = logger or get_logger(name="credential_bridge", log_level=log_level, force=True)
+
+        self.session = get_session(cert, proxies)
+
+        config = load_config()
+
+        # --- Resolve vault address ---
+        if vault_url:
+            self.vault_addr = vault_url
+        else:
+            self.vault_addr = os.environ.get("VAULT_ADDR") or config.get("vault_addr")
+
+        if not self.vault_addr:
+            raise ConfigurationError(
+                "Vault address must be provided via the vault_url argument, "
+                "the VAULT_ADDR environment variable, or ~/.vault_config.json"
+            )
+
+        # --- Resolve credentials (args override config) ---
+        self.vault_token = vault_token or config.get("vault_token")
+        self.vault_role_id = vault_role_id or config.get("vault_role_id")
+        self.vault_secret_id = vault_secret_id or config.get("vault_secret_id")
+
+        # Token and AppRole are mutually exclusive
+        if self.vault_token and (self.vault_role_id or self.vault_secret_id):
+            raise ConfigurationError(
+                "Provide either a Vault token or AppRole credentials, not both."
+            )
+
+        # At least one auth method must be present
+        if not self.vault_token and not (self.vault_role_id and self.vault_secret_id):
+            raise ConfigurationError(
+                "No authentication method provided. Please provide either a token "
+                "or AppRole credentials."
+            )
+
+        # --- Persist credentials to config (opt-in) ---
+        if persist:
+            if vault_token:
+                config["vault_token"] = vault_token
+                config["vault_role_id"] = None
+                config["vault_secret_id"] = None
+            elif vault_role_id and vault_secret_id:
+                config["vault_role_id"] = vault_role_id
+                config["vault_secret_id"] = vault_secret_id
+                config["vault_token"] = None
+
+            if vault_url:
+                config["vault_addr"] = vault_url
+
+            save_config(config)
+
+        self.client = self._authenticate()
+
+    # ------------------------------------------------------------------
+    # Authentication
+    # ------------------------------------------------------------------
+
+    def _authenticate(self) -> hvac.Client:
+        """Authenticate with Vault using a token or AppRole credentials."""
+        self.logger.info("Authenticating with Vault...")
+        try:
+            if self.vault_token:
+                client = hvac.Client(
+                    url=self.vault_addr,
+                    token=self.vault_token,
+                    session=self.session,
+                    verify=self.cert,
+                )
+                if not client.is_authenticated():
+                    raise VaultAuthError(
+                        "Failed to authenticate with Vault using token."
+                    )
+                self.logger.info("Authenticated with Vault via token.")
+                return client
+
+            # AppRole
+            client = hvac.Client(
+                url=self.vault_addr,
+                session=self.session,
+                verify=self.cert,
+            )
+            auth_response = client.auth.approle.login(
+                role_id=self.vault_role_id,
+                secret_id=self.vault_secret_id,
+            )
+            if "auth" not in auth_response or "client_token" not in auth_response["auth"]:
+                raise VaultAuthError(
+                    "Failed to authenticate with Vault using AppRole."
+                )
+            client.token = auth_response["auth"]["client_token"]
+            self.logger.info("Authenticated with Vault via AppRole.")
+            return client
+
+        except VaultAuthError:
+            raise
+        except VaultConnectionError:
+            raise
+        except hvac.exceptions.Forbidden as exc:
+            raise VaultAuthError(f"Forbidden: {exc}") from exc
+        except hvac.exceptions.InvalidRequest as exc:
+            raise VaultAuthError(f"Invalid request: {exc}") from exc
+        except (hvac.exceptions.VaultDown, requests.ConnectionError, requests.Timeout) as exc:
+            raise VaultConnectionError(f"Cannot connect to Vault at {self.vault_addr}: {exc}") from exc
+        except (ConnectionError, OSError) as exc:
+            raise VaultConnectionError(f"Cannot reach Vault at {self.vault_addr}: {exc}") from exc
+        except Exception as exc:
+            raise VaultError(f"Vault authentication error: {exc}") from exc
+
+    def _refresh_token_if_needed(self) -> None:
+        """Renew the Vault token if its TTL is below 5 minutes."""
+        try:
+            resp = self.client.auth.token.lookup_self()
+            if resp["data"]["ttl"] < 300:
+                self.client.auth.token.renew_self()
+                self.logger.info("Vault token refreshed.")
+        except hvac.exceptions.Forbidden as e:
+            raise VaultAuthError(f"Vault token is invalid or has expired: {e}") from e
+        except Exception as e:
+            self.logger.warning(f"Token refresh check failed (will retry on next operation): {e}")
+
+    # ------------------------------------------------------------------
+    # BaseSecretBackend interface
+    # ------------------------------------------------------------------
+
+    def add_secret(self, name: str, secret: Dict[str, Any]) -> None:
+        """Add or update a secret in Vault (creates a new KV-v2 version)."""
+        self._refresh_token_if_needed()
+        try:
+            self.client.secrets.kv.v2.create_or_update_secret(
+                path=name,
+                secret=secret,
+                mount_point=self.mount_point,
+            )
+            self.logger.info(f"Secret added: {name}")
+        except Exception as exc:
+            raise VaultError(f"Failed to add secret '{name}': {exc}") from exc
+
+    def get_secret(self, name: str) -> Dict[str, Any]:
+        """Retrieve a secret by *name*."""
+        self._refresh_token_if_needed()
+        try:
+            response = self.client.secrets.kv.v2.read_secret(
+                path=name,
+                mount_point=self.mount_point,
+            )
+            return response["data"]["data"]
+        except hvac.exceptions.InvalidPath as e:
+            raise VaultSecretNotFoundError(f"Secret path '{name}' does not exist: {e}") from e
+        except Exception as exc:
+            raise VaultError(f"Failed to get secret '{name}': {exc}") from exc
+
+    def update_secret(self, name: str, secret: Dict[str, Any]) -> None:
+        """Update an existing secret."""
+        self._refresh_token_if_needed()
+        try:
+            self.client.secrets.kv.v2.patch(
+                path=name,
+                secret=secret,
+                mount_point=self.mount_point,
+            )
+            self.logger.info(f"Secret updated: {name}")
+        except hvac.exceptions.InvalidPath as e:
+            raise VaultSecretNotFoundError(f"Secret path '{name}' does not exist: {e}") from e
+        except Exception as exc:
+            raise VaultError(f"Failed to update secret '{name}': {exc}") from exc
+
+    def delete_secret(self, name: str) -> None:
+        """Permanently delete a secret and all its versions."""
+        self._refresh_token_if_needed()
+        try:
+            self.client.secrets.kv.v2.delete_metadata_and_all_versions(
+                path=name,
+                mount_point=self.mount_point,
+            )
+            self.logger.info(f"Secret deleted: {name}")
+        except hvac.exceptions.InvalidPath as e:
+            raise VaultSecretNotFoundError(f"Secret path '{name}' does not exist: {e}") from e
+        except Exception as exc:
+            raise VaultError(f"Failed to delete secret '{name}': {exc}") from exc
+
+    def list_secrets(self, path: str = "") -> List[str]:
+        """List secret keys under *path*."""
+        self._refresh_token_if_needed()
+        try:
+            response = self.client.secrets.kv.v2.list_secrets(
+                path=path,
+                mount_point=self.mount_point,
+            )
+            return response["data"]["keys"]
+        except Exception as exc:
+            raise VaultError(f"Failed to list secrets at '{path}': {exc}") from exc
+
+    # ------------------------------------------------------------------
+    # Extra helpers
+    # ------------------------------------------------------------------
+
+    def get_config(self) -> Optional[Dict[str, Any]]:
+        """Return the KV engine configuration for the current mount point."""
+        self._refresh_token_if_needed()
+        try:
+            return self.client.secrets.kv.v2.read_configuration(
+                mount_point=self.mount_point
+            )
+        except Exception as exc:
+            raise VaultError(
+                f"Failed to read config for mount '{self.mount_point}': {exc}"
+            ) from exc
+
+    def read_secret_metadata(self, name: str) -> Optional[Dict[str, Any]]:
+        """Return metadata and version info for *name*."""
+        self._refresh_token_if_needed()
+        try:
+            return self.client.secrets.kv.v2.read_secret_metadata(
+                path=name,
+                mount_point=self.mount_point,
+            )
+        except Exception as exc:
+            raise VaultError(f"Failed to read metadata for '{name}': {exc}") from exc
+
+    def delete_secret_versions(self, name: str, versions: List[int]) -> None:
+        """Soft-delete specific versions of *name*."""
+        self._refresh_token_if_needed()
+        try:
+            self.client.secrets.kv.v2.delete_secret_versions(
+                path=name,
+                versions=versions,
+                mount_point=self.mount_point,
+            )
+            self.logger.info(f"Soft-deleted versions {versions} of '{name}'.")
+        except Exception as exc:
+            raise VaultError(
+                f"Failed to delete versions {versions} of '{name}': {exc}"
+            ) from exc
+
+    def undelete_secret_versions(self, name: str, versions: List[int]) -> None:
+        """Restore soft-deleted versions of *name*."""
+        self._refresh_token_if_needed()
+        try:
+            self.client.secrets.kv.v2.undelete_secret_versions(
+                path=name,
+                versions=versions,
+                mount_point=self.mount_point,
+            )
+            self.logger.info(f"Undeleted versions {versions} of '{name}'.")
+        except Exception as exc:
+            raise VaultError(
+                f"Failed to undelete versions {versions} of '{name}': {exc}"
+            ) from exc
+
+    def destroy_secret_versions(self, name: str, versions: List[int]) -> None:
+        """Permanently destroy specific versions of *name*."""
+        self._refresh_token_if_needed()
+        try:
+            self.client.secrets.kv.v2.destroy_secret_versions(
+                path=name,
+                versions=versions,
+                mount_point=self.mount_point,
+            )
+            self.logger.info(f"Destroyed versions {versions} of '{name}'.")
+        except Exception as exc:
+            raise VaultError(
+                f"Failed to destroy versions {versions} of '{name}': {exc}"
+            ) from exc

credential_bridge/cli/__main__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+main()