regstack 0.1.0__py3-none-any.whl

regstack/routers/register.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter, HTTPException, status
+
+from regstack.auth.tokens import generate_verification_token
+from regstack.db.repositories.pending_repo import PendingAlreadyExistsError
+from regstack.db.repositories.user_repo import UserAlreadyExistsError
+from regstack.models.pending_registration import PendingRegistration
+from regstack.models.user import BaseUser, UserCreate, UserPublic
+from regstack.routers._schemas import PendingResponse
+
+if TYPE_CHECKING:
+    from regstack.app import RegStack
+
+
+def build_register_router(rs: RegStack) -> APIRouter:
+    router = APIRouter()
+
+    @router.post(
+        "/register",
+        response_model=UserPublic | PendingResponse,
+        status_code=status.HTTP_201_CREATED,
+        summary="Register a new user (or start verification, if required)",
+    )
+    async def register(payload: UserCreate) -> UserPublic | PendingResponse:
+        if not rs.config.allow_registration:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Registration is disabled.",
+            )
+
+        existing = await rs.users.get_by_email(payload.email)
+        if existing is not None:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail="An account with that email already exists.",
+            )
+
+        hashed = rs.password_hasher.hash(payload.password)
+
+        if rs.config.require_verification:
+            return await _start_verification(rs, payload, hashed)
+
+        user = BaseUser(
+            email=payload.email,
+            hashed_password=hashed,
+            full_name=payload.full_name,
+            is_verified=True,
+        )
+        try:
+            user = await rs.users.create(user)
+        except UserAlreadyExistsError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail="An account with that email already exists.",
+            ) from exc
+
+        await rs.hooks.fire("user_registered", user=user)
+        return UserPublic.from_user(user)
+
+    return router
+
+
+async def _start_verification(
+    rs: RegStack, payload: UserCreate, hashed_password: str
+) -> PendingResponse:
+    raw, token_hash_value = generate_verification_token()
+    ttl = rs.config.verification_token_ttl_seconds
+    expires_at = rs.clock.now() + timedelta(seconds=ttl)
+    pending = PendingRegistration(
+        email=payload.email,
+        hashed_password=hashed_password,
+        full_name=payload.full_name,
+        token_hash=token_hash_value,
+        expires_at=expires_at,
+    )
+    try:
+        # upsert lets a user re-attempt registration; the most recent token wins
+        # and the old verification link silently stops working.
+        pending = await rs.pending.upsert(pending)
+    except PendingAlreadyExistsError as exc:  # pragma: no cover — upsert can't raise this
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="A pending registration already exists for that email.",
+        ) from exc
+
+    base = str(rs.config.base_url).rstrip("/")
+    url = f"{base}/verify?token={raw}"
+    message = rs.mail.verification(
+        to=payload.email,
+        full_name=payload.full_name,
+        url=url,
+    )
+    await rs.email.send(message)
+    await rs.hooks.fire("verification_requested", email=payload.email, url=url)
+    return PendingResponse(email=payload.email, expires_at=expires_at.isoformat())

