regstack 0.1.0__py3-none-any.whl

regstack/__init__.py

@@ -0,0 +1,5 @@
+from regstack.app import RegStack
+from regstack.config.schema import EmailConfig, RegStackConfig, SmsConfig
+from regstack.version import __version__
+
+__all__ = ["EmailConfig", "RegStack", "RegStackConfig", "SmsConfig", "__version__"]

regstack/app.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from fastapi.staticfiles import StaticFiles
+
+from regstack.auth.clock import Clock, SystemClock
+from regstack.auth.dependencies import AuthDependencies
+from regstack.auth.jwt import JwtCodec
+from regstack.auth.lockout import LockoutService
+from regstack.auth.password import PasswordHasher
+from regstack.config.schema import RegStackConfig
+from regstack.db.indexes import install_indexes as _install_indexes
+from regstack.db.repositories.blacklist_repo import BlacklistRepo
+from regstack.db.repositories.login_attempt_repo import LoginAttemptRepo
+from regstack.db.repositories.mfa_code_repo import MfaCodeRepo
+from regstack.db.repositories.pending_repo import PendingRepo
+from regstack.db.repositories.user_repo import UserRepo
+from regstack.email.base import EmailService
+from regstack.email.composer import MailComposer
+from regstack.email.factory import build_email_service
+from regstack.hooks.events import HookRegistry
+from regstack.models.user import BaseUser
+from regstack.routers import build_router
+from regstack.sms.base import SmsService
+from regstack.sms.factory import build_sms_service
+from regstack.ui.pages import build_ui_environment, build_ui_router, default_static_dir
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from fastapi import APIRouter
+    from jinja2 import Environment
+    from pymongo.asynchronous.database import AsyncDatabase
+
+
+class RegStack:
+    """Embeddable account-management module.
+
+    Hosts construct one of these per FastAPI application, then mount
+    ``regstack.router`` with ``app.include_router(regstack.router, prefix=...)``.
+    """
+
+    def __init__(
+        self,
+        *,
+        config: RegStackConfig,
+        db: AsyncDatabase,
+        clock: Clock | None = None,
+        email_service: EmailService | None = None,
+        mail_composer: MailComposer | None = None,
+        sms_service: SmsService | None = None,
+    ) -> None:
+        self.config = config
+        self.db = db
+        self.clock: Clock = clock or SystemClock()
+        self.password_hasher = PasswordHasher()
+        self.jwt = JwtCodec(config, self.clock)
+        self.users = UserRepo(db, config.user_collection, clock=self.clock)
+        self.pending = PendingRepo(db, config.pending_collection)
+        self.blacklist = BlacklistRepo(db, config.blacklist_collection)
+        self.attempts = LoginAttemptRepo(db, config.login_attempt_collection)
+        self.mfa_codes = MfaCodeRepo(db, config.mfa_code_collection, clock=self.clock)
+        self.lockout = LockoutService(attempts=self.attempts, config=config, clock=self.clock)
+        self.email: EmailService = email_service or build_email_service(config.email)
+        self.sms: SmsService = sms_service or build_sms_service(config.sms)
+        self.mail = mail_composer or MailComposer(
+            email_config=config.email,
+            app_name=config.app_name,
+        )
+        self.hooks = HookRegistry()
+        self.deps = AuthDependencies(jwt=self.jwt, users=self.users, blacklist=self.blacklist)
+        self._template_dirs: list[Path] = list(config.extra_template_dirs)
+        self._ui_env: Environment | None = None
+        self._router: APIRouter | None = None
+        self._ui_router: APIRouter | None = None
+        self._static_files: StaticFiles | None = None
+
+    @property
+    def router(self) -> APIRouter:
+        if self._router is None:
+            self._router = build_router(self)
+        return self._router
+
+    @property
+    def ui_env(self) -> Environment:
+        if self._ui_env is None:
+            self._ui_env = build_ui_environment(self._template_dirs)
+        return self._ui_env
+
+    @property
+    def ui_router(self) -> APIRouter:
+        if self._ui_router is None:
+            self._ui_router = build_ui_router(self)
+        return self._ui_router
+
+    @property
+    def static_files(self) -> StaticFiles:
+        """Bundled CSS / JS — host mounts at ``config.static_prefix``."""
+        if self._static_files is None:
+            self._static_files = StaticFiles(directory=str(default_static_dir()))
+        return self._static_files
+
+    # --- Lifecycle -------------------------------------------------------
+
+    async def install_indexes(self) -> None:
+        await _install_indexes(self.db, self.config)
+
+    async def bootstrap_admin(self, email: str, password: str) -> BaseUser:
+        """Create a verified superuser if none exists for the given email."""
+        existing = await self.users.get_by_email(email)
+        if existing is not None:
+            if not existing.is_superuser:
+                assert existing.id is not None
+                await self.users.set_superuser(existing.id, is_superuser=True)
+                existing.is_superuser = True
+            return existing
+        user = BaseUser(
+            email=email,
+            hashed_password=self.password_hasher.hash(password),
+            is_active=True,
+            is_verified=True,
+            is_superuser=True,
+        )
+        return await self.users.create(user)
+
+    # --- Extension surface ------------------------------------------------
+
+    def set_email_backend(self, service: EmailService) -> None:
+        self.email = service
+
+    def set_sms_backend(self, service: SmsService) -> None:
+        self.sms = service
+
+    def add_template_dir(self, path: str | Path) -> None:
+        """Prepend a host-supplied template directory. Host templates win
+        over regstack defaults via Jinja2's ``ChoiceLoader`` for both the
+        email composer and the SSR UI pages.
+        """
+        path_obj = Path(path)
+        self.mail.add_template_dir(path_obj)
+        if path_obj not in self._template_dirs:
+            self._template_dirs.insert(0, path_obj)
+        # Force the UI environment to rebuild on next access so the new
+        # directory takes effect even if the env was already touched.
+        self._ui_env = None
+
+    def on(self, event: str, handler: Callable[..., Awaitable[None] | None]) -> None:
+        self.hooks.on(event, handler)

