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

pip install gnexus-gauth

Or from source:

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:

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

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")

User avatar

After fetching the user, avatar data is available through the AuthenticatedUser object:

user = client.fetch_user(token_set.access_token)

# Direct avatar URL (or None if not set)
print(user.avatar_url)

# Size variants: small, medium, large, xlarge
for variant, url in user.avatar_variants.items():
    print(f"{variant}: {url}")

The avatar_url and avatar_variants are read from the profile section of the /oauth/userinfo response. Avatar URLs are public — no additional token is required to download the image.

If you need the raw binary data of an avatar, use any HTTP client:

import httpx

if user.avatar_url:
    response = httpx.get(user.avatar_url)
    image_bytes = response.content

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

Package Structure

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

# 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