vaultriever 0.1.0__py3-none-any.whl

vaultriever/__init__.py

@@ -0,0 +1,33 @@
+"""vaultriever: retrieve secrets in an ARN-like way from different vaults.
+
+Secrets are addressed with a Secret Resource Identifier (SRI)::
+
+    provider:region:secret_name:secret_key
+"""
+
+from vaultriever.exceptions import (
+    DatabricksConfigurationError,
+    ProviderNotRegisteredError,
+    SecretRetrievalError,
+    SRIParseError,
+    VaultrieverError,
+)
+from vaultriever.providers import SecretProvider, SecretProviderRegistry
+from vaultriever.resolver import resolve_secret
+from vaultriever.settings_mixin import SecretSRIMixin
+from vaultriever.sri import SecretProperties, is_sri, parse_sri
+
+__all__ = [
+    'DatabricksConfigurationError',
+    'ProviderNotRegisteredError',
+    'SecretProperties',
+    'SecretProvider',
+    'SecretProviderRegistry',
+    'SecretRetrievalError',
+    'SecretSRIMixin',
+    'SRIParseError',
+    'VaultrieverError',
+    'is_sri',
+    'parse_sri',
+    'resolve_secret',
+]

vaultriever/exceptions.py

@@ -0,0 +1,27 @@
+"""Package-specific exceptions.
+
+Error messages must never contain secret values. Including the SRI's
+secret_name/region is fine; the resolved value is not.
+"""
+
+from __future__ import annotations
+
+
+class VaultrieverError(Exception):
+    """Base class for all vaultriever errors."""
+
+
+class SRIParseError(VaultrieverError, ValueError):
+    """Raised when a string is not a valid Secret Resource Identifier."""
+
+
+class ProviderNotRegisteredError(VaultrieverError, LookupError):
+    """Raised when an SRI references a provider that is not registered."""
+
+
+class SecretRetrievalError(VaultrieverError):
+    """Raised when a provider fails to retrieve or decode a secret."""
+
+
+class DatabricksConfigurationError(SecretRetrievalError):
+    """Raised when the Databricks provider cannot build a usable context."""

vaultriever/logging.py

