# gnexus-gauth

Framework-agnostic Python client library for integrating services with `gnexus-auth`.

## Status

Alpha — early scaffold with working core pieces.

Current scaffold includes:

- package metadata;
- high-level `GAuthClient`;
- configuration object;
- DTO set;
- storage and service contracts;
- exception family;
- PKCE and authorization URL helpers;
- HTTP token endpoint client;
- HTTP userinfo client;
- webhook HMAC verifier;
- webhook JSON parser;
- package-level unit tests;
- plain Python integration example.

## Requirements

- Python 3.11+
- `httpx`

## Installation

```bash
pip install gnexus-gauth
```

Or from source:

```bash
pip install git+https://git.gnexus.space/git/root/gnexus-auth-client-py.git
```

## Usage Shape

The package is designed around one high-level client:

```python
from gnexus_gauth.client import GAuthClient
```

It expects:

- `GAuthConfig`
- token endpoint implementation
- runtime user provider
- webhook verifier
- webhook parser
- state store
- PKCE store

### Quick Example

```python
from gnexus_gauth.client import GAuthClient
from gnexus_gauth.config import GAuthConfig
from gnexus_gauth.oauth import HttpTokenEndpoint
from gnexus_gauth.runtime import HttpRuntimeUserProvider
from gnexus_gauth.webhook import HmacWebhookVerifier, JsonWebhookParser
from gnexus_gauth.support import InMemoryStateStore, InMemoryPkceStore

config = GAuthConfig(
    base_url="https://gnexus-auth.local",
    client_id="my-service",
    client_secret="my-secret",
    redirect_uri="https://my-service.local/callback",
)

client = GAuthClient(
    config=config,
    token_endpoint=HttpTokenEndpoint(config),
    runtime_user_provider=HttpRuntimeUserProvider(config),
    webhook_verifier=HmacWebhookVerifier(config),
    webhook_parser=JsonWebhookParser(),
    state_store=InMemoryStateStore(),
    pkce_store=InMemoryPkceStore(),
)

# Build authorization URL
auth_request = client.build_authorization_request(
    return_to="/dashboard",
    scopes=["openid", "email", "profile"],
)
print(auth_request.authorization_url)

# Exchange callback code
token_set = client.exchange_authorization_code("code_from_callback", "state_from_callback")
user = client.fetch_user(token_set.access_token)

# Verify and parse webhook
event = client.verify_and_parse_webhook(raw_body, headers, "webhook_secret")
```

See `examples/plain/example.py` for a more complete demonstration.

## Package Structure

```text
src/gnexus_gauth/
  __init__.py
  client.py       # GAuthClient
  config.py       # GAuthConfig
  contracts.py    # Abstract interfaces
  dto.py          # Data transfer objects
  exceptions.py   # Exception hierarchy
  oauth.py        # PKCE, URL builder, token endpoint
  runtime.py      # Userinfo client
  support.py      # In-memory stores, system clock
  webhook.py      # HMAC verifier, JSON parser
```

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check src tests

# Run type checker
mypy src
```

## Related

- PHP version: `gnexus/auth-client`
- Auth server: `gnexus-auth`