regstack 0.1.0__py3-none-any.whl

regstack/email/__init__.py

@@ -0,0 +1,12 @@
+from regstack.email.base import EmailMessage, EmailService
+from regstack.email.composer import MailComposer
+from regstack.email.console import ConsoleEmailService
+from regstack.email.factory import build_email_service
+
+__all__ = [
+    "ConsoleEmailService",
+    "EmailMessage",
+    "EmailService",
+    "MailComposer",
+    "build_email_service",
+]

regstack/email/base.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class EmailMessage:
+    to: str
+    subject: str
+    html: str
+    text: str
+    from_address: str
+    from_name: str
+
+    @property
+    def from_header(self) -> str:
+        return f"{self.from_name} <{self.from_address}>"
+
+
+class EmailService(ABC):
+    @abstractmethod
+    async def send(self, message: EmailMessage) -> None: ...

regstack/email/composer.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from jinja2 import ChoiceLoader, Environment, FileSystemLoader, PackageLoader, select_autoescape
+
+from regstack.email.base import EmailMessage
+
+if TYPE_CHECKING:
+    from regstack.config.schema import EmailConfig
+    from regstack.models.user import BaseUser
+
+_DEFAULT_PACKAGE = "regstack.email"
+_DEFAULT_TEMPLATE_DIR = "templates"
+
+
+class MailComposer:
+    """Builds rendered ``EmailMessage`` instances from Jinja2 templates.
+
+    Hosts override the default templates by registering their own template
+    directory via ``RegStack.add_template_dir``; the underlying
+    ``ChoiceLoader`` resolves the host directory first.
+
+    Each email kind has three template files:
+        ``<name>.subject.txt``  — single line, whitespace-stripped
+        ``<name>.html``         — rich body
+        ``<name>.txt``          — plain-text fallback
+    """
+
+    def __init__(
+        self,
+        *,
+        email_config: EmailConfig,
+        app_name: str,
+        host_template_dirs: list[Path] | None = None,
+    ) -> None:
+        self._email_config = email_config
+        self._app_name = app_name
+        self._host_dirs: list[Path] = list(host_template_dirs or [])
+        self._env = self._build_env()
+
+    def add_template_dir(self, path: Path) -> None:
+        self._host_dirs.insert(0, path)
+        self._env = self._build_env()
+
+    def _build_env(self) -> Environment:
+        loaders = [FileSystemLoader(str(p)) for p in self._host_dirs]
+        loaders.append(PackageLoader(_DEFAULT_PACKAGE, _DEFAULT_TEMPLATE_DIR))
+        return Environment(
+            loader=ChoiceLoader(loaders),
+            autoescape=select_autoescape(["html"]),
+            trim_blocks=True,
+            lstrip_blocks=True,
+            keep_trailing_newline=True,
+        )
+
+    def _render(self, template_name: str, context: dict[str, object]) -> str:
+        return self._env.get_template(template_name).render(context)
+
+    def _compose(
+        self,
+        *,
+        kind: str,
+        to: str,
+        context: dict[str, object],
+    ) -> EmailMessage:
+        subject = self._render(f"{kind}.subject.txt", context).strip()
+        html = self._render(f"{kind}.html", context)
+        text = self._render(f"{kind}.txt", context)
+        return EmailMessage(
+            to=to,
+            subject=subject,
+            html=html,
+            text=text,
+            from_address=self._email_config.from_address,
+            from_name=self._email_config.from_name,
+        )
+
+    # --- Public renderers -------------------------------------------------
+
+    def verification(self, *, to: str, full_name: str | None, url: str) -> EmailMessage:
+        return self._compose(
+            kind="verification",
+            to=to,
+            context={
+                "app_name": self._app_name,
+                "full_name": full_name or "",
+                "url": url,
+            },
+        )
+
+    def password_reset(
+        self, *, to: str, full_name: str | None, url: str, ttl_minutes: int
+    ) -> EmailMessage:
+        return self._compose(
+            kind="password_reset",
+            to=to,
+            context={
+                "app_name": self._app_name,
+                "full_name": full_name or "",
+                "url": url,
+                "ttl_minutes": ttl_minutes,
+            },
+        )
+
+    def email_change(
+        self, *, to: str, full_name: str | None, url: str, ttl_minutes: int
+    ) -> EmailMessage:
+        return self._compose(
+            kind="email_change",
+            to=to,
+            context={
+                "app_name": self._app_name,
+                "full_name": full_name or "",
+                "url": url,
+                "ttl_minutes": ttl_minutes,
+            },
+        )
+
+    # SMS bodies live here too — same Jinja loader stack so hosts can
+    # override the wording by dropping ``sms_<kind>.txt`` into their
+    # template directory.
+    def sms_body(self, *, kind: str, **context: object) -> str:
+        full = {"app_name": self._app_name, **context}
+        return self._render(f"sms_{kind}.txt", full).strip()
+
+
+def default_template_dir() -> Path:
+    """Filesystem path of the bundled defaults — useful for tooling that wants
+    to copy and customise rather than override per-template.
+    """
+    return Path(str(resources.files(_DEFAULT_PACKAGE).joinpath(_DEFAULT_TEMPLATE_DIR)))
+
+
+__all__ = ["MailComposer", "default_template_dir"]
+
+
+def for_user(user: BaseUser) -> dict[str, object]:
+    """Tiny convenience used by routers building template contexts."""
+    return {"email": user.email, "full_name": user.full_name}

