Metadata-Version: 2.4
Name: auths
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Typing :: Typed
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Dist: pyjwt>=2.0 ; extra == 'jwt'
Requires-Dist: cryptography>=3.0 ; extra == 'jwt'
Provides-Extra: jwt
Summary: Auths Python SDK - decentralized identity for developers and AI agents
Keywords: identity,cryptography,did,signing,verification,git,keri
License: Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/auths-dev/auths/issues
Project-URL: Documentation, https://docs.auths.dev
Project-URL: Homepage, https://auths.dev
Project-URL: Repository, https://github.com/auths-dev/auths

# Auths Python SDK

Decentralized identity for developers and AI agents. Sign, verify, and manage cryptographic identities with Git-native storage.

## Install

```bash
pip install auths
```

## Quick start

```python
from auths import Auths

auths = Auths()

# Verify an attestation
result = auths.verify(attestation_json=data, issuer_key=public_key_hex)
print(result.valid)  # True

# Sign bytes
signature = auths.sign(b"hello world", private_key=secret_key_hex)
```

## Identity management

```python
from auths import Auths

auths = Auths(repo_path="~/.auths")

# Create a cryptographic identity
identity = auths.identities.create(label="laptop")
print(identity.did)  # did:keri:EBfd...

# Provision an agent (for CI, MCP servers, etc.)
agent = auths.identities.provision_agent(
    identity.did,
    name="deploy-bot",
    capabilities=["sign"],
)

# Sign using the keychain-stored identity key
sig = auths.sign_as(b"hello world", identity=identity.did)

# Link and manage devices
device = auths.devices.link(identity_did=identity.did, capabilities=["sign"])
auths.devices.revoke(device.did, identity_did=identity.did, note="replaced")
```

## Git commit verification

```python
from auths.git import verify_commit_range

result = verify_commit_range("HEAD~5..HEAD")
for commit in result.commits:
    print(f"{commit.commit_sha}: {'valid' if commit.is_valid else commit.error}")
```

## Capability-aware verification

```python
# Verify an attestation grants a specific capability
result = auths.verify(attestation_json=data, issuer_key=key, required_capability="sign_commit")

# Verify an entire chain grants a capability
report = auths.verify_chain(chain, root_key, required_capability="deploy")
```

## Agent auth for MCP / AI frameworks

```python
from auths.agent import AgentAuth

auth = AgentAuth(
    bridge_url="https://bridge.example.com",
    attestation_chain_path=".auths/agent-chain.json",
)
token = auth.get_token(capabilities=["read", "write"])
```

## Error handling

```python
from auths import Auths, VerificationError, NetworkError

auths = Auths()
try:
    result = auths.verify(attestation_json=data, issuer_key=key)
except VerificationError as e:
    print(e.code)     # "expired_attestation"
    print(e.message)  # "Attestation expired at 2024-01-15T..."
except NetworkError as e:
    if e.should_retry:
        pass  # safe to retry
```

All errors inherit from `AuthsError` and carry `.code`, `.message`, and `.context`.

## Configuration

```python
# Auto-discover (uses ~/.auths)
auths = Auths()

# Explicit repo path
auths = Auths(repo_path="/path/to/identity-repo")

# With passphrase (or set AUTHS_PASSPHRASE env var)
auths = Auths(passphrase="my-secret")

# Headless / CI mode
# Set AUTHS_KEYCHAIN_BACKEND=file for environments without a system keychain
```

## API reference

Type stubs are bundled (`py.typed` + `__init__.pyi`). Your editor will show full signatures, docstrings, and return types for all methods.

## License

Apache-2.0