@@ -0,0 +1,16 @@
+"""Logger helper.
+
+All modules obtain their logger through :func:`get_logger` so the package
+shares a single ``vaultriever`` namespace and users can configure it once.
+"""
+
+from __future__ import annotations
+
+import logging
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a logger under the ``vaultriever`` namespace."""
+    if name == 'vaultriever' or name.startswith('vaultriever.'):
+        return logging.getLogger(name)
+    return logging.getLogger(f'vaultriever.{name}')

vaultriever/providers/__init__.py

@@ -0,0 +1,22 @@
+"""Secret providers and their registry.
+
+Default providers are registered at import time. Provider SDK dependencies
+(boto3, databricks-sdk) are imported lazily on first use, so registration is
+safe even when the corresponding extra is not installed.
+"""
+
+from __future__ import annotations
+
+from vaultriever.providers.aws import AWSSecretProvider
+from vaultriever.providers.base import SecretProvider, SecretProviderRegistry
+from vaultriever.providers.databricks import DatabricksSecretProvider
+
+SecretProviderRegistry.register(AWSSecretProvider())
+SecretProviderRegistry.register(DatabricksSecretProvider())
+
+__all__ = [
+    'AWSSecretProvider',
+    'DatabricksSecretProvider',
+    'SecretProvider',
+    'SecretProviderRegistry',
+]

vaultriever/providers/aws.py

@@ -0,0 +1,79 @@
+"""AWS Secrets Manager provider.
+
+SRI semantics: ``aws:<region>:<secret_name>:<json_key>``. The secret's
+``SecretString`` must be a JSON object; ``json_key`` selects one of its keys.
+Credentials are resolved by the AWS SDK default chain (env vars, profile,
+IAM role).
+
+Requires the ``aws`` extra: ``pip install vaultriever[aws]``.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from typing import Any
+
+from vaultriever.exceptions import SecretRetrievalError
+from vaultriever.logging import get_logger
+from vaultriever.sri import SecretProperties
+
+logger = get_logger(__name__)
+
+
+@lru_cache
+def _get_aws_secret_json(secret_name: str, region_name: str) -> dict[str, Any]:
+    """Fetch and decode a JSON secret, caching by (secret_name, region)."""
+    try:
+        import boto3
+    except ImportError as exc:  # pragma: no cover - depends on install extras
+        raise SecretRetrievalError(
+            "boto3 is required for the 'aws' provider. Install with: pip install vaultriever[aws]"
+        ) from exc
+
+    logger.debug('Fetching AWS secret %r in region %r', secret_name, region_name)
+    client = boto3.Session().client('secretsmanager', region_name=region_name)
+    try:
+        response = client.get_secret_value(SecretId=secret_name)
+    except Exception as exc:
+        raise SecretRetrievalError(
+            f'Failed to retrieve AWS secret {secret_name!r} in region {region_name!r}: '
+            f'{type(exc).__name__}'
+        ) from exc
+
+    secret_string = response.get('SecretString')
+    if secret_string is None:
+        raise SecretRetrievalError(
+            f'AWS secret {secret_name!r} has no SecretString (binary secrets are not supported)'
+        )
+    try:
+        data = json.loads(secret_string)
+    except json.JSONDecodeError as exc:
+        raise SecretRetrievalError(f'AWS secret {secret_name!r} is not valid JSON') from exc
+    if not isinstance(data, dict):
+        raise SecretRetrievalError(f'AWS secret {secret_name!r} is not a JSON object')
+    return data
+
+
+class AWSSecretProvider:
+    """Retrieve keys from JSON secrets stored in AWS Secrets Manager."""
+
+    name = 'aws'
+
+    def get_secret_value(self, props: SecretProperties) -> Any:
+        if not props.region:
+            raise SecretRetrievalError(
+                "AWS SRIs require a non-empty region, e.g. 'aws:us-east-1:my-secret:MY_KEY'"
+            )
+        data = _get_aws_secret_json(props.secret_name, props.region)
+        try:
+            return data[props.secret_key]
+        except KeyError:
+            raise SecretRetrievalError(
+                f'Key {props.secret_key!r} not found in AWS secret {props.secret_name!r}'
+            ) from None
+
+    @staticmethod
+    def clear_cache() -> None:
+        """Clear the cached secret payloads (e.g. after rotation)."""
+        _get_aws_secret_json.cache_clear()

vaultriever/providers/azure.py

@@ -0,0 +1,19 @@
+"""Azure Key Vault provider (stub).
+
+Intended SRI semantics: ``azure:<vault_or_region>:<secret_name>:<key_or_version>``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from vaultriever.sri import SecretProperties
+
+
+class AzureSecretProvider:
+    """Placeholder provider; not implemented yet."""
+
+    name = 'azure'
+
+    def get_secret_value(self, props: SecretProperties) -> Any:
+        raise NotImplementedError('Azure provider not implemented yet.')

vaultriever/providers/base.py

@@ -0,0 +1,60 @@
+"""Provider interface and registry."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from vaultriever.exceptions import ProviderNotRegisteredError
+from vaultriever.logging import get_logger
+from vaultriever.sri import SecretProperties
+
+logger = get_logger(__name__)
+
+
+@runtime_checkable
+class SecretProvider(Protocol):
+    """Minimal interface every secret provider must implement."""
+
+    name: str  # e.g. "aws", "databricks"
+
+    def get_secret_value(self, props: SecretProperties) -> Any: ...
+
+
+class SecretProviderRegistry:
+    """Registry of available secret providers, keyed by provider name."""
+
+    _providers: dict[str, SecretProvider] = {}
+
+    @classmethod
+    def register(cls, provider: SecretProvider) -> None:
+        """Register a provider under its ``name``, replacing any existing one."""
+        logger.debug('Registering secret provider %r', provider.name)
+        cls._providers[provider.name] = provider
+
+    @classmethod
+    def get(cls, name: str) -> SecretProvider:
+        """Return the provider registered under ``name``.
+
+        Raises:
+            ProviderNotRegisteredError: If no provider is registered.
+        """
+        try:
+            return cls._providers[name]
+        except KeyError:
+            raise ProviderNotRegisteredError(
+                f'No secret provider registered for {name!r}. '
+                f'Available providers: {cls.available_providers()}'
+            ) from None
+
+    @classmethod
+    def unregister(cls, name: str) -> None:
+        """Remove a provider from the registry; no-op if not registered."""
+        cls._providers.pop(name, None)
+
+    @classmethod
+    def is_registered(cls, name: str) -> bool:
+        return name in cls._providers
+
+    @classmethod
+    def available_providers(cls) -> list[str]:
+        return sorted(cls._providers)