regstack/email/console.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import logging
+
+from regstack.email.base import EmailMessage, EmailService
+
+log = logging.getLogger("regstack.email.console")
+
+
+class ConsoleEmailService(EmailService):
+    """Logs the email payload instead of sending it. Used in dev and tests.
+
+    Captured messages are also kept in ``self.outbox`` so tests can assert on
+    rendered content without scraping logs.
+    """
+
+    def __init__(self) -> None:
+        self.outbox: list[EmailMessage] = []
+
+    async def send(self, message: EmailMessage) -> None:
+        self.outbox.append(message)
+        log.info(
+            "[regstack/console-email] To: %s | From: %s | Subject: %s",
+            message.to,
+            message.from_header,
+            message.subject,
+        )
+        log.debug("[regstack/console-email] text body:\n%s", message.text)

regstack/email/factory.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from regstack.email.base import EmailService
+from regstack.email.console import ConsoleEmailService
+
+if TYPE_CHECKING:
+    from regstack.config.schema import EmailConfig
+
+
+def build_email_service(config: EmailConfig) -> EmailService:
+    if config.backend == "console":
+        return ConsoleEmailService()
+    if config.backend == "smtp":
+        from regstack.email.smtp import SmtpEmailService
+
+        return SmtpEmailService(config)
+    if config.backend == "ses":
+        from regstack.email.ses import SesEmailService
+
+        return SesEmailService(config)
+    raise ValueError(f"Unknown email backend: {config.backend!r}")

regstack/email/ses.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from regstack.email.base import EmailMessage, EmailService
+
+if TYPE_CHECKING:
+    from regstack.config.schema import EmailConfig
+
+
+class SesEmailService(EmailService):
+    """Sends mail via AWS SES. Requires the optional ``ses`` extra
+    (``pip install regstack[ses]``) which pulls in ``aioboto3``.
+    """
+
+    def __init__(self, config: EmailConfig) -> None:
+        try:
+            import aioboto3  # noqa: F401  (import-time check)
+        except ImportError as exc:
+            raise RuntimeError(
+                "The SES email backend requires the 'ses' extra. "
+                "Install with `pip install regstack[ses]` or `uv sync --extra ses`."
+            ) from exc
+        self._config = config
+        # Defer client construction to send() so each call gets a fresh
+        # short-lived session. SES clients are cheap to instantiate.
+
+    async def send(self, message: EmailMessage) -> None:
+        import aioboto3
+
+        session_kwargs = {}
+        if self._config.ses_profile:
+            session_kwargs["profile_name"] = self._config.ses_profile
+        session = aioboto3.Session(**session_kwargs)
+
+        async with session.client("ses", region_name=self._config.ses_region) as client:
+            await client.send_email(
+                Source=message.from_header,
+                Destination={"ToAddresses": [message.to]},
+                Message={
+                    "Subject": {"Data": message.subject, "Charset": "UTF-8"},
+                    "Body": {
+                        "Text": {"Data": message.text, "Charset": "UTF-8"},
+                        "Html": {"Data": message.html, "Charset": "UTF-8"},
+                    },
+                },
+            )