regstack/auth/__init__.py

@@ -0,0 +1,21 @@
+from regstack.auth.clock import Clock, FrozenClock, SystemClock
+from regstack.auth.dependencies import AuthDependencies
+from regstack.auth.jwt import JwtCodec, RevocationChecker, TokenPayload
+from regstack.auth.lockout import LockoutDecision, LockoutService
+from regstack.auth.password import PasswordHasher
+from regstack.auth.tokens import generate_verification_token, hash_token
+
+__all__ = [
+    "AuthDependencies",
+    "Clock",
+    "FrozenClock",
+    "JwtCodec",
+    "LockoutDecision",
+    "LockoutService",
+    "PasswordHasher",
+    "RevocationChecker",
+    "SystemClock",
+    "TokenPayload",
+    "generate_verification_token",
+    "hash_token",
+]

regstack/auth/clock.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Protocol
+
+
+class Clock(Protocol):
+    def now(self) -> datetime: ...
+
+
+class SystemClock:
+    def now(self) -> datetime:
+        return datetime.now(UTC)
+
+
+class FrozenClock:
+    """Test seam — returns a fixed timestamp until ``advance`` is called."""
+
+    def __init__(self, start: datetime | None = None) -> None:
+        self._now = start or datetime(2025, 1, 1, tzinfo=UTC)
+
+    def now(self) -> datetime:
+        return self._now
+
+    def advance(self, delta: timedelta) -> None:
+        self._now += delta
+
+    def set(self, when: datetime) -> None:
+        self._now = when