regstack/routers/verify.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter, HTTPException, status
+from pydantic import BaseModel, ConfigDict, EmailStr
+
+from regstack.auth.tokens import generate_verification_token, hash_token
+from regstack.models.pending_registration import PendingRegistration
+from regstack.models.user import BaseUser, UserPublic
+from regstack.routers._schemas import MessageResponse
+
+if TYPE_CHECKING:
+    from regstack.app import RegStack
+
+
+class VerifyRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    token: str
+
+
+class ResendRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    email: EmailStr
+
+
+def build_verify_router(rs: RegStack) -> APIRouter:
+    router = APIRouter()
+
+    @router.post(
+        "/verify",
+        response_model=UserPublic,
+        summary="Confirm an email address from a verification link",
+    )
+    async def verify(payload: VerifyRequest) -> UserPublic:
+        token_hash_value = hash_token(payload.token)
+        pending = await rs.pending.find_by_token_hash(token_hash_value)
+        if pending is None:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Verification token is invalid or has expired.",
+            )
+        if pending.expires_at <= rs.clock.now():
+            await rs.pending.delete_by_email(pending.email)
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Verification token has expired. Request a new one.",
+            )
+
+        user = BaseUser(
+            email=pending.email,
+            hashed_password=pending.hashed_password,
+            full_name=pending.full_name,
+            is_active=True,
+            is_verified=True,
+        )
+        user = await rs.users.create(user)
+        await rs.pending.delete_by_email(pending.email)
+
+        await rs.hooks.fire("user_verified", user=user)
+        return UserPublic.from_user(user)
+
+    @router.post(
+        "/resend-verification",
+        response_model=MessageResponse,
+        status_code=status.HTTP_202_ACCEPTED,
+        summary="Re-send a verification email if a pending registration exists",
+    )
+    async def resend(payload: ResendRequest) -> MessageResponse:
+        # Anti-enumeration: always return the same response regardless of
+        # whether a pending registration exists.
+        existing_user = await rs.users.get_by_email(payload.email)
+        if existing_user is not None:
+            return _ack()
+
+        pending = await rs.pending.find_by_email(payload.email)
+        if pending is None:
+            return _ack()
+
+        raw, token_hash_value = generate_verification_token()
+        ttl = rs.config.verification_token_ttl_seconds
+        new_pending = PendingRegistration(
+            id=None,
+            email=pending.email,
+            hashed_password=pending.hashed_password,
+            full_name=pending.full_name,
+            token_hash=token_hash_value,
+            expires_at=rs.clock.now() + timedelta(seconds=ttl),
+        )
+        new_pending.created_at = datetime.now(UTC)
+        await rs.pending.upsert(new_pending)
+
+        url = _verification_url(rs, raw)
+        message = rs.mail.verification(
+            to=pending.email,
+            full_name=pending.full_name,
+            url=url,
+        )
+        await rs.email.send(message)
+        await rs.hooks.fire("verification_requested", email=pending.email, url=url)
+        return _ack()
+
+    return router
+
+
+def _ack() -> MessageResponse:
+    return MessageResponse(message="If a pending registration exists, a new email has been sent.")
+
+
+def _verification_url(rs: RegStack, raw_token: str) -> str:
+    base = str(rs.config.base_url).rstrip("/")
+    return f"{base}/verify?token={raw_token}"
+
+
+__all__ = ["ResendRequest", "VerifyRequest", "build_verify_router"]

regstack/sms/__init__.py

@@ -0,0 +1,5 @@
+from regstack.sms.base import SmsMessage, SmsService
+from regstack.sms.factory import build_sms_service
+from regstack.sms.null import NullSmsService
+
+__all__ = ["NullSmsService", "SmsMessage", "SmsService", "build_sms_service"]

regstack/sms/base.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+# E.164: leading '+', then 1-15 digits, no leading zero in the country code.
+_E164 = re.compile(r"^\+[1-9]\d{1,14}$")
+
+
+def is_valid_e164(phone: str) -> bool:
+    return bool(_E164.fullmatch(phone))
+
+
+@dataclass(frozen=True, slots=True)
+class SmsMessage:
+    to: str
+    body: str
+    from_number: str | None = None
+
+
+class SmsService(ABC):
+    @abstractmethod
+    async def send(self, message: SmsMessage) -> None: ...

regstack/sms/factory.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from regstack.sms.base import SmsService
+from regstack.sms.null import NullSmsService
+
+if TYPE_CHECKING:
+    from regstack.config.schema import SmsConfig
+
+
+def build_sms_service(config: SmsConfig) -> SmsService:
+    if config.backend == "null":
+        return NullSmsService()
+    if config.backend == "sns":
+        from regstack.sms.sns import SnsSmsService
+
+        return SnsSmsService(config)
+    if config.backend == "twilio":
+        from regstack.sms.twilio import TwilioSmsService
+
+        return TwilioSmsService(config)
+    raise ValueError(f"Unknown SMS backend: {config.backend!r}")

regstack/sms/null.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import logging
+
+from regstack.sms.base import SmsMessage, SmsService
+
+log = logging.getLogger("regstack.sms.null")
+
+
+class NullSmsService(SmsService):
+    """Default backend. Records messages in ``self.outbox`` so tests and dev
+    runs can inspect them without contacting a real SMS gateway. Logs each
+    send at INFO so the demo can grep the code out of stdout.
+    """
+
+    def __init__(self) -> None:
+        self.outbox: list[SmsMessage] = []
+
+    async def send(self, message: SmsMessage) -> None:
+        self.outbox.append(message)
+        log.info(
+            "[regstack/null-sms] To: %s | From: %s | Body: %s",
+            message.to,
+            message.from_number or "(unset)",
+            message.body,
+        )

