Metadata-Version: 2.4
Name: hush-am-sdk
Version: 0.3.0
Summary: Python SDK for Hush secret access via SPIFFE mTLS
Author-email: Hush Security <support@hush.security>
License-Expression: Apache-2.0
Project-URL: Homepage, https://hush.security
Project-URL: Repository, https://github.com/hushsecurity/hush-am-sdk-python
Project-URL: Issues, https://github.com/hushsecurity/hush-am-sdk-python/issues
Keywords: hush,secrets,spiffe,mtls,sdk,access-manager
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
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: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: spiffe>=0.2.0
Requires-Dist: spiffe-tls>=0.3.1
Requires-Dist: httpx>=0.27.0
Requires-Dist: cryptography>=41.0
Requires-Dist: pyOpenSSL>=23.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pylint>=4.0.4; extra == "dev"
Requires-Dist: ruff>=0.15.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# hush-am-sdk-python

Python SDK for fetching secrets from the Hush access-manager via SPIFFE mTLS.

## Requirements

- Hush-am access-manager deployed in the cluster.
- A SPIRE agent reachable in the pod (provides the SPIFFE SVID for mTLS).
- The pod's workload identity is bound to a Hush policy granting access to the requested secrets.

## Error handling

All SDK errors derive from `HushError`. Catch the base class for a generic
fallback, or the specific subclasses where the caller can do something useful:

```python
from husham import HushClient, HushSecretNotFoundError, HushError

try:
    with HushClient() as hush:
        creds = hush.get_secret("secret_name")
except HushSecretNotFoundError:
    ...  # secret missing or no access
except HushError as e:
    ...  # any other SDK failure
```

## End-to-end example

The snippet below needs a Hush-am-instrumented runtime to actually fetch a
secret — it cannot run from your laptop because there is no local SPIRE agent.

1. Create a Hush-am policy that:
   - Includes an SDK delivery config that maps a secret to `<secret_name>` and
     maps the fields you intend to read (e.g. `username`, `password`, `host`).
   - Adds an attestation rule for the pod that will run the SDK, so its
     workload identity is bound to the policy.
2. Install the SDK in the pod image:

   ```bash
   pip install hush-am-sdk
   ```

3. Run this snippet inside the pod:

```python
import sys
from husham import HushClient, HushError


def main() -> int:
    try:
        with HushClient() as hush:
            secret = hush.get_secret("<secret_name>")
            print(f"username: {secret['username']}")
            print(f"password: {secret['password']}")

            # Or fetch a single field directly:
            host = hush.get_secret_field("<secret_name>", "host")
            print(f"host: {host}")
    except HushError as exc:
        print(f"{type(exc).__name__}: {exc}", file=sys.stderr)
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())
```

## Additional features

### Bearer token for user-claims filtering

Pass an optional bearer token to scope the request to a specific user's claims:

```python
hush.get_secret("secret_name", token=user_jwt)
hush.get_secret_field("secret_name", "password", token=user_jwt)
```

### Module-level helpers

Module-level convenience helpers backed by a singleton client are also available,
so you don't need to manage a `HushClient` instance yourself:

```python
from husham import get_secret, get_secret_field

creds = get_secret("secret_name")
password = get_secret_field("secret_name", "password")
```
