feature-standards-python-auth 0.2.0__tar.gz

feature_standards_python_auth-0.2.0/.gitignore

@@ -0,0 +1,22 @@
+.env
+.env.*
+!.env.example
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+node_modules/
+dist/
+test-results/
+playwright-report/
+.DS_Store
+*.log
+coverage.out
+eval-results/
+/implementations/go-net-http/go-net-http
+/examples/consumer-go/consumer-go
+/clients/react/lib/
+/clients/react/*.tgz
+bin/
+target/

feature_standards_python_auth-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jongko54
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

feature_standards_python_auth-0.2.0/PACKAGE.md

@@ -0,0 +1,23 @@
+# Feature Standards Python authentication
+
+Session authentication for FastAPI with a reusable application factory and authentication dependency. The implementation follows the same behavioral contracts as the project's Go, Java, Rust, and browser clients.
+
+```python
+from typing import Annotated
+from fastapi import Depends
+from feature_auth import create_app, current_user
+
+app = create_app()
+
+@app.get("/private")
+def private(user: Annotated[dict, Depends(current_user)]):
+    return {"user": user}
+```
+
+Python 3.12 or later is required. Configuration is read when the application lifespan starts. In-memory mode supports one configured user and process-local sessions. PostgreSQL mode adds shared persistent sessions; the optional account lifecycle profile adds registration, email verification, and password reset.
+
+For a loopback-only demo, explicitly set `AUTH_DEMO=true`, `AUTH_COOKIE_SECURE=false`, and `AUTH_ALLOWED_ORIGIN=http://127.0.0.1:5173`. Run Uvicorn with `--no-proxy-headers`. Demo credentials are `demo@example.com` / `correct-horse-battery-staple`; they are not production credentials.
+
+Database migrations and seeding are explicit repository tools. Installing or starting this package does not create tables or users. Production HTTPS, proxy policy, secrets, mail delivery, and operational controls require deployment-specific configuration.
+
+See the [source and integration guide](https://github.com/jongko54/feature-standards/tree/main/implementations/python-fastapi), [contracts](https://github.com/jongko54/feature-standards/tree/main/features/auth), and [security policy](https://github.com/jongko54/feature-standards/security/policy). Contract tests are not an independent security audit. MIT licensed.

feature_standards_python_auth-0.2.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.5
+Name: feature-standards-python-auth
+Version: 0.2.0
+Summary: Contract-tested session authentication for FastAPI
+Project-URL: Repository, https://github.com/jongko54/feature-standards
+Project-URL: Documentation, https://github.com/jongko54/feature-standards/tree/main/implementations/python-fastapi
+Project-URL: Issues, https://github.com/jongko54/feature-standards/issues
+Author: jongko54
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: argon2-cffi<26,>=25.1.0
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: psycopg[binary]<4,>=3.2
+Requires-Dist: uvicorn<1,>=0.34
+Description-Content-Type: text/markdown
+
+# Feature Standards Python authentication
+
+Session authentication for FastAPI with a reusable application factory and authentication dependency. The implementation follows the same behavioral contracts as the project's Go, Java, Rust, and browser clients.
+
+```python
+from typing import Annotated
+from fastapi import Depends
+from feature_auth import create_app, current_user
+
+app = create_app()
+
+@app.get("/private")
+def private(user: Annotated[dict, Depends(current_user)]):
+    return {"user": user}
+```
+
+Python 3.12 or later is required. Configuration is read when the application lifespan starts. In-memory mode supports one configured user and process-local sessions. PostgreSQL mode adds shared persistent sessions; the optional account lifecycle profile adds registration, email verification, and password reset.
+
+For a loopback-only demo, explicitly set `AUTH_DEMO=true`, `AUTH_COOKIE_SECURE=false`, and `AUTH_ALLOWED_ORIGIN=http://127.0.0.1:5173`. Run Uvicorn with `--no-proxy-headers`. Demo credentials are `demo@example.com` / `correct-horse-battery-staple`; they are not production credentials.
+
+Database migrations and seeding are explicit repository tools. Installing or starting this package does not create tables or users. Production HTTPS, proxy policy, secrets, mail delivery, and operational controls require deployment-specific configuration.
+
+See the [source and integration guide](https://github.com/jongko54/feature-standards/tree/main/implementations/python-fastapi), [contracts](https://github.com/jongko54/feature-standards/tree/main/features/auth), and [security policy](https://github.com/jongko54/feature-standards/security/policy). Contract tests are not an independent security audit. MIT licensed.

feature_standards_python_auth-0.2.0/feature_auth/__init__.py

@@ -0,0 +1,15 @@
+"""Reusable browser-session authentication for FastAPI."""
+
+from .core import AuthError, AuthService, AuthStore, Settings
+from .http import create_app, current_user
+from .memory import AuthState
+
+__all__ = [
+    "AuthError",
+    "AuthService",
+    "AuthState",
+    "AuthStore",
+    "Settings",
+    "create_app",
+    "current_user",
+]

feature_standards_python_auth-0.2.0/feature_auth/accounts.py

@@ -0,0 +1,36 @@
+"""v3 account input contract, independent of HTTP and PostgreSQL."""
+
+import re
+
+from .core import AuthError, normalize_email, valid_email
+
+ACCOUNT_ROUTES = {
+    "/auth/register": "register",
+    "/auth/email-verification/request": "verify-request",
+    "/auth/email-verification/confirm": "verify-confirm",
+    "/auth/password-reset/request": "reset-request",
+    "/auth/password-reset/confirm": "reset-confirm",
+}
+ACCOUNT_FIELDS = {
+    "register": {"email", "password"},
+    "verify-request": {"email"},
+    "verify-confirm": {"token"},
+    "reset-request": {"email"},
+    "reset-confirm": {"token", "password"},
+}
+
+
+def account_input(action: str, data: dict[str, str]) -> tuple[str, str, str]:
+    email = normalize_email(data.get("email", ""))
+    token = data.get("token", "")
+    password = data.get("password", "")
+    if (
+        (
+            "email" in data
+            and (not valid_email(email) or any(ord(c) <= 32 or ord(c) == 127 for c in email))
+        )
+        or ("token" in data and re.fullmatch(r"[A-Za-z0-9_-]{43}", token) is None)
+        or ("password" in data and not (len(password) >= 15 and len(password.encode()) <= 1024))
+    ):
+        raise AuthError(400, "INVALID_REQUEST")
+    return email, token, password

feature_standards_python_auth-0.2.0/feature_auth/core.py

@@ -0,0 +1,191 @@
+"""Shared configuration, storage protocol and authentication service."""
+
+from __future__ import annotations
+
+import ipaddress
+import os
+from dataclasses import dataclass, field, replace
+from typing import Protocol
+from urllib.parse import urlsplit
+
+COOKIE_NAME = "fs_session"
+MAX_BODY_BYTES = 4096
+DEMO_EMAIL = "demo@example.com"
+DEMO_PASSWORD = "correct-horse-battery-staple"
+ASCII_EMAIL_WHITESPACE = "\t\n\v\f\r "
+ASCII_EMAIL_LOWERCASE = str.maketrans("ABCDEFGHIJKLMNOPQRSTUVWXYZ", "abcdefghijklmnopqrstuvwxyz")
+
+
+def normalize_email(email: str) -> str:
+    """Unicode 테이블과 무관하게 계약의 ASCII 정규화만 수행한다."""
+    return email.strip(ASCII_EMAIL_WHITESPACE).translate(ASCII_EMAIL_LOWERCASE)
+
+
+def env_bool(name: str, default: bool) -> bool:
+    value = os.environ.get(name, str(default).lower())
+    if value not in ("true", "false"):
+        raise ValueError(f"{name} must be true or false")
+    return value == "true"
+
+
+def env_positive_int(name: str, default: int) -> int:
+    raw = os.environ.get(name, str(default))
+    if not raw.isascii() or not raw.isdecimal() or int(raw) <= 0:
+        raise ValueError(f"{name} must be a positive integer")
+    return int(raw)
+
+
+def valid_email(email: str) -> bool:
+    return "@" in email and 0 < len(email.encode("utf-8")) <= 254
+
+
+def is_loopback(host: str) -> bool:
+    if host == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+@dataclass(frozen=True)
+class Settings:
+    demo: bool
+    email: str
+    password: str = field(repr=False)
+    origin: str = "http://127.0.0.1:5173"
+    secure_cookie: bool = True
+    session_ttl: int = 1800
+    rate_limit_max: int = 5
+    rate_limit_window: int = 60
+    store: str = "memory"
+    database_url: str = field(default="", repr=False)
+    account_lifecycle: bool = False
+
+    @classmethod
+    def from_env(cls) -> Settings:
+        store = os.environ.get("AUTH_STORE", "memory")
+        if store not in ("memory", "postgres"):
+            raise ValueError("AUTH_STORE must be memory or postgres")
+        account_lifecycle = env_bool("AUTH_ACCOUNT_LIFECYCLE", False)
+        if account_lifecycle and store != "postgres":
+            raise ValueError("AUTH_ACCOUNT_LIFECYCLE requires postgres storage")
+        database_url = os.environ.get("AUTH_DATABASE_URL", "") if store == "postgres" else ""
+        if store == "postgres" and not database_url.startswith(("postgresql://", "postgres://")):
+            raise ValueError("AUTH_DATABASE_URL must be a PostgreSQL URI")
+        demo = env_bool("AUTH_DEMO", False)
+        origin = os.environ.get("AUTH_ALLOWED_ORIGIN", "http://127.0.0.1:5173")
+        secure = env_bool("AUTH_COOKIE_SECURE", True)
+        parsed = urlsplit(origin)
+        try:
+            port = parsed.port
+        except ValueError as exc:
+            raise ValueError("AUTH_ALLOWED_ORIGIN has an invalid port") from exc
+        if (
+            parsed.scheme not in ("http", "https")
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.path
+            or parsed.query
+            or parsed.fragment
+            or origin != f"{parsed.scheme}://{parsed.netloc}"
+            or "*" in origin
+            or any(char.isspace() for char in origin)
+            or (port is not None and not 1 <= port <= 65535)
+        ):
+            raise ValueError("AUTH_ALLOWED_ORIGIN must be an exact HTTP(S) origin")
+        if not demo and parsed.scheme != "https":
+            raise ValueError("Non-demo mode requires an HTTPS origin")
+        if not secure and not (demo and is_loopback(parsed.hostname)):
+            raise ValueError("Insecure cookies require demo mode with a loopback origin")
+        email, password = "", ""
+        if store == "memory":
+            email = DEMO_EMAIL if demo else normalize_email(os.environ.get("AUTH_USER_EMAIL", ""))
+            password = DEMO_PASSWORD if demo else os.environ.get("AUTH_USER_PASSWORD", "")
+        try:
+            valid_credentials = valid_email(email) and 1 <= len(password.encode("utf-8")) <= 1024
+        except UnicodeError:
+            valid_credentials = False
+        if store == "memory" and not valid_credentials:
+            raise ValueError("A valid AUTH_USER_EMAIL and AUTH_USER_PASSWORD are required")
+        env_positive_int("AUTH_PORT", 8000)
+        if int(os.environ.get("AUTH_PORT", "8000")) > 65535:
+            raise ValueError("AUTH_PORT must be at most 65535")
+        return cls(
+            store=store,
+            database_url=database_url,
+            account_lifecycle=account_lifecycle,
+            demo=demo,
+            email=email,
+            password=password,
+            origin=origin,
+            secure_cookie=secure,
+            session_ttl=env_positive_int("AUTH_SESSION_TTL_SECONDS", 1800),
+            rate_limit_max=env_positive_int("AUTH_RATE_LIMIT_MAX", 5),
+            rate_limit_window=env_positive_int("AUTH_RATE_LIMIT_WINDOW_SECONDS", 60),
+        )
+
+
+@dataclass(frozen=True)
+class Session:
+    csrf: str
+    expires_at: float
+    user: dict[str, str] | None = None
+
+
+@dataclass
+class FailureWindow:
+    count: int
+    expires_at: float
+
+
+class AuthError(Exception):
+    def __init__(self, status: int, code: str, headers: dict[str, str] | None = None):
+        self.status = status
+        self.code = code
+        self.headers = headers
+
+
+class AuthStore(Protocol):
+    """Atomic authentication operations; HTTP adapters never handle SQL."""
+
+    def authenticate(
+        self, peer: str, email: str, password: str, old_token: str
+    ) -> tuple[str, Session]: ...
+    def get_session(self, token: str) -> Session | None: ...
+    def logout(self, token: str, csrf: str) -> None: ...
+    def health(self) -> None: ...
+    def close(self) -> None: ...
+
+
+class AuthService:
+    def __init__(self, settings: Settings, store: AuthStore):
+        self.settings = replace(settings, password="", database_url="")
+        self.store = store
+        self.profile = (
+            "browser-session-v3"
+            if settings.account_lifecycle
+            else ("browser-session-v2" if settings.store == "postgres" else "browser-session-v1")
+        )
+
+    def account(self, action: str, peer: str, email: str, token: str, password: str):
+        handler = getattr(self.store, "account", None)
+        if not self.settings.account_lifecycle or handler is None:
+            raise AuthError(404, "NOT_FOUND")
+        return handler(action, peer, email, token, password)
+
+    def authenticate(self, peer: str, email: str, password: str, old_token: str):
+        return self.store.authenticate(peer, email, password, old_token)
+
+    def get_session(self, token: str):
+        return self.store.get_session(token)
+
+    def logout(self, token: str, csrf: str):
+        return self.store.logout(token, csrf)
+
+    def payload(self, session: Session) -> dict:
+        return {
+            "user": session.user or {"id": "demo-user", "email": self.settings.email},
+            "csrfToken": session.csrf,
+        }

feature_standards_python_auth-0.2.0/feature_auth/http.py

@@ -0,0 +1,231 @@
+"""FastAPI routes; authentication storage is injected through the service."""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse, Response
+from starlette.concurrency import run_in_threadpool
+from starlette.exceptions import HTTPException
+
+from .accounts import ACCOUNT_FIELDS, ACCOUNT_ROUTES, account_input
+from .core import (
+    COOKIE_NAME,
+    MAX_BODY_BYTES,
+    AuthError,
+    AuthService,
+    AuthStore,
+    Settings,
+    normalize_email,
+    valid_email,
+)
+from .service import build_service
+
+
+def error_response(status: int, code: str, headers: dict | None = None) -> JSONResponse:
+    response_headers = {"Cache-Control": "no-store", "X-Content-Type-Options": "nosniff"}
+    response_headers.update(headers or {})
+    return JSONResponse(
+        status_code=status,
+        content={"error": {"code": code, "message": code.replace("_", " ").lower()}},
+        headers=response_headers,
+    )
+
+
+def require_origin(request: Request, settings: Settings) -> None:
+    if request.headers.getlist("origin") != [settings.origin]:
+        raise AuthError(403, "ORIGIN_DENIED")
+
+
+def unique_object(pairs: list[tuple[str, object]]) -> dict:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("Duplicate JSON key")
+        result[key] = value
+    return result
+
+
+def invalid_constant(value: str) -> None:
+    raise ValueError("Invalid JSON constant")
+
+
+async def read_object(request: Request, fields: set[str]) -> dict[str, str]:
+    media_type = request.headers.get("content-type", "").split(";", 1)[0].strip().lower()
+    if media_type != "application/json":
+        raise AuthError(415, "UNSUPPORTED_MEDIA_TYPE")
+    body = bytearray()
+    async for chunk in request.stream():
+        body.extend(chunk)
+        if len(body) > MAX_BODY_BYTES:
+            raise AuthError(413, "REQUEST_TOO_LARGE")
+    try:
+        data = json.loads(
+            body.decode("utf-8"), object_pairs_hook=unique_object, parse_constant=invalid_constant
+        )
+        if not isinstance(data, dict) or set(data) != fields:
+            raise ValueError("Invalid object")
+        if any(not isinstance(value, str) for value in data.values()):
+            raise ValueError("Invalid field type")
+        for value in data.values():
+            value.encode("utf-8")
+        return data
+    except (ValueError, UnicodeError, RecursionError) as exc:
+        raise AuthError(400, "INVALID_REQUEST") from exc
+
+
+async def read_credentials(request: Request) -> tuple[str, str]:
+    data = await read_object(request, {"email", "password"})
+    try:
+        email = normalize_email(data["email"])
+        password = data["password"]
+        if not valid_email(email) or not 1 <= len(password.encode("utf-8")) <= 1024:
+            raise ValueError("Invalid field length")
+        return email, password
+    except (ValueError, UnicodeError, RecursionError) as exc:
+        raise AuthError(400, "INVALID_REQUEST") from exc
+
+
+def current_user(request: Request) -> dict[str, str]:
+    """Return the current user, also usable as Depends(current_user)."""
+    state: AuthService = request.app.state.auth
+    session = state.get_session(request.cookies.get(COOKIE_NAME, ""))
+    if session is None:
+        raise AuthError(401, "UNAUTHENTICATED")
+    return state.payload(session)["user"]
+
+
+def create_app(
+    *,
+    settings: Settings | None = None,
+    clock: Callable[[], float] = time.monotonic,
+    store: AuthStore | None = None,
+) -> FastAPI:
+    @asynccontextmanager
+    async def lifespan(application: FastAPI):
+        application.state.auth = await run_in_threadpool(
+            build_service, settings or Settings.from_env(), store, clock
+        )
+        try:
+            yield
+        finally:
+            await run_in_threadpool(application.state.auth.store.close)
+
+    application = FastAPI(
+        title="Feature Standards Auth",
+        lifespan=lifespan,
+        docs_url=None,
+        redoc_url=None,
+        openapi_url=None,
+        redirect_slashes=False,
+    )
+
+    @application.middleware("http")
+    async def auth_headers(request: Request, call_next):
+        if (
+            request.url.path in ACCOUNT_ROUTES
+            and not request.app.state.auth.settings.account_lifecycle
+        ):
+            return error_response(404, "NOT_FOUND")
+        response = await call_next(request)
+        if request.url.path.startswith("/auth/"):
+            response.headers["Cache-Control"] = "no-store"
+            response.headers["X-Content-Type-Options"] = "nosniff"
+        return response
+
+    @application.exception_handler(AuthError)
+    async def handle_auth_error(request: Request, error: AuthError):
+        return error_response(error.status, error.code, error.headers)
+
+    @application.exception_handler(HTTPException)
+    async def handle_http_error(request: Request, error: HTTPException):
+        code = {404: "NOT_FOUND", 405: "METHOD_NOT_ALLOWED"}.get(error.status_code, "HTTP_ERROR")
+        return error_response(error.status_code, code, error.headers)
+
+    @application.exception_handler(Exception)
+    async def handle_internal_error(request: Request, error: Exception):
+        return error_response(500, "INTERNAL_ERROR")
+
+    @application.get("/healthz")
+    def healthz(request: Request):
+        state = request.app.state.auth
+        state.store.health()
+        return {"status": "ok", "profile": state.profile, "implementation": "python-fastapi"}
+
+    @application.post("/auth/login")
+    async def login(request: Request):
+        state: AuthService = request.app.state.auth
+        require_origin(request, state.settings)
+        email, password = await read_credentials(request)
+        token, session = await run_in_threadpool(
+            state.authenticate,
+            request.client.host if request.client else "unknown",
+            email,
+            password,
+            request.cookies.get(COOKIE_NAME, ""),
+        )
+        response = JSONResponse(state.payload(session))
+        response.set_cookie(
+            COOKIE_NAME,
+            token,
+            max_age=state.settings.session_ttl,
+            path="/",
+            secure=state.settings.secure_cookie,
+            httponly=True,
+            samesite="lax",
+        )
+        return response
+
+    @application.get("/auth/me")
+    def me(request: Request):
+        state: AuthService = request.app.state.auth
+        session = state.get_session(request.cookies.get(COOKIE_NAME, ""))
+        if session is None:
+            raise AuthError(401, "UNAUTHENTICATED")
+        return state.payload(session)
+
+    @application.post("/auth/logout")
+    def logout(request: Request):
+        state: AuthService = request.app.state.auth
+        require_origin(request, state.settings)
+        csrf_headers = request.headers.getlist("x-csrf-token")
+        csrf = csrf_headers[0] if len(csrf_headers) == 1 else ""
+        state.logout(request.cookies.get(COOKIE_NAME, ""), csrf)
+        response = Response(status_code=204)
+        response.delete_cookie(
+            COOKIE_NAME,
+            path="/",
+            secure=state.settings.secure_cookie,
+            httponly=True,
+            samesite="lax",
+        )
+        return response
+
+    def account_endpoint(action: str):
+        async def endpoint(request: Request):
+            state: AuthService = request.app.state.auth
+            require_origin(request, state.settings)
+            data = await read_object(request, ACCOUNT_FIELDS[action])
+            email, token, password = account_input(action, data)
+            await run_in_threadpool(
+                state.account,
+                action,
+                request.client.host if request.client else "unknown",
+                email,
+                token,
+                password,
+            )
+            if action.endswith("confirm"):
+                return Response(status_code=204)
+            return JSONResponse({"status": "accepted"}, status_code=202)
+
+        return endpoint
+
+    for path, action in ACCOUNT_ROUTES.items():
+        application.add_api_route(path, account_endpoint(action), methods=["POST"])
+
+    return application

feature_standards_python_auth-0.2.0/feature_auth/memory.py

@@ -0,0 +1,90 @@
+"""The original process-local v1 adapter."""
+
+from __future__ import annotations
+
+import hmac
+import math
+import secrets
+import threading
+from collections.abc import Callable
+from dataclasses import replace
+
+from argon2 import PasswordHasher
+from argon2.exceptions import VerifyMismatchError
+
+from .core import AuthError, FailureWindow, Session, Settings
+
+
+class AuthState:
+    def __init__(self, settings: Settings, clock: Callable[[], float]):
+        self.clock = clock
+        self.hasher = PasswordHasher()
+        self.password_hash = self.hasher.hash(settings.password)
+        self.settings = replace(settings, password="")
+        self.sessions: dict[str, Session] = {}
+        self.failures: dict[str, FailureWindow] = {}
+        self.lock = threading.RLock()
+
+    def _prune(self, now: float) -> None:
+        self.sessions = {
+            token: session for token, session in self.sessions.items() if session.expires_at > now
+        }
+        self.failures = {
+            peer: window for peer, window in self.failures.items() if window.expires_at > now
+        }
+
+    def authenticate(
+        self, peer: str, email: str, password: str, old_token: str
+    ) -> tuple[str, Session]:
+        # 해싱을 직렬화해 병렬 로그인 메모리 폭증과 실패 횟수 경합 우회를 막는다.
+        with self.lock:
+            now = self.clock()
+            self._prune(now)
+            failure = self.failures.get(peer)
+            if failure is not None and failure.count >= self.settings.rate_limit_max:
+                retry_after = max(1, math.ceil(failure.expires_at - now))
+                raise AuthError(429, "RATE_LIMITED", {"Retry-After": str(retry_after)})
+            try:
+                password_matches = self.hasher.verify(self.password_hash, password)
+            except VerifyMismatchError:
+                password_matches = False
+            email_matches = hmac.compare_digest(email.encode(), self.settings.email.encode())
+            if not password_matches or not email_matches:
+                if failure is None:
+                    self.failures[peer] = FailureWindow(1, now + self.settings.rate_limit_window)
+                else:
+                    failure.count += 1
+                raise AuthError(401, "INVALID_CREDENTIALS")
+            self.failures.pop(peer, None)
+            self.sessions.pop(old_token, None)
+            token = secrets.token_urlsafe(32)
+            session = Session(secrets.token_urlsafe(32), self.clock() + self.settings.session_ttl)
+            self.sessions[token] = session
+            return token, session
+
+    def get_session(self, token: str) -> Session | None:
+        with self.lock:
+            self._prune(self.clock())
+            return self.sessions.get(token)
+
+    def logout(self, token: str, csrf: str) -> None:
+        with self.lock:
+            self._prune(self.clock())
+            session = self.sessions.get(token)
+            if session is not None:
+                if not hmac.compare_digest(csrf.encode("utf-8"), session.csrf.encode("utf-8")):
+                    raise AuthError(403, "CSRF_INVALID")
+                del self.sessions[token]
+
+    def health(self) -> None:
+        pass
+
+    def close(self) -> None:
+        self.sessions.clear()
+        self.failures.clear()
+
+    def payload(self, session: Session) -> dict:
+        return {
+            "user": session.user or {"id": "demo-user", "email": self.settings.email},
+            "csrfToken": session.csrf,
+        }

feature_standards_python_auth-0.2.0/feature_auth/postgres.py

@@ -0,0 +1,215 @@
+"""PostgreSQL adapter. Transactions complete before values reach the HTTP layer."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import math
+import re
+import secrets
+from contextlib import contextmanager
+
+import psycopg
+from argon2 import PasswordHasher
+from argon2.exceptions import InvalidHashError, VerificationError, VerifyMismatchError
+
+from .core import AuthError, Session, Settings
+
+PHC = re.compile(r"^\$argon2id\$v=19\$m=65536,t=3,p=4\$([A-Za-z0-9+/]{22})\$([A-Za-z0-9+/]{43})$")
+
+
+def valid_phc(value: str) -> bool:
+    match = PHC.fullmatch(value)
+    if not match:
+        return False
+    try:
+        salt, digest = (
+            base64.b64decode(part + "=" * (-len(part) % 4), validate=True)
+            for part in match.groups()
+        )
+        return (
+            len(salt) == 16
+            and len(digest) == 32
+            and base64.b64encode(salt).decode().rstrip("=") == match[1]
+            and base64.b64encode(digest).decode().rstrip("=") == match[2]
+        )
+    except ValueError:
+        return False
+
+
+def token_hash(token: str) -> bytes:
+    return hashlib.sha256(token.encode("utf-8")).digest()
+
+
+class PostgresStore:
+    def __init__(self, settings: Settings):
+        if not settings.database_url.startswith(("postgresql://", "postgres://")):
+            raise ValueError("AUTH_DATABASE_URL must be a PostgreSQL URI")
+        self._url = settings.database_url
+        self.ttl = settings.session_ttl
+        self.limit = settings.rate_limit_max
+        self.window = settings.rate_limit_window
+        self.account_lifecycle = settings.account_lifecycle
+        self.hasher = PasswordHasher(
+            time_cost=3, memory_cost=65536, parallelism=4, salt_len=16, hash_len=32
+        )
+        self._dummy = self.hasher.hash(secrets.token_urlsafe(32))
+        try:
+            self.health()
+        except AuthError:
+            raise ValueError(
+                "PostgreSQL authentication storage is unavailable or incompatible"
+            ) from None
+
+    @contextmanager
+    def _connection(self):
+        try:
+            # Each operation owns its connection and transaction; no thread shares one.
+            with psycopg.connect(
+                self._url,
+                connect_timeout=3,
+                options="-c statement_timeout=10000 -c lock_timeout=8000",
+            ) as conn:
+                yield conn
+        except psycopg.Error:
+            raise AuthError(503, "STORAGE_UNAVAILABLE") from None
+
+    def health(self) -> None:
+        with self._connection() as conn:
+            rows = conn.execute("SELECT version FROM feature_auth.schema_version").fetchall()
+            if rows != [(2 if self.account_lifecycle else 1,)]:
+                raise AuthError(503, "STORAGE_UNAVAILABLE")
+
+    def close(self) -> None:
+        pass
+
+    def account(self, action: str, peer: str, email: str, token: str, password: str) -> None:
+        if not self.account_lifecycle:
+            raise AuthError(404, "NOT_FOUND")
+        with self._connection() as conn:
+            outcome = conn.execute(
+                "SELECT feature_auth.account_reserve(%s,%s)", (action, peer)
+            ).fetchone()[0]
+            if not isinstance(outcome, int) or outcome < 0:
+                raise AuthError(503, "STORAGE_UNAVAILABLE")
+            if outcome == 0:
+                # Reserve the peer budget in this transaction before allocating Argon2 memory.
+                encoded = self.hasher.hash(password) if password else ""
+                if action in ("register", "verify-request", "reset-request"):
+                    token = secrets.token_urlsafe(32)
+                outcome = conn.execute(
+                    "SELECT feature_auth.account_apply(%s,%s,%s,%s,%s)",
+                    (action, peer, email, token, encoded),
+                ).fetchone()[0]
+        # The connection context commits before any semantic outcome reaches HTTP.
+        if not isinstance(outcome, int):
+            raise AuthError(503, "STORAGE_UNAVAILABLE")
+        if outcome == -1:
+            raise AuthError(400, "INVALID_TOKEN")
+        if outcome > 0:
+            raise AuthError(429, "RATE_LIMITED", {"Retry-After": str(outcome)})
+        if outcome != 0:
+            raise AuthError(503, "STORAGE_UNAVAILABLE")
+
+    def authenticate(self, peer: str, email: str, password: str, old_token: str):
+        outcome = None
+        result = None
+        with self._connection() as conn:
+            conn.execute(
+                "SELECT pg_advisory_xact_lock(20261102, hashtext(host(CAST(%s AS inet))))", (peer,)
+            )
+            now = conn.execute("SELECT clock_timestamp()").fetchone()[0]
+            conn.execute(
+                "DELETE FROM feature_auth.login_attempts "
+                "WHERE peer = CAST(%s AS inet) AND expires_at <= %s",
+                (peer, now),
+            )
+            attempt = conn.execute(
+                "SELECT failures, expires_at FROM feature_auth.login_attempts "
+                "WHERE peer = CAST(%s AS inet)",
+                (peer,),
+            ).fetchone()
+            if attempt and attempt[0] >= self.limit:
+                retry = max(1, math.ceil((attempt[1] - now).total_seconds()))
+                outcome = AuthError(429, "RATE_LIMITED", {"Retry-After": str(retry)})
+            else:
+                user = conn.execute(
+                    "SELECT id, email, password_hash, enabled "
+                    "FROM feature_auth.users WHERE email = %s FOR SHARE",
+                    (email,),
+                ).fetchone()
+                encoded = user[2] if user else self._dummy
+                if not valid_phc(encoded):
+                    raise AuthError(503, "STORAGE_UNAVAILABLE")
+                try:
+                    matches = self.hasher.verify(encoded, password)
+                except VerifyMismatchError:
+                    matches = False
+                except (InvalidHashError, VerificationError):
+                    raise AuthError(503, "STORAGE_UNAVAILABLE") from None
+                if not matches or not user or not user[3]:
+                    conn.execute(
+                        """INSERT INTO feature_auth.login_attempts(peer, failures, expires_at)
+                        VALUES (CAST(%s AS inet), 1, %s + %s * interval '1 second')
+                        ON CONFLICT (peer) DO UPDATE
+                        SET failures = feature_auth.login_attempts.failures + 1""",
+                        (peer, now, self.window),
+                    )
+                    outcome = AuthError(401, "INVALID_CREDENTIALS")
+                else:
+                    conn.execute(
+                        "DELETE FROM feature_auth.login_attempts WHERE peer = CAST(%s AS inet)",
+                        (peer,),
+                    )
+                    conn.execute(
+                        "DELETE FROM feature_auth.sessions WHERE token_hash = %s",
+                        (token_hash(old_token),),
+                    )
+                    token, csrf = secrets.token_urlsafe(32), secrets.token_urlsafe(32)
+                    # Read DB time after hashing so TTL begins at session creation.
+                    expires = conn.execute(
+                        """INSERT INTO feature_auth.sessions
+                        (token_hash,user_id,csrf_token,created_at,expires_at)
+                        SELECT %s,%s,%s,t,t + %s * interval '1 second'
+                        FROM (SELECT clock_timestamp() AS t) AS clock
+                        RETURNING expires_at""",
+                        (token_hash(token), user[0], csrf, self.ttl),
+                    ).fetchone()[0]
+                    result = (
+                        token,
+                        Session(csrf, expires.timestamp(), {"id": user[0], "email": user[1]}),
+                    )
+        # Raising inside the transaction would roll back the failed-attempt counter.
+        if outcome:
+            raise outcome
+        return result
+
+    def get_session(self, token: str) -> Session | None:
+        with self._connection() as conn:
+            row = conn.execute(
+                """SELECT s.csrf_token,s.expires_at,u.id,u.email
+                FROM feature_auth.sessions s JOIN feature_auth.users u ON u.id=s.user_id
+                WHERE s.token_hash=%s AND s.expires_at > clock_timestamp() AND u.enabled""",
+                (token_hash(token),),
+            ).fetchone()
+            if row:
+                return Session(row[0], row[1].timestamp(), {"id": row[2], "email": row[3]})
+        return None
+
+    def logout(self, token: str, csrf: str) -> None:
+        with self._connection() as conn:
+            digest = token_hash(token)
+            row = conn.execute(
+                "SELECT csrf_token,expires_at FROM feature_auth.sessions "
+                "WHERE token_hash=%s FOR UPDATE",
+                (digest,),
+            ).fetchone()
+            now = conn.execute("SELECT clock_timestamp()").fetchone()[0]
+            if (
+                row
+                and row[1] > now
+                and not hmac.compare_digest(csrf.encode("utf-8"), row[0].encode("utf-8"))
+            ):
+                raise AuthError(403, "CSRF_INVALID")
+            conn.execute("DELETE FROM feature_auth.sessions WHERE token_hash=%s", (digest,))

feature_standards_python_auth-0.2.0/feature_auth/service.py

@@ -0,0 +1,22 @@
+"""Composition root for the interchangeable store adapters."""
+
+from collections.abc import Callable
+
+from .core import AuthService, AuthStore, Settings
+
+
+def build_service(settings: Settings, store: AuthStore | None, clock: Callable[[], float]):
+    if settings.store not in ("memory", "postgres"):
+        raise ValueError("AUTH_STORE must be memory or postgres")
+    if settings.account_lifecycle and settings.store != "postgres":
+        raise ValueError("AUTH_ACCOUNT_LIFECYCLE requires postgres storage")
+    if store is None:
+        if settings.store == "postgres":
+            from .postgres import PostgresStore
+
+            store = PostgresStore(settings)
+        else:
+            from .memory import AuthState
+
+            store = AuthState(settings, clock)
+    return AuthService(settings, store)

feature_standards_python_auth-0.2.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "feature-standards-python-auth"
+version = "0.2.0"
+description = "Contract-tested session authentication for FastAPI"
+readme = "PACKAGE.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "jongko54"}]
+requires-python = ">=3.12"
+dependencies = [
+  "argon2-cffi>=25.1.0,<26",
+  "fastapi>=0.115,<1",
+  "uvicorn>=0.34,<1",
+  "psycopg[binary]>=3.2,<4",
+]
+
+[project.urls]
+Repository = "https://github.com/jongko54/feature-standards"
+Documentation = "https://github.com/jongko54/feature-standards/tree/main/implementations/python-fastapi"
+Issues = "https://github.com/jongko54/feature-standards/issues"
+
+[dependency-groups]
+dev = [
+    "httpx2>=2.16.0,<3",
+    "pytest>=8,<10",
+    "ruff>=0.12,<1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["feature_auth"]
+
+[tool.hatch.build.targets.sdist]
+include = ["feature_auth", "pyproject.toml", "PACKAGE.md", "LICENSE"]