fastauth-py 0.1.0__py3-none-any.whl

fastauth/__init__.py

@@ -0,0 +1,9 @@
+"""fastauth — a modular FastAPI authentication library."""
+
+from __future__ import annotations
+
+from fastauth.config import FastAuthConfig
+from fastauth.runtime.auth import FastAuth
+
+__all__ = ["FastAuth", "FastAuthConfig", "__version__"]
+__version__ = "0.1.0"

fastauth/cli/__init__.py

@@ -0,0 +1,3 @@
+"""fastauth CLI."""
+
+from __future__ import annotations

fastauth/cli/main.py

@@ -0,0 +1,207 @@
+"""Typer-based CLI for fastauth."""
+
+from __future__ import annotations
+
+import asyncio
+import pathlib
+import secrets
+from typing import Any
+
+import typer
+from rich import print as rich_print
+
+__all__ = ["AUTH_SCAFFOLD", "AUTH_SCAFFOLDS", "app", "cli"]
+
+
+app = typer.Typer(no_args_is_help=True, help="fastauth CLI")
+
+
+MEMORY_AUTH_SCAFFOLD = '''\
+"""Authkit instance for this application.
+
+This scaffold demonstrates explicit dependency injection. Build your
+``FastAuthConfig`` in your application code, then pass it to ``create_auth``.
+fastauth never reads process-level configuration.
+"""
+from __future__ import annotations
+
+from fastauth import FastAuth, FastAuthConfig
+from fastauth.storage.memory import InMemoryAdapter
+
+
+def create_auth(config: FastAuthConfig) -> FastAuth:
+    return FastAuth(config, adapter=InMemoryAdapter())
+'''
+
+
+MONGO_AUTH_SCAFFOLD = '''\
+"""Mongo-backed fastauth instance for this application.
+
+Build ``FastAuthConfig`` in your application code. The Mongo URL and database
+name come from ``config.database.mongo``; fastauth never reads process-level
+configuration.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
+
+from fastauth import FastAuth, FastAuthConfig
+from fastauth.storage.beanie import BeanieAdapter, init_beanie_documents
+
+
+def create_mongo_database(config: FastAuthConfig) -> AsyncIOMotorDatabase[Any]:
+    client: AsyncIOMotorClient[Any] = AsyncIOMotorClient(
+        config.database.mongo.url,
+        uuidRepresentation="standard",
+    )
+    return client[config.database.mongo.database_name]
+
+
+def create_auth(
+    config: FastAuthConfig,
+    database: AsyncIOMotorDatabase[Any],
+) -> FastAuth:
+    return FastAuth(config, adapter=BeanieAdapter(database))
+
+
+async def init_auth_database(database: AsyncIOMotorDatabase[Any]) -> None:
+    await init_beanie_documents(database)
+'''
+
+
+POSTGRES_AUTH_SCAFFOLD = '''\
+"""Postgres-backed fastauth instance for this application.
+
+Build ``FastAuthConfig`` in your application code. The Postgres URL and table
+prefix come from ``config.database.postgres``; fastauth never reads
+process-level configuration.
+"""
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from fastauth import FastAuth, FastAuthConfig
+from fastauth.storage.postgres import PostgresAdapter
+
+
+def create_auth(config: FastAuthConfig) -> FastAuth:
+    adapter = PostgresAdapter.from_url(
+        config.database.postgres.url,
+        table_prefix=config.database.postgres.table_prefix,
+    )
+    return FastAuth(config, adapter=adapter)
+
+
+def create_app(config: FastAuthConfig) -> FastAPI:
+    auth = create_auth(config)
+    adapter = auth.context.adapter
+    if not isinstance(adapter, PostgresAdapter):
+        raise RuntimeError("expected PostgresAdapter")
+    app = FastAPI(lifespan=adapter.checked_lifespan(auth))
+    auth.install(app)
+    return app
+'''
+
+
+AUTH_SCAFFOLD = MEMORY_AUTH_SCAFFOLD
+AUTH_SCAFFOLDS = {
+    "memory": MEMORY_AUTH_SCAFFOLD,
+    "mongo": MONGO_AUTH_SCAFFOLD,
+    "postgres": POSTGRES_AUTH_SCAFFOLD,
+}
+
+
+@app.command("init")
+def init_command(
+    path: pathlib.Path = typer.Option(pathlib.Path("."), "--path", "-p"),  # noqa: B008
+    backend: str = typer.Option(
+        "memory",
+        "--backend",
+        "-b",
+        help="Scaffold backend: memory, mongo, or postgres",
+    ),
+) -> None:
+    """Scaffold an ``auth.py`` showing explicit FastAuthConfig construction."""
+    backend_key = backend.lower()
+    if backend_key not in AUTH_SCAFFOLDS:
+        rich_print("[red]--backend must be one of: memory, mongo, postgres[/red]")
+        raise typer.Exit(code=1)
+    path.mkdir(parents=True, exist_ok=True)
+    (path / "auth.py").write_text(AUTH_SCAFFOLDS[backend_key], encoding="utf-8")
+    rich_print(f"[green]wrote auth.py to {path}[/green]")
+
+
+@app.command("migrate")
+def migrate_command(
+    mongo_url: str | None = typer.Option(None, "--mongo-url", "-m", help="MongoDB connection URL"),
+    postgres_url: str | None = typer.Option(
+        None,
+        "--postgres-url",
+        help="Postgres connection URL, for example postgresql+asyncpg://...",
+    ),
+    database: str = typer.Option(
+        "fastauth",
+        "--database",
+        "-d",
+        help="MongoDB database name",
+    ),
+    postgres_table_prefix: str = typer.Option(
+        "fastauth_",
+        "--postgres-table-prefix",
+        help="Table prefix for Postgres schema creation",
+    ),
+) -> None:
+    """Initialise database schema/indexes for fastauth storage adapters.
+
+    Connection details are passed via CLI flags. fastauth does not read
+    them from the environment.
+    """
+    selected_backends = [mongo_url is not None, postgres_url is not None]
+    if sum(selected_backends) != 1:
+        rich_print("[red]Pass exactly one of --mongo-url or --postgres-url[/red]")
+        raise typer.Exit(code=1)
+
+    async def run() -> None:
+        if mongo_url is not None:
+            from motor.motor_asyncio import AsyncIOMotorClient
+
+            from fastauth.storage.beanie import init_beanie_documents
+
+            client: AsyncIOMotorClient[Any] = AsyncIOMotorClient(
+                mongo_url, uuidRepresentation="standard"
+            )
+            try:
+                await init_beanie_documents(client[database])
+                rich_print("[green]indexes ensured on every fastauth collection[/green]")
+            finally:
+                client.close()
+            return
+
+        from fastauth.storage.postgres import PostgresAdapter
+
+        assert postgres_url is not None
+        adapter = PostgresAdapter.from_url(postgres_url, table_prefix=postgres_table_prefix)
+        try:
+            applied = await adapter.apply_migrations()
+            version = await adapter.schema_version()
+            if applied:
+                rich_print(f"[green]Postgres migrations applied: {applied}[/green]")
+            else:
+                rich_print("[green]Postgres schema already current[/green]")
+            rich_print(f"[green]Postgres fastauth schema version: {version}[/green]")
+        finally:
+            await adapter.engine.dispose()
+
+    asyncio.run(run())
+
+
+@app.command("generate-secret")
+def generate_secret_command() -> None:
+    """Print a fresh 64-char URL-safe secret."""
+    rich_print(secrets.token_urlsafe(48))
+
+
+def cli() -> None:
+    app()