regstack/auth/dependencies.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import Depends, HTTPException, Request, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from regstack.auth.jwt import TokenError, is_payload_bulk_revoked
+
+if TYPE_CHECKING:
+    from regstack.auth.jwt import JwtCodec
+    from regstack.db.repositories.blacklist_repo import BlacklistRepo
+    from regstack.db.repositories.user_repo import UserRepo
+    from regstack.models.user import BaseUser
+
+_bearer = HTTPBearer(auto_error=False)
+
+
+class AuthDependencies:
+    """Factory for FastAPI dependencies bound to a particular RegStack instance.
+
+    A factory is used (rather than module-level dependencies) because two
+    embedded RegStack instances in the same process would otherwise share
+    state via module globals.
+    """
+
+    def __init__(
+        self,
+        *,
+        jwt: JwtCodec,
+        users: UserRepo,
+        blacklist: BlacklistRepo,
+    ) -> None:
+        self._jwt = jwt
+        self._users = users
+        self._blacklist = blacklist
+
+    def current_user(self) -> object:
+        """Return a callable usable as a FastAPI dependency yielding the authenticated user."""
+
+        async def _dep(
+            request: Request,
+            creds: HTTPAuthorizationCredentials | None = Depends(_bearer),
+        ) -> BaseUser:
+            user = await self._authenticate(creds)
+            request.state.regstack_user = user
+            return user
+
+        return _dep
+
+    def current_admin(self) -> object:
+        async def _dep(
+            request: Request,
+            creds: HTTPAuthorizationCredentials | None = Depends(_bearer),
+        ) -> BaseUser:
+            user = await self._authenticate(creds)
+            if not user.is_superuser:
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail="Administrator privileges required.",
+                )
+            request.state.regstack_user = user
+            return user
+
+        return _dep
+
+    async def _authenticate(self, creds: HTTPAuthorizationCredentials | None):
+        if creds is None or creds.scheme.lower() != "bearer":
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Authentication required.",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+        try:
+            payload = self._jwt.decode(creds.credentials)
+        except TokenError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail=f"Invalid token: {exc}",
+                headers={"WWW-Authenticate": "Bearer"},
+            ) from exc
+
+        if await self._blacklist.is_revoked(payload.jti):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Token has been revoked.",
+            )
+
+        user = await self._users.get_by_id(payload.sub)
+        if user is None or not user.is_active:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="User no longer active.",
+            )
+
+        if is_payload_bulk_revoked(payload, user.tokens_invalidated_after):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Session was invalidated; please sign in again.",
+            )
+
+        return user