regstack/email/smtp.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from email.message import EmailMessage as MimeMessage
+from typing import TYPE_CHECKING
+
+import aiosmtplib
+
+from regstack.email.base import EmailMessage, EmailService
+
+if TYPE_CHECKING:
+    from regstack.config.schema import EmailConfig
+
+
+class SmtpEmailService(EmailService):
+    """Sends mail via aiosmtplib. STARTTLS is enabled by default; set
+    ``smtp_starttls=False`` for an SMTP-over-SSL server (port 465 et al.)
+    or for plaintext local relays.
+    """
+
+    def __init__(self, config: EmailConfig) -> None:
+        if not config.smtp_host:
+            raise ValueError("EmailConfig.smtp_host is required for the SMTP backend.")
+        self._config = config
+
+    async def send(self, message: EmailMessage) -> None:
+        mime = MimeMessage()
+        mime["From"] = message.from_header
+        mime["To"] = message.to
+        mime["Subject"] = message.subject
+        mime.set_content(message.text)
+        mime.add_alternative(message.html, subtype="html")
+
+        username = self._config.smtp_username or None
+        password = (
+            self._config.smtp_password.get_secret_value()
+            if self._config.smtp_password is not None
+            else None
+        )
+        await aiosmtplib.send(
+            mime,
+            hostname=self._config.smtp_host,
+            port=self._config.smtp_port,
+            start_tls=self._config.smtp_starttls,
+            username=username,
+            password=password,
+        )

regstack/email/templates/email_change.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>{{ app_name }} — confirm new email</title>
+</head>
+<body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; color: #222; line-height: 1.5;">
+<p>Hi{% if full_name %} {{ full_name }}{% endif %},</p>
+<p>Someone — hopefully you — asked to change the email address on your <strong>{{ app_name }}</strong> account to this one. Click the link below to confirm. The link is valid for {{ ttl_minutes }} minutes.</p>
+<p><a href="{{ url }}" style="display:inline-block;padding:10px 20px;background:#222;color:#fff;text-decoration:none;border-radius:4px;">Confirm new email</a></p>
+<p>If the button doesn't work, paste this URL into your browser:</p>
+<p style="word-break: break-all;"><a href="{{ url }}">{{ url }}</a></p>
+<p style="color:#666;font-size: 12px;">If you didn't request this change, ignore this email — your address won't change.</p>
+</body>
+</html>

regstack/email/templates/email_change.subject.txt

@@ -0,0 +1 @@
+Confirm your new {{ app_name }} email address

regstack/email/templates/email_change.txt

@@ -0,0 +1,7 @@
+Hi{% if full_name %} {{ full_name }}{% endif %},
+
+Someone — hopefully you — asked to change the email address on your {{ app_name }} account to this one. Use the link below to confirm. It is valid for {{ ttl_minutes }} minutes.
+
+  {{ url }}
+
+If you didn't request this change, ignore this email — your address won't change.

regstack/email/templates/password_reset.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>{{ app_name }} — reset your password</title>
+</head>
+<body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; color: #222; line-height: 1.5;">
+<p>Hi{% if full_name %} {{ full_name }}{% endif %},</p>
+<p>We received a request to reset the password for your <strong>{{ app_name }}</strong> account. The link below is valid for {{ ttl_minutes }} minutes.</p>
+<p><a href="{{ url }}" style="display:inline-block;padding:10px 20px;background:#222;color:#fff;text-decoration:none;border-radius:4px;">Choose a new password</a></p>
+<p>If the button doesn't work, paste this URL into your browser:</p>
+<p style="word-break: break-all;"><a href="{{ url }}">{{ url }}</a></p>
+<p style="color:#666;font-size: 12px;">If you didn't request a reset, you can ignore this email — your password won't change.</p>
+</body>
+</html>

