nyxa-auth — JWT / session auth & policies for Nyxa

Authentication and authorization for apps built with nyxa. Core nyxa does not depend on this package (no JWT in the core install).

At a glance

Install

uv add nyxa-auth
uv add 'nyxa-auth[oauth]'   # Authlib — Google / GitHub OAuth
# JWT (default driver):
uv run nyxa init myapi --database sqlite --auth jwt --no-input
# Session cookies:
uv run nyxa init myapi --database sqlite --auth session --no-input

JWT driver

AUTH_DRIVER=jwt
AUTH_SECRET_KEY=change-me-to-a-long-random-secret!!
# AUTH_ALGORITHM=HS256
# AUTH_ACCESS_TOKEN_EXPIRE_MINUTES=60

Session driver

AUTH_DRIVER=session
AUTH_SECRET_KEY=change-me-to-a-long-random-secret!!
# AUTH_SESSION_SECRET=  # optional override for cookie signing

In main.py:

from nyxa_auth import configure_session, set_user_loader

app = FastAPI()
configure_session(app)
set_user_loader(...)

Login stores user_id in a signed cookie; require_auth reads it instead of Bearer JWT.

Personal access tokens

Requires nyxa-db. Under AUTH_DRIVER=jwt, Bearer auth tries JWT first, then a registered personal-token lookup.

from nyxa_auth import (
    create_personal_token,
    find_token,
    set_token_lookup,
    set_user_loader,
)

def lookup(plain: str) -> str | None:
    session = get_session_factory()()
    try:
        row = find_token(session, plain)
        if row is None:
            return None
        session.commit()
        return str(row.tokenable_id)
    finally:
        session.close()

set_user_loader(...)
set_token_lookup(lookup)

# Issue (plaintext once):
issued = create_personal_token(session, user.id, "ci")
# Authorization: Bearer nyxa_<id>_<secret>

Table: personal_access_tokens (hash only). Revoke with revoke_personal_token / revoke_all_for_user.

OAuth (Google + GitHub)

Requires the optional extra and Authlib. Identity rows need nyxa-db:

uv add 'nyxa-auth[oauth]'

OAUTH_GOOGLE_CLIENT_ID=...
OAUTH_GOOGLE_CLIENT_SECRET=...
OAUTH_GOOGLE_REDIRECT_URI=http://127.0.0.1:8000/api/oauth/google/callback
OAUTH_GITHUB_CLIENT_ID=...
OAUTH_GITHUB_CLIENT_SECRET=...
OAUTH_GITHUB_REDIRECT_URI=http://127.0.0.1:8000/api/oauth/github/callback
AUTH_SECRET_KEY=...   # also signs the OAuth state cookie

from nyxa_auth import (
    clear_oauth_state_cookie,
    complete_oauth_login,
    create_authorize_redirect,
    provider_from_env,
    resolve_oauth_identity,
)

provider = provider_from_env("google")  # or "github"
# GET /oauth/google/redirect → create_authorize_redirect(request, provider)
# callback → resolve_oauth_identity(...) then complete_oauth_login(...)
# JWT driver returns {"access_token", "token_type"}; session driver returns {"ok": true}

Users are linked by (provider, sub) in oauth_identities. On first login, email auto-link attaches the identity to an existing user when emails match (trusts the provider). Existing Google users get an identity row on their next OAuth login.

Quick start

from typing import Annotated

from fastapi import Depends, FastAPI
from nyxa import Route, register
from nyxa_auth import (
    CurrentUser,
    create_access_token,
    hash_password,
    require_auth,
    set_user_loader,
    verify_password,
)

app = FastAPI()

# Map JWT "sub" → your user object (sync callable).
users = {"1": {"id": 1, "email": "ada@example.com", "password_hash": hash_password("secret")}}
set_user_loader(lambda sub: users.get(sub))
register(app)

@app.post("/login")
def login(email: str, password: str) -> dict[str, str]:
    user = next((u for u in users.values() if u["email"] == email), None)
    if user is None or not verify_password(password, user["password_hash"]):
        from nyxa_auth import AuthenticationError
        raise AuthenticationError("Invalid credentials")
    return {"access_token": create_access_token(str(user["id"])), "token_type": "bearer"}

# Protect a route group:
with Route.prefix("/api"), Route.middleware(require_auth):
    Route.get("/me", lambda user: user)  # prefer a controller in real apps

Or inject the user on a controller action:

from nyxa_auth import CurrentUser

async def me(self, user: CurrentUser) -> dict:
    return {"id": getattr(user, "id", None)}

Policies

uv run nyxa make:policy User

from nyxa_auth import Policy, authorize

class UserPolicy(Policy):
    def update(self, user, model=None) -> bool:
        return model is not None and user.id == model.id

# In a controller:
authorize(user, UserPolicy, "update", target_user)

Denied abilities raise AuthorizationError (HTTP 403). Missing/invalid credentials raise AuthenticationError (HTTP 401).