vaultriever/providers/databricks.py

@@ -0,0 +1,95 @@
+"""Databricks secrets provider.
+
+SRI semantics: ``databricks:<profile>:<scope>:<key>``.
+
+- Empty region (``databricks::my-scope:MY_KEY``) -> default workspace: the
+    runtime ``dbutils`` when running on Databricks, otherwise the SDK's default
+    authentication.
+- Non-empty region -> used as the Databricks CLI profile name, e.g.
+  ``databricks:staging:my-scope:MY_KEY`` reads via the ``staging`` profile.
+
+Requires the ``databricks`` extra outside a Databricks runtime:
+``pip install vaultriever[databricks]``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from vaultriever.exceptions import DatabricksConfigurationError, SecretRetrievalError
+from vaultriever.logging import get_logger
+from vaultriever.sri import SecretProperties
+
+logger = get_logger(__name__)
+
+
+@dataclass(frozen=True)
+class DatabricksContext:
+    """Where to read Databricks secrets from. ``profile=None`` means default."""
+
+    profile: str | None
+
+
+def resolve_databricks_context(region: str | None) -> DatabricksContext:
+    """Map the SRI region component to a Databricks context.
+
+    An empty/None region selects the default workspace; anything else is
+    interpreted as a Databricks CLI profile name.
+    """
+    if not region:
+        return DatabricksContext(profile=None)
+    return DatabricksContext(profile=region)
+
+
+def _get_secret(context: DatabricksContext, scope: str, key: str) -> str:
+    """Fetch a secret for the given context. Split out so tests can patch it."""
+    if context.profile is None:
+        # On a Databricks runtime this is the native dbutils; elsewhere the
+        # SDK falls back to default authentication.
+        try:
+            from databricks.sdk.runtime import dbutils
+
+            return str(dbutils.secrets.get(scope=scope, key=key))
+        except ImportError:
+            try:
+                from databricks.sdk import WorkspaceClient
+            except ImportError as import_exc:
+                raise DatabricksConfigurationError(
+                    "databricks-sdk is required for the 'databricks' provider. "
+                    'Install with: pip install vaultriever[databricks]'
+                ) from import_exc
+
+            client = WorkspaceClient()
+            return str(client.dbutils.secrets.get(scope=scope, key=key))
+
+    try:
+        from databricks.sdk import WorkspaceClient
+    except ImportError as exc:
+        raise DatabricksConfigurationError(
+            "databricks-sdk is required for the 'databricks' provider. "
+            'Install with: pip install vaultriever[databricks]'
+        ) from exc
+    client = WorkspaceClient(profile=context.profile)
+    return str(client.dbutils.secrets.get(scope=scope, key=key))
+
+
+class DatabricksSecretProvider:
+    """Retrieve secrets from Databricks secret scopes."""
+
+    name = 'databricks'
+
+    def get_secret_value(self, props: SecretProperties) -> Any:
+        context = resolve_databricks_context(props.region)
+        logger.debug(
+            'Fetching Databricks secret scope=%r profile=%r', props.secret_name, context.profile
+        )
+        try:
+            return _get_secret(context, props.secret_name, props.secret_key)
+        except SecretRetrievalError:
+            raise
+        except Exception as exc:
+            raise SecretRetrievalError(
+                f'Failed to retrieve Databricks secret scope={props.secret_name!r} '
+                f'key={props.secret_key!r}: {type(exc).__name__}'
+            ) from exc

vaultriever/providers/gcp.py

@@ -0,0 +1,19 @@
+"""GCP Secret Manager provider (stub).
+
+Intended SRI semantics: ``gcp:<project_or_region>:<secret_name>:<key_or_version>``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from vaultriever.sri import SecretProperties
+
+
+class GCPSecretProvider:
+    """Placeholder provider; not implemented yet."""
+
+    name = 'gcp'
+
+    def get_secret_value(self, props: SecretProperties) -> Any:
+        raise NotImplementedError('GCP provider not implemented yet.')

