Metadata-Version: 2.4
Name: cai-auth-sdk
Version: 0.7.8
Summary: Pure-Python client SDK for the CAI-AUTH server (CBOR/HTTP).
Project-URL: Homepage, https://github.com/cai-technology/cai-auth
Project-URL: Repository, https://github.com/cai-technology/cai-auth
Author-email: CAI Technology <contact@caitech.ro>
License: Proprietary — CAI Technology SRL
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.11
Requires-Dist: cbor2>=5.6
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Provides-Extra: hybrid-kem
Requires-Dist: cryptography>=42.0; extra == 'hybrid-kem'
Requires-Dist: quantcrypt>=0.4; extra == 'hybrid-kem'
Provides-Extra: test
Requires-Dist: cryptography>=42.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Requires-Dist: quantcrypt>=0.4; extra == 'test'
Requires-Dist: respx>=0.21; extra == 'test'
Description-Content-Type: text/markdown

# cai-auth-sdk (Python)

Pure-Python client SDK for the [CAI-AUTH server](../cai-auth-server) using
HTTP/CBOR. Zero native dependencies — pip installs cleanly on any platform
that has Python 3.11+.

## Install

```bash
# From the monorepo (editable)
pip install -e cai-auth-python-sdk

# Or build a wheel
cd cai-auth-python-sdk && python -m build
```

## Quick start

```python
from cai_auth_sdk import CaiAuthClient

async with CaiAuthClient(base_url="https://cai-auth.example.com") as c:
    ok = await c.health()
    assert ok.status == "ok"
```

## Running tests (Docker only, per project rule)

```bash
docker run --rm --name caiauth_python_sdk_test \
  -u $(id -u):$(id -g) \
  -v $(pwd)/..:/work \
  -w /work/cai-auth-python-sdk \
  caiauth/python-sdk-test:latest \
  pytest -v
```

## Scope

Covers all 11 CAI-AUTH protocol endpoints in the 0.2.0 spec:

| # | Endpoint                        | SDK method                |
|---|---------------------------------|---------------------------|
| 1 | `GET  /health`                  | `health()`                |
| 2 | `GET  /metrics`                 | `metrics()`               |
| 3 | `POST /v1/enroll/begin`         | `enroll_begin()`          |
| 4 | `POST /v1/enroll/complete`      | `enroll_complete()`       |
| 5 | `POST /v1/challenge/create`     | `challenge_create()`      |
| 6 | `POST /v1/challenge/verify`     | `challenge_verify()`      |
| 7 | `POST /v1/recovery/begin`       | `recovery_begin()`        |
| 8 | `POST /v1/recovery/submit-shard`| `recovery_submit_shard()` |
| 9 | `POST /v1/recovery/complete`    | `recovery_complete()`     |
| 10| `POST /v1/revoke`               | `revoke()`                |
| 11| `GET  /v1/audit`                | `audit()`                 |

## Limitations

- No certificate pinning (add in Phase 5.1 alongside public deployment).
- No automatic session token refresh — follow server semantics in §5.
- Sync API only for now; async is the primary surface.
