Metadata-Version: 2.4
Name: keyverify
Version: 2.0.0
Summary: Shared central API-key verification client with TTL cache, scope enforcement, and fail-open/fail-closed behavior.
License: MIT
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pyright>=1.1.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: twine>=5.1.1; extra == 'dev'
Description-Content-Type: text/markdown

# key-verify-client

Shared central API-key verification client used by ingress services such as
`agent-platform` and `asr-service` when central API-key verification is enabled.

## Package naming

The three names intentionally differ by responsibility:

- Git repository: `key-verify-client`
- PyPI project / distribution: **`keyverify`**
- Python import package: **`keyverify`**

Do not change `[project].name` in `pyproject.toml` to `key-verify-client` or
`key_verify_client`. The existing PyPI project is `keyverify`, and Trusted
Publishing authorizes that project name.

Install from PyPI:

```bash
pip install keyverify
```

Import from Python:

```python
from keyverify import KeyVerifyClient, VerificationResult
```

## Behavior

- Calls `POST /internal/verify-key` over HTTP(S) with a per-deployment service token.
- Enforces `CLIENT_SCOPE` locally against the authoritative `client` returned by admin-platform.
- Caches successful verification results for `KEY_CACHE_TTL` / `AUTH_CACHE_TTL` seconds.
- `cache_ttl=0` disables caching so revocation is immediately visible.
- `fail_open=false` rejects when the central service is unreachable and there is no live cache entry.
- Plaintext client keys are never used as cache dictionary keys; only SHA-256 digests are retained.

## Local development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -q
```

## Build and verify release artifacts

Always clean old artifacts first:

```bash
rm -rf dist build *.egg-info src/*.egg-info
python -m build
python -m twine check dist/*
python scripts/verify_dist_metadata.py dist
```

For version `2.0.0`, the artifact names must be:

```text
keyverify-2.0.0-py3-none-any.whl
keyverify-2.0.0.tar.gz
```

The metadata verification command must report:

```text
Name=keyverify Version=2.0.0
```

Only after those checks pass should CI upload `dist/*` to PyPI.