regstack/auth/jwt.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, Any, Protocol
+
+import jwt as pyjwt
+
+from regstack.config.secrets import derive_secret
+
+if TYPE_CHECKING:
+    from regstack.auth.clock import Clock
+    from regstack.config.schema import RegStackConfig
+
+_DEFAULT_PURPOSE = "session"
+
+
+class TokenError(Exception):
+    """Raised when a token cannot be decoded or is no longer valid."""
+
+
+@dataclass(slots=True)
+class TokenPayload:
+    sub: str
+    jti: str
+    iat: datetime
+    exp: datetime
+    purpose: str
+
+    def to_claims(self, audience: str | None) -> dict[str, Any]:
+        # iat is emitted as a float so a within-the-same-second login after a
+        # bulk-revoke cutoff isn't falsely rejected. RFC 7519 NumericDate
+        # explicitly allows non-integer values.
+        claims: dict[str, Any] = {
+            "sub": self.sub,
+            "jti": self.jti,
+            "iat": self.iat.timestamp(),
+            "exp": int(self.exp.timestamp()),
+            "purpose": self.purpose,
+        }
+        if audience is not None:
+            claims["aud"] = audience
+        return claims
+
+
+class RevocationChecker(Protocol):
+    """Anything that knows whether a `jti` has been revoked."""
+
+    async def is_revoked(self, jti: str) -> bool: ...
+
+
+class JwtCodec:
+    """Encode and decode regstack's session JWTs.
+
+    Each purpose (session, verification, password_reset) signs with a key
+    derived from ``config.jwt_secret`` so a leak of one derived key does
+    not compromise the master.
+    """
+
+    def __init__(self, config: RegStackConfig, clock: Clock) -> None:
+        if not config.jwt_secret.get_secret_value():
+            raise ValueError(
+                "RegStackConfig.jwt_secret is empty. Run `regstack init` to generate one, "
+                "or set REGSTACK_JWT_SECRET."
+            )
+        self._config = config
+        self._clock = clock
+
+    def _key(self, purpose: str) -> bytes:
+        return derive_secret(self._config.jwt_secret.get_secret_value(), purpose)
+
+    def encode(
+        self,
+        subject: str,
+        *,
+        purpose: str = _DEFAULT_PURPOSE,
+        ttl_seconds: int | None = None,
+    ) -> tuple[str, TokenPayload]:
+        now = self._clock.now()
+        ttl = ttl_seconds if ttl_seconds is not None else self._config.jwt_ttl_seconds
+        exp = now + timedelta(seconds=ttl)
+        payload = TokenPayload(
+            sub=subject,
+            jti=secrets.token_urlsafe(16),
+            iat=now,
+            exp=exp,
+            purpose=purpose,
+        )
+        token = pyjwt.encode(
+            payload.to_claims(self._config.jwt_audience),
+            self._key(purpose),
+            algorithm=self._config.jwt_algorithm,
+        )
+        return token, payload
+
+    def decode(self, token: str, *, purpose: str = _DEFAULT_PURPOSE) -> TokenPayload:
+        try:
+            # We disable pyjwt's exp/iat checks because they use the system
+            # wall clock; we re-check both against the injected Clock so that
+            # FrozenClock-driven tests (and any future time-mocking host) get
+            # consistent behaviour.
+            claims = pyjwt.decode(
+                token,
+                self._key(purpose),
+                algorithms=[self._config.jwt_algorithm],
+                audience=self._config.jwt_audience,
+                options={
+                    "require": ["sub", "exp", "iat", "jti", "purpose"],
+                    "verify_exp": False,
+                    "verify_iat": False,
+                    "verify_nbf": False,
+                },
+            )
+        except pyjwt.PyJWTError as exc:
+            raise TokenError(str(exc)) from exc
+
+        if claims.get("purpose") != purpose:
+            raise TokenError("token purpose mismatch")
+
+        now = self._clock.now()
+        tz = now.tzinfo
+        iat = datetime.fromtimestamp(float(claims["iat"]), tz=tz)
+        exp = datetime.fromtimestamp(int(claims["exp"]), tz=tz)
+        if now >= exp:
+            raise TokenError("Signature has expired")
+
+        return TokenPayload(
+            sub=str(claims["sub"]),
+            jti=str(claims["jti"]),
+            iat=iat,
+            exp=exp,
+            purpose=str(claims["purpose"]),
+        )
+
+
+def is_payload_bulk_revoked(payload: TokenPayload, cutoff: datetime | None) -> bool:
+    """Return True when the user's bulk-revocation cutoff is at-or-after the
+    token's ``iat``. Tokens issued strictly after the cutoff (even by
+    microseconds) survive; tokens issued at exactly the same instant are
+    treated as before-the-change for security.
+    """
+    if cutoff is None:
+        return False
+    return payload.iat <= cutoff

regstack/auth/lockout.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from regstack.auth.clock import Clock
+    from regstack.config.schema import RegStackConfig
+    from regstack.db.repositories.login_attempt_repo import LoginAttemptRepo
+
+
+@dataclass(slots=True, frozen=True)
+class LockoutDecision:
+    locked: bool
+    retry_after_seconds: int
+
+
+class LockoutService:
+    """Counts failed logins per email in a sliding window. Locks the account
+    when the threshold is exceeded for the rest of the window.
+
+    Disabled (always returns ``locked=False``) when ``config.rate_limit_disabled``
+    is set — tests rely on this to avoid timing flakes.
+    """
+
+    def __init__(
+        self,
+        *,
+        attempts: LoginAttemptRepo,
+        config: RegStackConfig,
+        clock: Clock,
+    ) -> None:
+        self._attempts = attempts
+        self._config = config
+        self._clock = clock
+
+    @property
+    def _window(self) -> timedelta:
+        return timedelta(seconds=self._config.login_lockout_window_seconds)
+
+    async def check(self, email: str) -> LockoutDecision:
+        if self._config.rate_limit_disabled:
+            return LockoutDecision(locked=False, retry_after_seconds=0)
+        count = await self._attempts.count_recent(email, window=self._window, now=self._clock.now())
+        if count >= self._config.login_lockout_threshold:
+            return LockoutDecision(
+                locked=True,
+                retry_after_seconds=self._config.login_lockout_window_seconds,
+            )
+        return LockoutDecision(locked=False, retry_after_seconds=0)
+
+    async def record_failure(self, email: str, *, ip: str | None = None) -> None:
+        if self._config.rate_limit_disabled:
+            return
+        await self._attempts.record_failure(email, when=self._clock.now(), ip=ip)
+
+    async def clear(self, email: str) -> None:
+        await self._attempts.clear(email)

