Metadata-Version: 2.4
Name: ecc-auth
Version: 0.1.3
Summary: Shared Keycloak OIDC authentication SDK for ECC projects
Project-URL: Homepage, https://github.com/early-chinese-civilization/ecc-auth
Project-URL: Source, https://github.com/early-chinese-civilization/ecc-auth
Project-URL: Issues, https://github.com/early-chinese-civilization/ecc-auth/issues
Author: Early Chinese Civilization
Keywords: authentication,ecc,fastapi,keycloak,oidc
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: authlib>=1.6
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.28
Requires-Dist: pyjwt[crypto]>=2.10
Requires-Dist: starlette>=0.40
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ty; extra == 'dev'
Requires-Dist: uvicorn>=0.34; extra == 'dev'
Description-Content-Type: text/markdown

# ecc-auth

`ecc-auth` is a small shared authentication SDK for ECC Python services that integrate with Keycloak and FastAPI.

It provides:

- Keycloak configuration via `KeycloakConfig`
- Standard FastAPI auth routes via `create_auth_router`
- Current-user dependencies via `get_current_user` and `get_current_user_optional`
- JWT verification helpers via `verify_access_token`

## Installation

Once published to PyPI:

```bash
pip install ecc-auth
```

Or with `uv`:

```bash
uv add ecc-auth
```

## Quick Start

```python
from fastapi import FastAPI

from ecc_auth import AuthSessionMiddleware, KeycloakConfig, create_auth_router, init_dependencies

app = FastAPI()
app.add_middleware(AuthSessionMiddleware)

config = KeycloakConfig(
    url="https://keycloak.example.com",
    realm="ecc",
    client_id="example-client",
    client_secret="example-secret",
    tls_insecure=False,
)

init_dependencies(config)
app.include_router(create_auth_router(config), prefix="/api/auth")
```

## Development

This repository is a single Python package repository. The package root,
tests, and release metadata all live at the repository root.

Build the package locally:

```bash
uv build
```

Run tests:

```bash
uv run pytest
```

## Callback Error Contract

When `/api/auth/callback` cannot complete, `ecc-auth` redirects back to the app
origin with a stable `?error=<code>` query parameter.

Current callback error codes:

- `missing_state`
- `invalid_state`
- `missing_code`
- `csrf_mismatch`
- `missing_pkce`
- `token_exchange_failed`
- `callback_upstream_failed`
- `token_not_yet_valid`
- `token_validation_failed`
- `token_verification_unavailable`
- `user_sync_failed`
- `callback_failed`

Consumer apps should map these codes to user-facing copy instead of exposing raw
exception text.

## Publishing

This repository includes a GitHub Actions workflow at `.github/workflows/publish-python.yml`.

Recommended release flow:

1. Bump `version` in `pyproject.toml`.
2. Commit and push the change.
3. Create a GitHub release.
4. Let the workflow build and publish the package to PyPI.

Before the first release, configure a Trusted Publisher for this repository in PyPI and point it at:

- Repository owner: `early-chinese-civilization`
- Repository name: `ecc-auth`
- Workflow file: `.github/workflows/publish-python.yml`
- Environment name: `pypi`