fastauth/config.py

@@ -0,0 +1,270 @@
+"""Pydantic configuration for fastauth.
+
+:class:`FastAuthConfig` is a plain Pydantic v2 ``BaseModel``. All values are
+passed explicitly at instantiation time, with Pydantic's validation enforced
+on construction. The framework has no notion of "environment variables" —
+reading from process-level configuration, files, AWS Secrets Manager,
+HashiCorp Vault, or any other source is the consumer's responsibility. Pass
+the values in as constructor arguments and fastauth will validate them.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+from fastauth.domain.enums import (
+    DatabaseBackendKind,
+    RateLimitStorageKind,
+    SessionStrategyKind,
+    WireFormat,
+)
+
+__all__ = [
+    "AdvancedConfig",
+    "AppConfig",
+    "CookieConfig",
+    "CsrfConfig",
+    "DatabaseConfig",
+    "DeleteAccountConfig",
+    "EmailChangeConfig",
+    "EmailConfig",
+    "EmailVerificationConfig",
+    "FastAuthConfig",
+    "LockoutConfig",
+    "MemoryDatabaseConfig",
+    "MongoDatabaseConfig",
+    "PasswordConfig",
+    "PasswordResetConfig",
+    "PostgresDatabaseConfig",
+    "RateLimitConfig",
+    "RefreshTokenConfig",
+    "SecurityHeadersConfig",
+    "SessionConfig",
+]
+
+
+class ConfigSection(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+
+class AppConfig(ConfigSection):
+    name: str = "fastauth"
+    base_url: str = "http://localhost:8000"
+    base_path: str = "/auth"
+
+
+class SessionConfig(ConfigSection):
+    strategy: SessionStrategyKind = SessionStrategyKind.DATABASE
+    max_age_seconds: int = 60 * 60 * 24 * 7
+    idle_timeout_seconds: int | None = None
+    rotate_on_refresh: bool = True
+
+
+class CookieConfig(ConfigSection):
+    name: str = "fastauth.session_token"
+    domain: str | None = None
+    path: str = "/"
+    secure: bool = True
+    http_only: bool = True
+    same_site: Literal["lax", "strict", "none"] = "lax"
+
+
+class PasswordConfig(ConfigSection):
+    min_length: int = 8
+    argon2_time_cost: int = 3
+    argon2_memory_cost_kib: int = 64 * 1024  # 64 MiB
+    argon2_parallelism: int = 4
+
+
+class EmailConfig(ConfigSection):
+    from_address: str = "no-reply@localhost"
+    from_name: str = "fastauth"
+    verification_subject: str = "Verify your email"
+    password_reset_subject: str = "Reset your password"  # noqa: S105
+    template_directory: str | None = None
+
+
+class EmailVerificationConfig(ConfigSection):
+    token_ttl_minutes: int = 15
+    require_verified_for_sign_in: bool = False
+    base_verify_url: str = "http://localhost:8000/auth/verify-email"
+
+
+class PasswordResetConfig(ConfigSection):
+    token_ttl_minutes: int = 30
+    base_reset_url: str = "http://localhost:8000/auth/reset-password"
+
+
+class EmailChangeConfig(ConfigSection):
+    token_ttl_minutes: int = 15
+    base_confirm_url: str = "http://localhost:8000/auth/change-email/confirm"
+    subject: str = "Confirm your new email address"
+
+
+class DeleteAccountConfig(ConfigSection):
+    token_ttl_minutes: int = 15
+    base_confirm_url: str = "http://localhost:8000/auth/delete-account/confirm"
+    subject: str = "Confirm account deletion"
+
+
+class RateLimitConfig(ConfigSection):
+    enabled: bool = True
+    window_seconds: int = 60
+    max_requests: int = 100
+    storage: RateLimitStorageKind = RateLimitStorageKind.MEMORY
+
+
+class CsrfConfig(ConfigSection):
+    enabled: bool = True
+    trusted_origins: list[str] = Field(default_factory=list)
+    allow_relative_paths: bool = True
+
+
+class LockoutConfig(ConfigSection):
+    """Account-lockout policy: lock an identifier after N failed sign-ins.
+
+    ``window_seconds`` doubles as the lockout duration — failures older than
+    the window are forgotten, and a triggered lockout naturally expires at the
+    same horizon. ``max_failures=5`` matches NIST 800-63B's guidance for
+    consumer auth (5 is the typical default in libraries like Devise and
+    fastapi-users); raise it for low-risk applications or to combat false
+    positives from shared NAT.
+    """
+
+    enabled: bool = True
+    max_failures: int = 5
+    window_seconds: int = 15 * 60
+
+
+class RefreshTokenConfig(ConfigSection):
+    """Long-lived refresh-token policy.
+
+    Refresh tokens piggyback on the bearer-token transport: when ``enabled``
+    is true (default) AND the sign-up / sign-in request opts into a bearer
+    response via ``include_token=true``, the response carries a
+    ``refresh_token`` that the client can later exchange at
+    ``POST /auth/refresh`` for a fresh access session. Cookie-only clients
+    (``include_token=false``) skip the refresh token entirely — their cookie
+    *is* the long-lived credential, so a separate refresh token would be
+    redundant.
+
+    Tokens are rotated on every use (one-time-use; OAuth 2.1 recommendation):
+    presenting a refresh token returns a *new* token and marks the old one
+    consumed. Presenting a previously-consumed token revokes the entire
+    rotation chain (theft-detection) — the user is forced to sign in again.
+
+    ``max_age_seconds`` defaults to 30 days. ``absolute_max_age_seconds``
+    caps the total lifetime of a single rotation chain — even with continuous
+    rotation, a chain expires after this many seconds since the initial
+    sign-in. Set to ``None`` to disable the absolute cap (rotation can extend
+    sessions indefinitely as long as the user is active).
+    """
+
+    enabled: bool = True
+    max_age_seconds: int = 30 * 24 * 60 * 60
+    absolute_max_age_seconds: int | None = None
+
+
+class SecurityHeadersConfig(ConfigSection):
+    """Response-header hardening (HSTS, frame-ancestors, MIME-sniffing, …).
+
+    Defaults match the OWASP Secure Headers Project's recommendations for a
+    typical SaaS web application. Every header is individually toggleable —
+    set ``hsts=None`` (etc.) to omit. The default ``hsts`` value
+    (``"max-age=31536000; includeSubDomains"``) is conservative; production
+    deployments preloaded into the HSTS preload list should add ``; preload``.
+
+    ``content_security_policy`` defaults to ``None`` because a meaningful CSP
+    is application-specific. Set it to a string and the middleware will emit
+    a ``Content-Security-Policy`` header verbatim.
+    """
+
+    enabled: bool = True
+    hsts: str | None = "max-age=31536000; includeSubDomains"
+    x_frame_options: str | None = "DENY"
+    x_content_type_options: str | None = "nosniff"
+    referrer_policy: str | None = "strict-origin-when-cross-origin"
+    permissions_policy: str | None = None
+    content_security_policy: str | None = None
+
+
+class MongoDatabaseConfig(ConfigSection):
+    url: str = "mongodb://localhost:27017"
+    database_name: str = "fastauth"
+
+
+class PostgresDatabaseConfig(ConfigSection):
+    url: str = "postgresql+asyncpg://localhost/fastauth"
+    table_prefix: str = "fastauth_"
+
+
+class MemoryDatabaseConfig(ConfigSection):
+    pass
+
+
+class DatabaseConfig(ConfigSection):
+    backend: DatabaseBackendKind = DatabaseBackendKind.MEMORY
+    memory: MemoryDatabaseConfig = Field(default_factory=MemoryDatabaseConfig)
+    mongo: MongoDatabaseConfig = Field(default_factory=MongoDatabaseConfig)
+    postgres: PostgresDatabaseConfig = Field(default_factory=PostgresDatabaseConfig)
+
+
+class AdvancedConfig(ConfigSection):
+    ip_address_headers: list[str] = Field(default_factory=lambda: ["x-forwarded-for"])
+    ipv6_subnet: int = 64
+    cookie_secure_prefix: bool = True
+
+
+def empty_secret_str_list() -> list[SecretStr]:
+    """Typed default factory for ``secret_key_rotation`` (keeps pyright strict happy)."""
+    return []
+
+
+class FastAuthConfig(BaseModel):
+    """Top-level fastauth configuration.
+
+    A plain Pydantic v2 ``BaseModel``. Construction validates the entire tree
+    eagerly. **The framework never reads process-level configuration or any
+    other external source** — every value comes from the constructor. Consumers
+    should read their chosen configuration source in their own code and pass
+    the values in explicitly.
+
+    Example::
+
+        from pydantic import SecretStr
+        from fastauth import FastAuth, FastAuthConfig
+        from fastauth.config import DatabaseConfig, MongoDatabaseConfig
+
+        config = FastAuthConfig(
+            secret_key=SecretStr("..."),
+            database=DatabaseConfig(
+                backend="mongo",
+                mongo=MongoDatabaseConfig(url="mongodb://localhost:27017"),
+            ),
+        )
+        auth = FastAuth(config, adapter=...)
+    """
+
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+    secret_key: SecretStr
+    secret_key_rotation: list[SecretStr] = Field(default_factory=empty_secret_str_list)
+    app: AppConfig = Field(default_factory=AppConfig)
+    session: SessionConfig = Field(default_factory=SessionConfig)
+    cookie: CookieConfig = Field(default_factory=CookieConfig)
+    password: PasswordConfig = Field(default_factory=PasswordConfig)
+    email: EmailConfig = Field(default_factory=EmailConfig)
+    email_verification: EmailVerificationConfig = Field(default_factory=EmailVerificationConfig)
+    password_reset: PasswordResetConfig = Field(default_factory=PasswordResetConfig)
+    email_change: EmailChangeConfig = Field(default_factory=EmailChangeConfig)
+    delete_account: DeleteAccountConfig = Field(default_factory=DeleteAccountConfig)
+    rate_limit: RateLimitConfig = Field(default_factory=RateLimitConfig)
+    csrf: CsrfConfig = Field(default_factory=CsrfConfig)
+    lockout: LockoutConfig = Field(default_factory=LockoutConfig)
+    refresh_token: RefreshTokenConfig = Field(default_factory=RefreshTokenConfig)
+    security_headers: SecurityHeadersConfig = Field(default_factory=SecurityHeadersConfig)
+    database: DatabaseConfig = Field(default_factory=DatabaseConfig)
+    advanced: AdvancedConfig = Field(default_factory=AdvancedConfig)
+    wire_format: WireFormat = WireFormat.SNAKE

fastauth/domain/enums.py

@@ -0,0 +1,125 @@
+"""Project-wide string enumerations. Every closed set of strings lives here."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+__all__ = [
+    "AuditEventType",
+    "DatabaseBackendKind",
+    "EmailMessageKind",
+    "HookPhase",
+    "JwtAlgorithm",
+    "ProviderId",
+    "RateLimitStorageKind",
+    "SessionStrategyKind",
+    "TokenType",
+    "VerificationPurpose",
+    "WireFormat",
+]
+
+
+class ProviderId(StrEnum):
+    CREDENTIAL = "credential"
+    EMAIL_OTP = "email-otp"
+
+
+class VerificationPurpose(StrEnum):
+    EMAIL_VERIFICATION = "email-verification"
+    PASSWORD_RESET = "password-reset"  # noqa: S105
+    EMAIL_CHANGE = "email-change"
+    ACCOUNT_DELETION = "account-deletion"
+    EMAIL_OTP_SIGN_IN = "email-otp-sign-in"
+    EMAIL_OTP_VERIFICATION = "email-otp-verification"
+    EMAIL_OTP_PASSWORD_RESET = "email-otp-password-reset"  # noqa: S105
+    EMAIL_OTP_EMAIL_CHANGE = "email-otp-email-change"
+
+
+class AuditEventType(StrEnum):
+    USER_SIGNED_UP = "user_signed_up"
+    USER_SIGNED_IN = "user_signed_in"
+    USER_SIGNED_OUT = "user_signed_out"
+    USER_EMAIL_VERIFIED = "user_email_verified"
+    USER_UPDATED = "user_updated"
+    USER_EMAIL_CHANGE_REQUESTED = "user_email_change_requested"
+    USER_EMAIL_CHANGED = "user_email_changed"
+    USER_DELETE_REQUESTED = "user_delete_requested"
+    USER_DELETED = "user_deleted"
+    SESSION_CREATED = "session_created"
+    SESSION_REVOKED = "session_revoked"
+    SESSIONS_REVOKED_ALL = "sessions_revoked_all"
+    ACCOUNT_LINKED = "account_linked"
+    ACCOUNT_UNLINKED = "account_unlinked"
+    PASSWORD_CHANGED = "password_changed"  # noqa: S105
+    PASSWORD_RESET_REQUESTED = "password_reset_requested"  # noqa: S105
+    PASSWORD_RESET_COMPLETED = "password_reset_completed"  # noqa: S105
+    EMAIL_VERIFICATION_SENT = "email_verification_sent"
+    API_KEY_CREATED = "api_key_created"
+    API_KEY_REVOKED = "api_key_revoked"
+    API_KEY_VERIFIED_FAILED = "api_key_verified_failed"
+    SECURITY_VELOCITY_EXCEEDED = "security_velocity_exceeded"
+    ACCOUNT_LOCKED = "account_locked"
+    OTP_REQUESTED = "otp_requested"
+    OTP_VERIFIED = "otp_verified"
+    OTP_VERIFY_FAILED = "otp_verify_failed"
+
+
+class SessionStrategyKind(StrEnum):
+    DATABASE = "database"
+    JWT = "jwt"
+
+
+class DatabaseBackendKind(StrEnum):
+    MEMORY = "memory"
+    MONGO = "mongo"
+    POSTGRES = "postgres"
+
+
+class WireFormat(StrEnum):
+    """JSON casing convention applied to public request / response bodies.
+
+    ``SNAKE`` (default) emits Pythonic ``snake_case`` field names — the
+    historical and back-compat behaviour. ``CAMEL`` emits ``camelCase``
+    (e.g. ``email_verified`` → ``emailVerified``, ``refresh_token`` →
+    ``refreshToken``).
+
+    Both casings are always **accepted** on input regardless of this
+    setting — toggling only affects output.
+    """
+
+    SNAKE = "snake"
+    CAMEL = "camel"
+
+
+class TokenType(StrEnum):
+    SESSION = "session"
+    VERIFICATION = "verification"
+    API_KEY = "api-key"
+
+
+class HookPhase(StrEnum):
+    BEFORE_CREATE = "before_create"
+    AFTER_CREATE = "after_create"
+    BEFORE_UPDATE = "before_update"
+    AFTER_UPDATE = "after_update"
+    BEFORE_DELETE = "before_delete"
+    AFTER_DELETE = "after_delete"
+
+
+class RateLimitStorageKind(StrEnum):
+    MEMORY = "memory"
+    DATABASE = "database"
+
+
+class EmailMessageKind(StrEnum):
+    VERIFICATION = "verification"
+    PASSWORD_RESET = "password-reset"  # noqa: S105
+    ACCOUNT_DELETION = "account-deletion"
+
+
+class JwtAlgorithm(StrEnum):
+    EDDSA = "EdDSA"
+    ES256 = "ES256"
+    RS256 = "RS256"
+    PS256 = "PS256"
+    ES512 = "ES512"