regstack/auth/mfa.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import secrets
+from typing import TYPE_CHECKING
+
+from regstack.auth.tokens import hash_token
+
+if TYPE_CHECKING:
+    from regstack.config.schema import RegStackConfig
+
+
+def generate_numeric_code(length: int) -> str:
+    """Cryptographically random numeric code as a zero-padded string.
+
+    Using ``secrets.randbelow`` (rather than ``random.randint``) keeps the
+    distribution uniform without leaking via the timing of ``randint``'s
+    rejection sampling — which itself uses ``getrandbits`` — but ``secrets``
+    is the standard answer for this in modern Python.
+    """
+    if length < 1:
+        raise ValueError("length must be >= 1")
+    upper_exclusive = 10**length
+    return f"{secrets.randbelow(upper_exclusive):0{length}d}"
+
+
+def generate_mfa_code(config: RegStackConfig) -> tuple[str, str]:
+    """Return ``(raw_code, code_hash)``."""
+    raw = generate_numeric_code(config.sms_code_length)
+    return raw, hash_token(raw)

regstack/auth/password.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pwdlib import PasswordHash
+from pwdlib.hashers.argon2 import Argon2Hasher
+
+
+class PasswordHasher:
+    """Thin wrapper over ``pwdlib`` so we can swap algorithms without touching callers."""
+
+    def __init__(self) -> None:
+        self._hasher = PasswordHash((Argon2Hasher(),))
+
+    def hash(self, password: str) -> str:
+        return self._hasher.hash(password)
+
+    def verify(self, password: str, hashed: str) -> bool:
+        return self._hasher.verify(password, hashed)
+
+    def needs_rehash(self, hashed: str) -> bool:
+        return self._hasher.check_needs_rehash(hashed)

regstack/auth/tokens.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import hashlib
+import secrets
+
+
+def generate_verification_token() -> tuple[str, str]:
+    """Return (raw_token_for_email, hash_for_db) for a single-use verification link.
+
+    The raw token is only ever sent in the verification email; only the
+    SHA-256 digest hits the database, so a database read does not yield
+    usable tokens.
+    """
+    raw = secrets.token_urlsafe(32)
+    return raw, hash_token(raw)
+
+
+def hash_token(raw: str) -> str:
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()

regstack/cli/__main__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import click
+
+from regstack.cli.admin import create_admin as create_admin_cmd
+from regstack.cli.doctor import doctor as doctor_cmd
+from regstack.cli.init import init as init_cmd
+from regstack.version import __version__
+
+
+@click.group(help="regstack — embeddable account registration for FastAPI/MongoDB apps.")
+@click.version_option(__version__, prog_name="regstack")
+def cli() -> None:
+    pass
+
+
+cli.add_command(init_cmd, name="init")
+cli.add_command(create_admin_cmd)
+cli.add_command(doctor_cmd)
+
+
+def main() -> None:
+    cli(prog_name="regstack")
+
+
+if __name__ == "__main__":
+    main()

regstack/cli/_runtime.py

@@ -0,0 +1,39 @@
+"""Helpers shared between the CLI commands.
+
+Keeps the per-command modules small and focused on their click flag wiring.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from regstack.app import RegStack
+from regstack.config.schema import RegStackConfig
+from regstack.db.client import make_client
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+
+def load_runtime_config(toml_path: Path | None = None) -> RegStackConfig:
+    return RegStackConfig.load(toml_path=toml_path) if toml_path else RegStackConfig.load()
+
+
+@asynccontextmanager
+async def open_regstack(toml_path: Path | None = None) -> AsyncIterator[RegStack]:
+    """Yield a fully-wired ``RegStack`` against a real Mongo connection.
+
+    Both the connection and the regstack instance are torn down on exit so
+    short-lived CLI invocations don't leak background tasks.
+    """
+    config = load_runtime_config(toml_path)
+    mongo = make_client(config)
+    try:
+        db = mongo[config.mongodb_database]
+        rs = RegStack(config=config, db=db)
+        await rs.install_indexes()
+        yield rs
+    finally:
+        await mongo.aclose()