regstack/email/templates/password_reset.subject.txt

@@ -0,0 +1 @@
+Reset your {{ app_name }} password

regstack/email/templates/password_reset.txt

@@ -0,0 +1,7 @@
+Hi{% if full_name %} {{ full_name }}{% endif %},
+
+We received a request to reset the password for your {{ app_name }} account. The link below is valid for {{ ttl_minutes }} minutes:
+
+  {{ url }}
+
+If you didn't request a reset, you can ignore this email — your password won't change.

regstack/email/templates/sms_login_mfa.txt

@@ -0,0 +1 @@
+{{ app_name }} sign-in code: {{ code }}. Expires in {{ ttl_minutes }} minutes. If you didn't try to sign in, ignore this message.

regstack/email/templates/sms_phone_setup.txt

@@ -0,0 +1 @@
+{{ app_name }} verification code: {{ code }}. It expires in {{ ttl_minutes }} minutes.

regstack/email/templates/verification.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>{{ app_name }} — confirm your email</title>
+</head>
+<body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; color: #222; line-height: 1.5;">
+<p>Hi{% if full_name %} {{ full_name }}{% endif %},</p>
+<p>Thanks for signing up to <strong>{{ app_name }}</strong>. Please confirm your email address by clicking the link below.</p>
+<p><a href="{{ url }}" style="display:inline-block;padding:10px 20px;background:#222;color:#fff;text-decoration:none;border-radius:4px;">Confirm my account</a></p>
+<p>If the button doesn't work, paste this URL into your browser:</p>
+<p style="word-break: break-all;"><a href="{{ url }}">{{ url }}</a></p>
+<p style="color:#666;font-size: 12px;">If you didn't create an account, you can safely ignore this email — it will expire automatically.</p>
+</body>
+</html>

regstack/email/templates/verification.subject.txt

@@ -0,0 +1 @@
+Confirm your {{ app_name }} account

regstack/email/templates/verification.txt

@@ -0,0 +1,7 @@
+Hi{% if full_name %} {{ full_name }}{% endif %},
+
+Thanks for signing up to {{ app_name }}. Please confirm your email address by visiting the link below:
+
+  {{ url }}
+
+If you didn't create an account, you can safely ignore this email — the link will expire automatically.

regstack/hooks/__init__.py

@@ -0,0 +1,3 @@
+from regstack.hooks.events import HookRegistry
+
+__all__ = ["HookRegistry"]

regstack/hooks/events.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from collections import defaultdict
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+log = logging.getLogger("regstack.hooks")
+
+Handler = Callable[..., Awaitable[None] | None]
+
+# Known event names. Hosts may also subscribe to custom events at their own risk.
+KNOWN_EVENTS = {
+    "user_registered",
+    "user_logged_in",
+    "user_logged_out",
+    "user_verified",
+    "password_reset_requested",
+    "password_reset_completed",
+    "password_changed",
+    "user_deleted",
+}
+
+
+class HookRegistry:
+    """Tiny event bus. Handlers are awaited concurrently; exceptions are logged
+    and swallowed so a misbehaving host hook cannot break a primary auth flow.
+    """
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, list[Handler]] = defaultdict(list)
+
+    def on(self, event: str, handler: Handler) -> None:
+        self._handlers[event].append(handler)
+
+    async def fire(self, event: str, /, **kwargs: Any) -> None:
+        handlers = self._handlers.get(event, ())
+        if not handlers:
+            return
+        coros = []
+        for handler in handlers:
+            try:
+                result = handler(**kwargs)
+            except Exception:
+                log.exception("regstack hook %r raised synchronously", event)
+                continue
+            if inspect.isawaitable(result):
+                coros.append(_swallow(event, result))
+        if coros:
+            await asyncio.gather(*coros)
+
+
+async def _swallow(event: str, awaitable: Awaitable[None]) -> None:
+    try:
+        await awaitable
+    except Exception:
+        log.exception("regstack hook %r raised in awaitable", event)

