Metadata-Version: 2.4
Name: nexgensis-auth-client
Version: 0.1.0
Summary: Python SDK for Nexgensis CentralAuth — JWT validation, auth API client, admin client, webhooks, Django integration
Author: Nexgensis Platform Team
License: Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: Django :: 4.2
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyJWT>=2.8
Requires-Dist: cryptography>=41.0
Requires-Dist: httpx>=0.27
Requires-Dist: typing-extensions>=4.7; python_version < "3.11"
Provides-Extra: django
Requires-Dist: Django<5.0,>=4.2; extra == "django"
Requires-Dist: djangorestframework>=3.15; extra == "django"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-django>=4.7; extra == "dev"
Requires-Dist: responses>=0.24; extra == "dev"
Requires-Dist: Django<5.0,>=4.2; extra == "dev"
Requires-Dist: djangorestframework>=3.15; extra == "dev"

# nexgensis-auth-client

Official Python SDK for **CentralAuth** — Nexgensis' shared identity provider.

Products use it to:

- **Validate** Django-issued JWTs against the published JWKS (RS256, audience-bound).
- **Call** `/oauth/*` and `/api/auth/*` (`AuthClient`) on behalf of a human user.
- **Mint M2M tokens** (`M2MClient`) for service-to-service calls, with audience+scope-keyed in-process caching.
- **Drive admin operations** (`AdminClient`) — users, groups, products, entitlements, audit — for backend sync jobs.
- **Receive webhooks** safely — HMAC-SHA256 signature, timestamp replay-guard, idempotent dedupe (`WebhookVerifier` + Django `@webhook_view`).
- **Plug into Django/DRF** with one settings dict — `JWTAuthentication`, `AuthMiddleware`, `HasGroup` / `HasEntitlement` / `HasScope`.

## Install

```bash
pip install nexgensis-auth-client            # core: validation + clients + webhooks
pip install 'nexgensis-auth-client[django]'  # adds Django + DRF integration
```

## 60-second Django integration

```python
# settings.py
CENTRALAUTH = {
    "BASE_URL": "https://auth.nexgensis.com",
    "AUDIENCE": "qms",   # this product's client_id
}

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "nexgensis_auth_client.django.authentication.JWTAuthentication",
    ],
}
```

```python
# views.py
from rest_framework.decorators import api_view, permission_classes
from rest_framework.permissions import IsAuthenticated
from nexgensis_auth_client.django.permissions import HasGroup

@api_view(["POST"])
@permission_classes([IsAuthenticated, HasGroup("QA_LEAD")])
def close_issue(request, issue_id):
    ...
```

After auth: `request.user.id` / `request.auth.has_group(...)` / `request.auth.email`.

## Webhook receiver

```python
# settings.py
QMS_USER_SYNC_SECRET = os.environ["QMS_USER_SYNC_SECRET"]

# urls.py
path("webhooks/centralauth/", on_user_event),

# views.py
from nexgensis_auth_client.django.webhooks import webhook_view

@webhook_view(secret_setting="QMS_USER_SYNC_SECRET")
def on_user_event(request, event):
    if event.event_type == "user.disabled":
        ...
    return HttpResponse(status=200)
```

## Test helpers

```python
from nexgensis_auth_client.testing import build_auth_context, override_auth

def test_qa_lead_can_close(api_client):
    ctx = build_auth_context(user_id="u-1", groups=["QA_LEAD"])
    with override_auth(api_client, ctx):
        response = api_client.post("/issues/I-1/close/")
    assert response.status_code == 200
```

## Stable surface

These are the public, semver-protected names:

| Module                                  | Purpose                                |
|-----------------------------------------|----------------------------------------|
| `AuthClient`                            | OAuth user flows (login/refresh/etc.)  |
| `AdminClient`                           | `/api/v1/*` admin REST                 |
| `M2MClient`                             | client_credentials with token caching  |
| `JWTValidator` / `JWKSCache`            | Token validation                       |
| `AuthContext`                           | Claim accessor (groups, scopes, etc.)  |
| `WebhookVerifier` / `VerifiedEvent`     | Webhook HMAC + dedupe                  |
| `nexgensis_auth_client.django.*`        | Django/DRF integration                 |
| `nexgensis_auth_client.testing.*`       | Test fixtures                          |

See `docs/PRODUCT_INTEGRATION_GUIDE.md` in the CentralAuth repo for the full guide.
