1  # Auths Python SDK
  2  
  3  Decentralized identity for developers and AI agents. Sign, verify, and manage cryptographic identities with Git-native storage.
  4  
  5  ## Install
  6  
  7  ```bash
  8  pip install auths-python
  9  ```
 10  
 11  ## Quick start
 12  
 13  ```python
 14  from auths import Auths
 15  
 16  auths = Auths()
 17  
 18  # Verify an attestation
 19  result = auths.verify(attestation_json=data, issuer_key=public_key_hex)
 20  print(result.valid)  # True
 21  
 22  # Sign bytes
 23  signature = auths.sign(b"hello world", private_key=secret_key_hex)
 24  ```
 25  
 26  ## Identity management
 27  
 28  ```python
 29  from auths import Auths
 30  
 31  auths = Auths(repo_path="~/.auths")
 32  
 33  # Create a cryptographic identity
 34  identity = auths.identities.create(label="laptop")
 35  print(identity.did)  # did:keri:EBfd...
 36  
 37  # Provision an agent (for CI, MCP servers, etc.)
 38  agent = auths.identities.provision_agent(
 39      identity.did,
 40      name="deploy-bot",
 41      capabilities=["sign"],
 42  )
 43  
 44  # Sign using the keychain-stored identity key
 45  sig = auths.sign_as(b"hello world", identity=identity.did)
 46  
 47  # Link and manage devices
 48  device = auths.devices.link(identity_did=identity.did, capabilities=["sign"])
 49  auths.devices.revoke(device.did, identity_did=identity.did, note="replaced")
 50  ```
 51  
 52  ## Git commit verification
 53  
 54  ```python
 55  from auths.git import verify_commit_range
 56  
 57  result = verify_commit_range("HEAD~5..HEAD")
 58  for commit in result.commits:
 59      print(f"{commit.commit_sha}: {'valid' if commit.is_valid else commit.error}")
 60  ```
 61  
 62  ## Capability-aware verification
 63  
 64  ```python
 65  # Verify an attestation grants a specific capability
 66  result = auths.verify(attestation_json=data, issuer_key=key, required_capability="sign_commit")
 67  
 68  # Verify an entire chain grants a capability
 69  report = auths.verify_chain(chain, root_key, required_capability="deploy")
 70  ```
 71  
 72  ## Agent auth for MCP / AI frameworks
 73  
 74  ```python
 75  from auths.agent import AgentAuth
 76  
 77  auth = AgentAuth(
 78      bridge_url="https://bridge.example.com",
 79      attestation_chain_path=".auths/agent-chain.json",
 80  )
 81  token = auth.get_token(capabilities=["read", "write"])
 82  ```
 83  
 84  ## Error handling
 85  
 86  ```python
 87  from auths import Auths, VerificationError, NetworkError
 88  
 89  auths = Auths()
 90  try:
 91      result = auths.verify(attestation_json=data, issuer_key=key)
 92  except VerificationError as e:
 93      print(e.code)     # "expired_attestation"
 94      print(e.message)  # "Attestation expired at 2024-01-15T..."
 95  except NetworkError as e:
 96      if e.should_retry:
 97          pass  # safe to retry
 98  ```
 99  
100  All errors inherit from `AuthsError` and carry `.code`, `.message`, and `.context`.
101  
102  ## Configuration
103  
104  ```python
105  # Auto-discover (uses ~/.auths)
106  auths = Auths()
107  
108  # Explicit repo path
109  auths = Auths(repo_path="/path/to/identity-repo")
110  
111  # With passphrase (or set AUTHS_PASSPHRASE env var)
112  auths = Auths(passphrase="my-secret")
113  
114  # Headless / CI mode
115  # Set AUTHS_KEYCHAIN_BACKEND=file for environments without a system keychain
116  ```
117  
118  ## API reference
119  
120  Type stubs are bundled (`py.typed` + `__init__.pyi`). Your editor will show full signatures, docstrings, and return types for all methods.
121  
122  ## License
123  
124  Apache-2.0