regstack/models/__init__.py

@@ -0,0 +1,15 @@
+from regstack.models.login_attempt import LoginAttempt
+from regstack.models.mfa_code import MfaCode, MfaKind
+from regstack.models.pending_registration import PendingRegistration
+from regstack.models.user import BaseUser, UserCreate, UserPublic, UserUpdate
+
+__all__ = [
+    "BaseUser",
+    "LoginAttempt",
+    "MfaCode",
+    "MfaKind",
+    "PendingRegistration",
+    "UserCreate",
+    "UserPublic",
+    "UserUpdate",
+]

regstack/models/_objectid.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from bson import ObjectId
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import CoreSchema, core_schema
+
+
+class _ObjectIdValidator:
+    """Pydantic v2 type that accepts an ``ObjectId`` or its 24-char hex string and serialises as str."""
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> CoreSchema:
+        def validate(value: Any) -> str:
+            if isinstance(value, ObjectId):
+                return str(value)
+            if isinstance(value, str) and ObjectId.is_valid(value):
+                return value
+            raise ValueError(f"Not a valid ObjectId: {value!r}")
+
+        return core_schema.no_info_plain_validator_function(
+            validate,
+            serialization=core_schema.plain_serializer_function_ser_schema(str),
+        )
+
+
+ObjectIdStr = Annotated[str, _ObjectIdValidator]

regstack/models/login_attempt.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field
+
+from regstack.models._objectid import ObjectIdStr
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class LoginAttempt(BaseModel):
+    """One row per failed login attempt. TTL index on ``when`` reaps rows
+    once they fall outside the lockout window.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    id: ObjectIdStr | None = Field(default=None, alias="_id")
+    email: EmailStr
+    when: datetime = Field(default_factory=_utcnow)
+    ip: str | None = None
+
+    def to_mongo(self) -> dict[str, Any]:
+        data = self.model_dump(by_alias=True, exclude_none=True)
+        if data.get("_id") is None:
+            data.pop("_id", None)
+        return data

regstack/models/mfa_code.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from regstack.models._objectid import ObjectIdStr
+
+MfaKind = Literal["phone_setup", "login_mfa"]
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class MfaCode(BaseModel):
+    """One-time SMS code awaiting verification.
+
+    Only the SHA-256 hash of the code lives in the DB — a database read does
+    not yield usable codes. Codes are unique per ``(user_id, kind)`` so
+    re-issuing a code automatically invalidates the previous one.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    id: ObjectIdStr | None = Field(default=None, alias="_id")
+    user_id: str
+    kind: MfaKind
+    code_hash: str
+    expires_at: datetime
+    attempts: int = 0
+    max_attempts: int = 5
+    created_at: datetime = Field(default_factory=_utcnow)
+
+    def to_mongo(self) -> dict[str, Any]:
+        data = self.model_dump(by_alias=True, exclude_none=True)
+        if data.get("_id") is None:
+            data.pop("_id", None)
+        return data

regstack/models/pending_registration.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field
+
+from regstack.models._objectid import ObjectIdStr
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class PendingRegistration(BaseModel):
+    """Pre-verification user record. Lives in `pending_registrations` until
+    the user clicks the verification link (which moves them to `users`) or
+    `expires_at` passes (TTL index reaps).
+
+    Only the SHA-256 hash of the verification token is stored — the raw
+    token only exists in the email body and the user's clipboard.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    id: ObjectIdStr | None = Field(default=None, alias="_id")
+    email: EmailStr
+    hashed_password: str
+    full_name: str | None = None
+    token_hash: str
+    created_at: datetime = Field(default_factory=_utcnow)
+    expires_at: datetime
+
+    def to_mongo(self) -> dict[str, Any]:
+        data = self.model_dump(by_alias=True, exclude_none=True)
+        if data.get("_id") is None:
+            data.pop("_id", None)
+        return data