Metadata-Version: 2.4
Name: cai-auth-sdk
Version: 0.15.0
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
# Public PyPI — recommended for external users
pip install cai-auth-sdk

# With Phase 4 forward-secret KEM support
pip install 'cai-auth-sdk[hybrid-kem]'

# From GitLab Package Registry (internal CAI Technology token required)
pip install --index-url \
  https://<user>:<glpat-token>@git.finesynergy.eu/api/v4/projects/87/packages/pypi/simple \
  cai-auth-sdk

# Editable from the monorepo
pip install -e cai-auth-python-sdk
```

Release channels:
- PyPI public: <https://pypi.org/project/cai-auth-sdk/>
- GitLab registry: <https://git.finesynergy.eu/gelusi/cai-auth/-/packages>

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