vaultriever/resolver.py

@@ -0,0 +1,30 @@
+"""Secret resolution: parse an SRI and dispatch to the right provider."""
+
+from __future__ import annotations
+
+from vaultriever.logging import get_logger
+from vaultriever.providers import SecretProviderRegistry
+from vaultriever.sri import parse_sri
+
+logger = get_logger(__name__)
+
+
+def resolve_secret(secret_sri: str) -> str:
+    """Resolve an SRI string to its secret value.
+
+    Raises:
+        SRIParseError: If the SRI is malformed.
+        ProviderNotRegisteredError: If the provider is unknown.
+        SecretRetrievalError: If the provider fails to retrieve the secret.
+    """
+    props = parse_sri(secret_sri)
+    provider = SecretProviderRegistry.get(props.provider)
+    logger.debug(
+        'Resolving secret via provider=%r region=%r secret_name=%r',
+        props.provider,
+        props.region,
+        props.secret_name,
+    )
+    value = provider.get_secret_value(props)
+    # Always return a string so callers can wrap it in SecretStr.
+    return str(value)

vaultriever/settings_mixin.py

@@ -0,0 +1,82 @@
+"""Pydantic-settings integration.
+
+:class:`SecretSRIMixin` adds a wildcard ``mode='before'`` validator that
+detects SRI strings in ``str``/``SecretStr`` fields and replaces them with the
+resolved secret wrapped in ``SecretStr``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, ClassVar
+
+from pydantic import SecretStr, ValidationInfo, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from vaultriever.logging import get_logger
+from vaultriever.providers import SecretProviderRegistry
+from vaultriever.resolver import resolve_secret
+from vaultriever.sri import is_sri
+
+logger = get_logger(__name__)
+
+
+class SecretSRIMixin(BaseSettings):
+    """Base/mixin for ``BaseSettings`` models that resolves SRI values.
+
+    It extends ``BaseSettings`` (which keeps type checkers happy about
+    ``model_config``), so both forms work::
+
+        class MySettings(SecretSRIMixin):
+            api_key: str | SecretStr = 'aws:us-east-1:my-secret:API_KEY'
+
+        class MySettings(SecretSRIMixin, BaseSettings):
+            api_key: str | SecretStr = 'aws:us-east-1:my-secret:API_KEY'
+
+    Behavior:
+    - ``str``/``SecretStr`` values that look like an SRI *and* reference a
+      registered provider are resolved and returned as ``SecretStr``.
+    - All other values pass through unchanged.
+    - When ``enable_env_export`` is True (the default), validated values are
+      also written to ``os.environ`` under the field name. Note that this
+      writes resolved secrets in **plaintext** to the process environment;
+      set ``enable_env_export: ClassVar[bool] = False`` on your subclass to
+      opt out (the ``ClassVar`` annotation keeps pydantic from treating it as
+      a field).
+    """
+
+    # Ensures SRI strings used as field defaults are also resolved.
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(validate_default=True)
+
+    enable_env_export: ClassVar[bool] = True
+
+    @field_validator('*', mode='before')
+    @classmethod
+    def resolve_sri(cls, value: Any, info: ValidationInfo) -> Any:
+        if isinstance(value, SecretStr):
+            raw = value.get_secret_value()
+        elif isinstance(value, str):
+            raw = value
+        else:
+            return value
+
+        # Only treat the value as an SRI if its provider is registered, so
+        # colon-heavy strings such as connection URLs pass through untouched.
+        if is_sri(raw) and SecretProviderRegistry.is_registered(raw.split(':', 1)[0]):
+            logger.debug('Resolving SRI for field %r', info.field_name)
+            secret = SecretStr(resolve_secret(raw))
+            cls._export_to_env(info.field_name, secret.get_secret_value())
+            return secret
+
+        cls._export_to_env(info.field_name, raw)
+        return value
+
+    @classmethod
+    def _export_to_env(cls, field_name: str | None, value: Any) -> None:
+        if not cls.enable_env_export or not field_name:
+            return
+        if isinstance(value, dict | list):
+            os.environ[field_name] = json.dumps(value)
+        else:
+            os.environ[field_name] = str(value)

vaultriever/sri.py

@@ -0,0 +1,92 @@
+"""Secret Resource Identifier (SRI) parsing and validation.
+
+Canonical format::
+
+    provider:region:secret_name:secret_key
+
+Examples:
+    - ``aws:us-east-1:my-secret:OPENAI_API_KEY``
+    - ``databricks::my-secret-scope:OPENAI_API_KEY`` (empty region -> default
+      profile/workspace)
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from vaultriever.exceptions import SRIParseError
+
+SRI_PARTS = 4
+_PROVIDER_RE = re.compile(r'^[a-z][a-z0-9_-]*$')
+# Regions/profiles are identifier-like. Keeping this strict prevents strings
+# such as 'postgresql://user:pass@host:5432/db' from being detected as SRIs.
+_REGION_RE = re.compile(r'^[A-Za-z0-9._-]*$')
+
+_FORMAT_HINT = "Expected 'provider:region:secret_name:secret_key'"
+
+
+@dataclass(frozen=True)
+class SecretProperties:
+    """Parsed components of an SRI string."""
+
+    provider: str
+    region: str | None
+    secret_name: str
+    secret_key: str
+
+
+def is_sri(value: str) -> bool:
+    """Return True if ``value`` is structurally a valid SRI.
+
+    The check requires exactly 4 colon-separated parts, a lowercase provider
+    name, and non-empty secret_name/secret_key. Only the region may be empty.
+    This is a structural check only; it does not verify that the provider is
+    registered or that the secret exists.
+    """
+    if not isinstance(value, str):
+        return False
+    parts = value.split(':')
+    if len(parts) != SRI_PARTS:
+        return False
+    provider, region, secret_name, secret_key = parts
+    return (
+        bool(_PROVIDER_RE.match(provider))
+        and bool(_REGION_RE.match(region))
+        and bool(secret_name)
+        and bool(secret_key)
+    )
+
+
+def parse_sri(value: str) -> SecretProperties:
+    """Parse an SRI string into :class:`SecretProperties`.
+
+    Raises:
+        SRIParseError: If the string is malformed. The message never includes
+            the full input to avoid leaking values that only look like SRIs.
+    """
+    parts = value.split(':')
+    if len(parts) != SRI_PARTS:
+        raise SRIParseError(f'Malformed SRI with {len(parts)} part(s). {_FORMAT_HINT}')
+
+    provider, region, secret_name, secret_key = parts
+    if not _PROVIDER_RE.match(provider):
+        raise SRIParseError(
+            f'Invalid SRI provider {provider!r}: must be a non-empty lowercase name. {_FORMAT_HINT}'
+        )
+    if not _REGION_RE.match(region):
+        raise SRIParseError(
+            f'Invalid SRI region {region!r}: only letters, digits, ".", "_" and "-" '
+            f'are allowed. {_FORMAT_HINT}'
+        )
+    if not secret_name:
+        raise SRIParseError(f'SRI secret_name must be non-empty. {_FORMAT_HINT}')
+    if not secret_key:
+        raise SRIParseError(f'SRI secret_key must be non-empty. {_FORMAT_HINT}')
+
+    return SecretProperties(
+        provider=provider,
+        region=region or None,
+        secret_name=secret_name,
+        secret_key=secret_key,
+    )

