# 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")
```

## Keyless service-to-service verify

Verify an agent's credential **presentation** offline against a pinned root — one call, a
typed `Status` enum, no exception for a denial:

```python
from auths import verify_presentation, PresentationStatus

report = verify_presentation(bundle_json)  # the Auths-Presentation request bundle
if report.status is not PresentationStatus.VALID:
    raise PermissionError(f"denied: {report.status}")  # WRONG_AUDIENCE, EXPIRED, …

print(report.subject, report.caps)  # granted holder + capabilities
```

`verify_credential(bundle_json)` returns a `CredentialReport` the same way — e.g.
`report.status is CredentialStatus.CREDENTIAL_REVOKED` carries `report.revoked_at`. Malformed
input returns a typed `MALFORMED_REQUEST` status; it never raises.

## 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}")
```

## Time-pinned verification

```python
# Verify an attestation's authenticity at a historical point in time
result = auths.verify(attestation_json=data, issuer_key=key, at="2024-06-15T00:00:00Z")
```

> Capability/role authority is no longer checked at verification time. A capability
> grant comes from a holder-verified ACDC credential, not the attestation.

## 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