regstack/sms/sns.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from regstack.sms.base import SmsMessage, SmsService
+
+if TYPE_CHECKING:
+    from regstack.config.schema import SmsConfig
+
+
+class SnsSmsService(SmsService):
+    """AWS SNS Publish-to-PhoneNumber backend. Requires the optional
+    ``sns`` extra (``pip install regstack[sns]`` → aioboto3).
+    """
+
+    def __init__(self, config: SmsConfig) -> None:
+        try:
+            import aioboto3  # noqa: F401
+        except ImportError as exc:
+            raise RuntimeError(
+                "The SNS SMS backend requires the 'sns' extra. "
+                "Install with `pip install regstack[sns]` or `uv sync --extra sns`."
+            ) from exc
+        self._config = config
+
+    async def send(self, message: SmsMessage) -> None:
+        import aioboto3
+
+        session = aioboto3.Session()
+        async with session.client("sns", region_name=self._config.sns_region) as client:
+            kwargs: dict[str, object] = {
+                "PhoneNumber": message.to,
+                "Message": message.body,
+            }
+            if message.from_number:
+                kwargs["MessageAttributes"] = {
+                    "AWS.SNS.SMS.SenderID": {
+                        "DataType": "String",
+                        "StringValue": message.from_number,
+                    }
+                }
+            await client.publish(**kwargs)

regstack/sms/twilio.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from regstack.sms.base import SmsMessage, SmsService
+
+if TYPE_CHECKING:
+    from regstack.config.schema import SmsConfig
+
+
+class TwilioSmsService(SmsService):
+    """Twilio Programmable Messaging backend. Requires the optional
+    ``twilio`` extra (``pip install regstack[twilio]``).
+
+    The Twilio Python SDK is sync; we hand off to a worker thread so we
+    don't block the event loop.
+    """
+
+    def __init__(self, config: SmsConfig) -> None:
+        try:
+            from twilio.rest import Client  # noqa: F401
+        except ImportError as exc:
+            raise RuntimeError(
+                "The Twilio SMS backend requires the 'twilio' extra. "
+                "Install with `pip install regstack[twilio]` or `uv sync --extra twilio`."
+            ) from exc
+        if not (config.twilio_account_sid and config.twilio_auth_token):
+            raise ValueError("Twilio backend needs both twilio_account_sid and twilio_auth_token.")
+        if not (config.from_number or False):
+            raise ValueError("Twilio backend needs a from_number.")
+        self._config = config
+
+    async def send(self, message: SmsMessage) -> None:
+        from twilio.rest import Client
+
+        sid = self._config.twilio_account_sid
+        token = self._config.twilio_auth_token
+        assert sid and token  # validated in __init__
+        client = Client(sid, token.get_secret_value())
+
+        from_number = message.from_number or self._config.from_number
+        await asyncio.to_thread(
+            lambda: client.messages.create(
+                to=message.to,
+                from_=from_number,
+                body=message.body,
+            )
+        )

regstack/ui/__init__.py

@@ -0,0 +1,3 @@
+from regstack.ui.pages import build_ui_environment, build_ui_router, default_static_dir
+
+__all__ = ["build_ui_environment", "build_ui_router", "default_static_dir"]