vaultriever-0.1.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: vaultriever
+Version: 0.1.0
+Summary: Retrieve secrets in an ARN-like way from different vaults seamlessly, compatible with pydantic-settings.
+Project-URL: Homepage, https://github.com/DougTrajano/vaultriever
+Project-URL: Repository, https://github.com/DougTrajano/vaultriever
+Project-URL: Issues, https://github.com/DougTrajano/vaultriever/issues
+Author: Douglas Trajano
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aws,databricks,pydantic,pydantic-settings,secrets,vault
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: aws
+Requires-Dist: boto3>=1.26.0; extra == 'aws'
+Provides-Extra: databricks
+Requires-Dist: databricks-sdk>=0.20.0; extra == 'databricks'
+Provides-Extra: docs
+Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2.0; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# vaultriever
+
+Retrieve secrets in an ARN-like way from different vaults seamlessly, compatible with [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) — no custom field types, just `str` fields plus a reusable mixin.
+
+## Secret Resource Identifier (SRI)
+
+Secrets are addressed with a 4-part string:
+
+```
+provider:region:secret_name:secret_key
+```
+
+| Provider | Example | Notes |
+| --- | --- | --- |
+| AWS Secrets Manager | `aws:us-east-1:my-secret:OPENAI_API_KEY` | Secret must be a JSON object; `secret_key` selects a key. |
+| Databricks | `databricks::my-secret-scope:OPENAI_API_KEY` | Empty region → default workspace/profile; non-empty region → CLI profile name. |
+| Azure Key Vault | `azure:<vault_or_region>:<secret_name>:<key_or_version>` | Planned. |
+| GCP Secret Manager | `gcp:<project_or_region>:<secret_name>:<key_or_version>` | Planned. |
+
+## Installation
+
+```bash
+pip install vaultriever[aws]         # AWS Secrets Manager
+pip install vaultriever[databricks]  # Databricks (not needed on a Databricks runtime)
+```
+
+## Usage
+
+### With pydantic-settings
+
+```python
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings
+from vaultriever import SecretSRIMixin
+
+
+class OpenAISettings(SecretSRIMixin, BaseSettings):
+    openai_api_key: str | SecretStr = Field(
+        default='aws:us-east-1:my-secret:OPENAI_API_KEY',
+        description='OpenAI API key; SRI or literal.',
+    )
+
+
+settings = OpenAISettings()
+settings.openai_api_key                     # SecretStr('**********') — masked
+settings.openai_api_key.get_secret_value()  # the resolved secret
+```
+
+Behavior:
+
+- `str` / `SecretStr` values that look like an SRI (and reference a registered provider) are resolved and wrapped in `SecretStr`, so they stay masked in `repr()` and logs.
+- Everything else passes through unchanged — literals, URLs, non-string values.
+- Validated values are also exported to `os.environ` under the field name for downstream usage. **This writes resolved secrets in plaintext to the process environment**; opt out per model:
+
+```python
+from typing import ClassVar
+
+
+class MySettings(SecretSRIMixin, BaseSettings):
+    enable_env_export: ClassVar[bool] = False
+
+    api_key: str | SecretStr
+```
+
+### Standalone
+
+```python
+from vaultriever import is_sri, resolve_secret
+
+is_sri('aws:us-east-1:my-secret:API_KEY')          # True
+resolve_secret('aws:us-east-1:my-secret:API_KEY')  # 'sk-...'
+```
+
+### Custom providers
+
+```python
+from vaultriever import SecretProviderRegistry
+from vaultriever.sri import SecretProperties
+
+
+class MyVaultProvider:
+    name = 'myvault'
+
+    def get_secret_value(self, props: SecretProperties) -> str:
+        ...
+
+
+SecretProviderRegistry.register(MyVaultProvider())
+# Now 'myvault:region:name:key' SRIs resolve through it.
+```
+
+## Providers
+
+### AWS Secrets Manager
+
+- Credentials come from the AWS SDK default chain (env vars, profile, IAM role).
+- The region is required and taken from the SRI.
+- Secret payloads are cached per `(secret_name, region)` for the process lifetime; call `AWSSecretProvider.clear_cache()` after a rotation.
+
+### Databricks
+
+- On a Databricks runtime, secrets are read via the native `dbutils`.
+- Elsewhere, the [databricks-sdk](https://github.com/databricks/databricks-sdk-py) is used with default authentication, or with the CLI profile named by the SRI's region component (`databricks:staging:my-scope:MY_KEY`).
+
+## Development
+
+```bash
+uv sync --all-extras --dev
+uv run pytest
+uv run ruff check .
+uv run mypy
+```
+
+Releases are published to PyPI by pushing a `vX.Y.Z` tag.
+
+## License
+
+[MIT](LICENSE)

vaultriever-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+vaultriever/__init__.py,sha256=qUG25TBeN9tcUJvEUMO25twEZ4qtkqpldzlErjFweGI,909
+vaultriever/exceptions.py,sha256=bfbStUjIh4AsrfN_rlalr6KktUK81uuvVIq4ZuH0Y6U,808
+vaultriever/logging.py,sha256=oEqR69yFqWKCShJ6vB8-7NioQGFn-QqrMHQpU5VDOBY,490
+vaultriever/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vaultriever/resolver.py,sha256=dhcJuN10Y67mqiP6_s2ZFcsRIE9U7v8rzqgbCsaCEoY,976
+vaultriever/settings_mixin.py,sha256=c6amQmxC9uXHaEykn-wrNXz_xNrnXEG1-X0VIgxWyqY,3130
+vaultriever/sri.py,sha256=yXnUpjiIqFkqORC3lcpduAK-XJBGFPw_2D8DDcFDS_I,2909
+vaultriever/providers/__init__.py,sha256=kp5Gt35U39ILjT8H5hiL7KwCeNA9ixT8vvQBh-daH54,733
+vaultriever/providers/aws.py,sha256=GrBF-qhXVmD3r0hTX5xkWh2N4f6Z4uNW9p1U4yh3JM8,2861
+vaultriever/providers/azure.py,sha256=rMDhDuM4sO2LrSJe4lJ4y38QCZftr55-3SVnQz1QSAc,471
+vaultriever/providers/base.py,sha256=dmG6dAaVEOtzjqZatVlMDBkebI1tLMofpoLhV55e-U4,1856
+vaultriever/providers/databricks.py,sha256=0KHas-i-WhjPHEsZW7dPvzvLE9zMHxvu-WCaBwry9Fg,3481
+vaultriever/providers/gcp.py,sha256=WuQynwRlgz94jKXNgb0do01JFiOi1zyV94IfJqVm_Yo,468
+vaultriever-0.1.0.dist-info/METADATA,sha256=ZFx0f-qh2F5pXrBxH5EBPSpm3iypGpP1WZzg-_q0sSk,5201
+vaultriever-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+vaultriever-0.1.0.dist-info/licenses/LICENSE,sha256=Qo4k0W8GvBayeeEC1Nytlxt4FnUjcfpuUEQfnGb2ZrE,1072
+vaultriever-0.1.0.dist-info/RECORD,,

vaultriever-0.1.0.dist-info/WHEEL

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

vaultriever-0.1.0.dist-info/licenses/LICENSE

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