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

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
• 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.