regstack/ui/pages.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse
+from jinja2 import ChoiceLoader, Environment, FileSystemLoader, PackageLoader, select_autoescape
+
+if TYPE_CHECKING:
+    from regstack.app import RegStack
+
+_PACKAGE = "regstack.ui"
+_TEMPLATE_DIR = "templates"
+_STATIC_DIR = "static"
+
+PAGE_NAMES = (
+    "login",
+    "register",
+    "verify",
+    "forgot",
+    "reset",
+    "me",
+    "confirm-email-change",
+    "mfa-confirm",
+)
+
+
+def default_static_dir() -> Path:
+    """Filesystem path to the bundled static assets — used by the StaticFiles
+    factory in :mod:`regstack.app`.
+    """
+    return Path(str(resources.files(_PACKAGE).joinpath(_STATIC_DIR)))
+
+
+def build_ui_environment(host_template_dirs: list[Path] | None = None) -> Environment:
+    loaders = [FileSystemLoader(str(p)) for p in (host_template_dirs or [])]
+    loaders.append(PackageLoader(_PACKAGE, _TEMPLATE_DIR))
+    return Environment(
+        loader=ChoiceLoader(loaders),
+        autoescape=select_autoescape(["html"]),
+        trim_blocks=True,
+        lstrip_blocks=True,
+        keep_trailing_newline=True,
+    )
+
+
+def build_ui_router(rs: RegStack) -> APIRouter:
+    """Server-rendered pages that pair with the JSON API.
+
+    Pages are stateless: they read API + UI prefixes from the page body and
+    let ``regstack.js`` drive form submissions and auth-state redirects.
+    No cookie-based session is established here, so this router is safe to
+    mount alongside the JSON API without CSRF middleware.
+    """
+    router = APIRouter()
+    env = rs.ui_env
+
+    def _render(template_name: str, page: str, **extra: object) -> HTMLResponse:
+        ctx = _base_context(rs, page=page)
+        ctx.update(extra)
+        body = env.get_template(template_name).render(ctx)
+        return HTMLResponse(body)
+
+    @router.get("/login", response_class=HTMLResponse, summary="Sign-in page")
+    async def login_page(_request: Request) -> HTMLResponse:
+        return _render("auth/login.html", page="login")
+
+    @router.get("/register", response_class=HTMLResponse, summary="Account creation page")
+    async def register_page(_request: Request) -> HTMLResponse:
+        return _render("auth/register.html", page="register")
+
+    @router.get(
+        "/forgot",
+        response_class=HTMLResponse,
+        summary="Forgot-password request page",
+        include_in_schema=rs.config.enable_password_reset,
+    )
+    async def forgot_page(_request: Request) -> HTMLResponse:
+        return _render("auth/forgot.html", page="forgot")
+
+    @router.get(
+        "/reset",
+        response_class=HTMLResponse,
+        summary="Set a new password (token comes from query string)",
+        include_in_schema=rs.config.enable_password_reset,
+    )
+    async def reset_page(_request: Request) -> HTMLResponse:
+        return _render("auth/reset.html", page="reset")
+
+    @router.get(
+        "/verify",
+        response_class=HTMLResponse,
+        summary="Auto-confirms a verification token from the query string",
+    )
+    async def verify_page(_request: Request) -> HTMLResponse:
+        return _render("auth/verify.html", page="verify")
+
+    @router.get(
+        "/confirm-email-change",
+        response_class=HTMLResponse,
+        summary="Auto-confirms an email-change token from the query string",
+    )
+    async def confirm_email_change_page(_request: Request) -> HTMLResponse:
+        return _render(
+            "auth/email_change_confirm.html",
+            page="confirm-email-change",
+        )
+
+    @router.get(
+        "/me",
+        response_class=HTMLResponse,
+        summary="Authenticated account dashboard (client-side gate)",
+    )
+    async def me_page(_request: Request) -> HTMLResponse:
+        return _render("auth/me.html", page="me")
+
+    @router.get(
+        "/mfa-confirm",
+        response_class=HTMLResponse,
+        summary="Second step of an MFA-required sign-in",
+        include_in_schema=rs.config.enable_sms_2fa,
+    )
+    async def mfa_confirm_page(_request: Request) -> HTMLResponse:
+        return _render("auth/mfa_confirm.html", page="mfa-confirm")
+
+    return router
+
+
+def _base_context(rs: RegStack, *, page: str) -> dict[str, object]:
+    return {
+        "page": page,
+        "app_name": rs.config.app_name,
+        "brand_logo_url": rs.config.brand_logo_url,
+        "brand_tagline": rs.config.brand_tagline,
+        "api_prefix": rs.config.api_prefix.rstrip("/"),
+        "ui_prefix": rs.config.ui_prefix.rstrip("/"),
+        "static_prefix": rs.config.static_prefix.rstrip("/"),
+        "theme_css_url": rs.config.theme_css_url,
+        "allow_registration": rs.config.allow_registration,
+        "enable_password_reset": rs.config.enable_password_reset,
+        "enable_account_deletion": rs.config.enable_account_deletion,
+        "enable_sms_2fa": rs.config.enable_sms_2fa,
+    }
+
+
+__all__ = ["PAGE_NAMES", "build_ui_environment", "build_ui_router", "default_static_dir"]