English · Русский

orcestr-auth

Python authentication core and FastAPI/SQLAlchemy adapters for the Orcestr ecosystem.

The application keeps its real user model and product lifecycle. The package owns password, token, session, cookie, recovery, OAuth and WebSocket authentication mechanics.

Install

pip install "orcestr-auth[all]"

Optional groups:

Main APIs

SQLAlchemy Wiring

Attach auth tables to the application's registry and real user primary key:

from orcestr_auth.sqlalchemy import UserFieldMap, create_auth_models

auth_models = create_auth_models(
    registry=Base.registry,
    user_model=UserORM,
)

user_fields = UserFieldMap(
    id=UserORM.id,
    username=UserORM.username,
    email=UserORM.email,
    password_hash=UserORM.password_hash,
    is_active=UserORM.is_active,
    email_verified_at=UserORM.email_verified_at,
)

This creates direct indexed queries and real foreign keys. It does not create a second user table and does not use runtime reflection.

FastAPI Wiring

from orcestr_auth.fastapi import create_auth_dependencies, create_auth_router

auth_dependencies = create_auth_dependencies(
    config=auth_config,
    session_dependency=get_control_db_session,
    user_model=UserORM,
    user_fields=user_fields,
    models=auth_models,
)

router = create_auth_router(
    config=auth_config,
    application_dependency=get_auth_http_application,
    current_user_dependency=auth_dependencies.current_user,
    register_model=RegisterRequest,
    user_response_model=UserRead,
)

Auth services raise the shared orcestr_core.ApiError. Register the Core middleware and handlers once on the application, then include the auth router:

from fastapi import FastAPI
from orcestr_core.fastapi import RequestIdMiddleware, register_api_error_handlers

app = FastAPI()
app.add_middleware(RequestIdMiddleware)
register_api_error_handlers(app)
app.include_router(router)

This preserves stable auth codes such as invalid_credentials, structured validation fields and x-request-id in the same envelope as the rest of the product API.

The consumer implements the small AuthHttpApplication boundary for product-specific work: user creation, legal acceptance, tenant bootstrap, email delivery, audit and rate limits. Standard endpoints, cookies and token responses remain library-owned.

Security Model

• browser tokens live in HttpOnly cookies and never appear in browser auth JSON;
• cookie mutations require the configured CSRF header;
• refresh tokens are opaque, hashed, rotated and replay-protected;
• access JWTs validate issuer, audience, expiry, type, JTI and server session state;
• recovery codes are hashed, expiring, attempt-limited and one-time;
• OAuth validates redirects and supports state/PKCE without implicit account linking;
• WebSocket access uses short-lived one-time tickets.

See security invariants and architecture boundaries.

Development

uv sync --frozen
uv run pytest -q
uv build

Ecosystem

• All auth packages: Orcestr Auth repository
• Shared API contracts: Orcestr Core
• UI system: @orcestr/ui
• Product: orcestr.com

License

Licensed under the Mozilla Public License 2.0. Commercial use is permitted; see the repository NOTICE and trademark policy.