regstack 0.8.0__tar.gz → 0.8.1__tar.gz

{regstack-0.8.0 → regstack-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.8.0
+Version: 0.8.1
 Summary: Embeddable user registration, login, and account management for FastAPI apps. SQLite / Postgres / MongoDB.
 Project-URL: Homepage, https://github.com/jdrumgoole/regstack
 Project-URL: Repository, https://github.com/jdrumgoole/regstack
@@ -151,7 +151,7 @@ result everywhere is what regstack is for.
 ✔ Server-rendered HTML pages, theme with one CSS file
 ✔ Pluggable email (console / SMTP / Amazon SES) and SMS (Amazon SNS / Twilio)
 ✔ Argon2 password hashing, CSP-friendly templates
-✔ Setup wizards (live in their own pywebview windows): `regstack init` (project bootstrap), `regstack oauth setup` (guided Google OAuth client config), `regstack theme design` (live theme designer with preview), `regstack doctor` (config validator), and `regstack validate` (end-to-end probe of a deployed install)
+✔ Setup wizards (live in their own pywebview windows): `regstack init` (project bootstrap), `regstack oauth setup` (guided Google OAuth client config), `regstack theme design` (live theme designer with preview), `regstack ses setup` (guided SES configuration that validates against AWS), `regstack doctor` (config validator), and `regstack validate` (end-to-end probe of a deployed install)
 ✔ Three storage backends: SQLite, PostgreSQL, MongoDB — chosen by URL
 ```
 

{regstack-0.8.0 → regstack-0.8.1}/README.md

@@ -72,7 +72,7 @@ result everywhere is what regstack is for.
 ✔ Server-rendered HTML pages, theme with one CSS file
 ✔ Pluggable email (console / SMTP / Amazon SES) and SMS (Amazon SNS / Twilio)
 ✔ Argon2 password hashing, CSP-friendly templates
-✔ Setup wizards (live in their own pywebview windows): `regstack init` (project bootstrap), `regstack oauth setup` (guided Google OAuth client config), `regstack theme design` (live theme designer with preview), `regstack doctor` (config validator), and `regstack validate` (end-to-end probe of a deployed install)
+✔ Setup wizards (live in their own pywebview windows): `regstack init` (project bootstrap), `regstack oauth setup` (guided Google OAuth client config), `regstack theme design` (live theme designer with preview), `regstack ses setup` (guided SES configuration that validates against AWS), `regstack doctor` (config validator), and `regstack validate` (end-to-end probe of a deployed install)
 ✔ Three storage backends: SQLite, PostgreSQL, MongoDB — chosen by URL
 ```
 

{regstack-0.8.0 → regstack-0.8.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "regstack"
-version = "0.8.0"
+version = "0.8.1"
 description = "Embeddable user registration, login, and account management for FastAPI apps. SQLite / Postgres / MongoDB."
 readme = "README.md"
 requires-python = ">=3.11"

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/auth/lockout.py

@@ -93,6 +93,19 @@ class LockoutService:
             )
         return LockoutDecision(locked=False, retry_after_seconds=0)
 
+    async def attempts_remaining(self, email: str) -> int | None:
+        """Return how many failures are left before lockout fires.
+
+        Used by the login route after a wrong-password 401 so we can
+        surface the same "N attempts remaining" message MFA shows.
+        Returns ``None`` when rate-limiting is disabled (tests) — the
+        route should then suppress the line entirely.
+        """
+        if self._config.rate_limit_disabled:
+            return None
+        count = await self._attempts.count_recent(email, window=self._window, now=self._clock.now())
+        return max(self._config.login_lockout_threshold - count, 0)
+
     async def record_failure(self, email: str, *, ip: str | None = None) -> None:
         """Record one failed login. No-op when rate limiting is disabled.
 

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/auth/rate_limit.py

@@ -54,6 +54,9 @@ ROUTE_LIMIT_MAP: dict[str, str] = {
     "confirm_email_change_rate_limit": "/confirm-email-change",
     "delete_account_rate_limit": "/account",
     "oauth_exchange_rate_limit": "/oauth/exchange",
+    "phone_start_rate_limit": "/phone/start",
+    "phone_confirm_rate_limit": "/phone/confirm",
+    "phone_disable_rate_limit": "/phone",
 }
 
 

regstack-0.8.1/src/regstack/cli/_paths.py

@@ -0,0 +1,84 @@
+"""Shared CLI helpers for resolving the regstack config target.
+
+As of 0.8.x the canonical CLI flag is ``--config``. It accepts either:
+
+* a path to a regstack TOML file (``./regstack.toml``), or
+* a path to a directory containing or to-receive that file (``./conf/``).
+
+A legacy ``--target`` flag is still accepted on commands that write
+config (``init``, ``oauth setup``, ``ses setup``, ``theme design``);
+using it emits a deprecation warning.
+
+This module is the single source of truth for that resolution so each
+command stays a thin Click wrapper.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+CONFIG_FILE = "regstack.toml"
+
+_DEPRECATION_HINT = (
+    "Deprecation: --target is deprecated; use --config (accepts a file or a "
+    "directory). --target will be removed in 1.0."
+)
+
+
+def resolve_target_dir(
+    *,
+    config: Path | None,
+    target: Path | None,
+) -> Path:
+    """Resolve the directory the command should write into.
+
+    ``config`` is the canonical flag. ``target`` is the legacy alias;
+    if it's the one supplied, a deprecation warning is emitted to
+    stderr (once per invocation) before the value is honoured.
+
+    Raises ``click.UsageError`` if both are supplied.
+    """
+    if config is not None and target is not None:
+        raise click.UsageError(
+            "--config and --target are mutually exclusive. Use --config "
+            "(--target is the deprecated alias)."
+        )
+
+    if target is not None:
+        click.echo(click.style(_DEPRECATION_HINT, fg="yellow"), err=True)
+        value: Path | None = target
+    else:
+        value = config
+
+    if value is None:
+        return Path.cwd().resolve()
+
+    p = value.resolve()
+    # File or dir? If it's a file (or looks like one — name ends with .toml),
+    # operate in its parent directory.
+    if p.is_file() or p.suffix == ".toml":
+        return p.parent
+    return p
+
+
+def resolve_toml_path(config: Path | None) -> Path | None:
+    """Resolve ``--config`` for read-only commands (doctor, migrate, create-admin).
+
+    Returns the path to the TOML file, or ``None`` if the flag was
+    omitted (caller falls back to env/cwd discovery).
+
+    If a directory is supplied, looks for ``regstack.toml`` inside it.
+    The returned path is not required to exist — load_runtime_config
+    surfaces the error with a clearer message.
+    """
+    if config is None:
+        return None
+    p = config.resolve()
+    if p.is_dir():
+        return p / CONFIG_FILE
+    return p
+
+
+__all__ = ["CONFIG_FILE", "resolve_target_dir", "resolve_toml_path"]

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/cli/admin.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 import click
 
+from regstack.cli._paths import resolve_toml_path
 from regstack.cli._runtime import open_regstack
 
 
@@ -21,17 +22,21 @@ from regstack.cli._runtime import open_regstack
 )
 @click.option(
     "--config",
-    "toml_path",
-    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    "config_path_in",
+    type=click.Path(exists=True, path_type=Path),
     default=None,
-    help="Path to regstack.toml (default: search cwd / $REGSTACK_CONFIG).",
+    help=(
+        "Path to regstack.toml (or a directory containing it). "
+        "Default: search cwd / $REGSTACK_CONFIG."
+    ),
 )
-def create_admin(email: str, password: str | None, toml_path: Path | None) -> None:
+def create_admin(email: str, password: str | None, config_path_in: Path | None) -> None:
     if password is None:
         password = click.prompt("Password", hide_input=True, confirmation_prompt=True)
     if len(password) < 8:
         raise click.UsageError("Password must be at least 8 characters.")
 
+    toml_path = resolve_toml_path(config_path_in)
     asyncio.run(_run(email=email, password=password, toml_path=toml_path))
 
 

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/cli/doctor.py

@@ -9,6 +9,7 @@ import click
 import dns.resolver
 
 from regstack.backends.factory import build_backend, detect_backend_kind
+from regstack.cli._paths import resolve_toml_path
 from regstack.cli._results import CheckResult
 from regstack.cli._runtime import load_runtime_config
 from regstack.email.factory import build_email_service
@@ -23,10 +24,13 @@ if TYPE_CHECKING:
 )
 @click.option(
     "--config",
-    "toml_path",
-    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    "config_path_in",
+    type=click.Path(exists=True, path_type=Path),
     default=None,
-    help="Path to regstack.toml (default: search cwd / $REGSTACK_CONFIG).",
+    help=(
+        "Path to regstack.toml (or a directory containing it). "
+        "Default: search cwd / $REGSTACK_CONFIG."
+    ),
 )
 @click.option(
     "--check-dns",
@@ -39,7 +43,8 @@ if TYPE_CHECKING:
     default=None,
     help="Send a probe email to this address through the configured backend.",
 )
-def doctor(toml_path: Path | None, check_dns: bool, test_recipient: str | None) -> None:
+def doctor(config_path_in: Path | None, check_dns: bool, test_recipient: str | None) -> None:
+    toml_path = resolve_toml_path(config_path_in)
     results = asyncio.run(
         _run(toml_path=toml_path, check_dns=check_dns, test_recipient=test_recipient)
     )
@@ -49,7 +54,10 @@ def doctor(toml_path: Path | None, check_dns: bool, test_recipient: str | None)
         click.echo(f"{symbol} {r.name}: {r.detail}")
     if failed:
         click.echo(click.style(f"\n{failed} check(s) failed.", fg="red"), err=True)
-    sys.exit(failed)
+    # Clamp to 0/1 so a shell `regstack doctor && deploy` is predictable;
+    # the failure count appears on the stderr line above for operators
+    # who want it. (Review #4.)
+    sys.exit(1 if failed else 0)
 
 
 async def _run(

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/cli/init.py

@@ -6,34 +6,65 @@ from urllib.parse import urlsplit
 
 import click
 
+from regstack.cli._paths import CONFIG_FILE, resolve_target_dir
 from regstack.config.secrets import generate_secret
 
-CONFIG_FILE = "regstack.toml"
 SECRETS_FILE = "regstack.secrets.env"
 
 
 @click.command(help="Interactive wizard that writes regstack.toml + regstack.secrets.env.")
+@click.option(
+    "--config",
+    "config_path_in",
+    type=click.Path(path_type=Path),
+    default=None,
+    help=("Path to regstack.toml or the directory to write it into (default: current directory)."),
+)
 @click.option(
     "--target",
-    "target_dir",
+    "target_path_in",
     type=click.Path(file_okay=False, dir_okay=True, path_type=Path),
-    default=Path.cwd,
-    show_default="current directory",
-    help="Directory to write config files into.",
+    default=None,
+    help="DEPRECATED: use --config. Directory to write config files into.",
 )
 @click.option("--force", is_flag=True, help="Overwrite existing config files without prompting.")
-def init(target_dir: Path, *, force: bool) -> None:
-    target_dir = Path(target_dir).resolve()
+@click.option(
+    "--if-missing",
+    is_flag=True,
+    help=(
+        "Exit 0 silently when either config file already exists. Useful "
+        "for idempotent infrastructure-as-code: `regstack init --if-missing` "
+        "in a Dockerfile entrypoint produces config the first time and "
+        "no-ops on every subsequent boot."
+    ),
+)
+def init(
+    config_path_in: Path | None,
+    target_path_in: Path | None,
+    *,
+    force: bool,
+    if_missing: bool,
+) -> None:
+    if force and if_missing:
+        raise click.UsageError("--force and --if-missing are mutually exclusive.")
+    target_dir = resolve_target_dir(config=config_path_in, target=target_path_in)
     target_dir.mkdir(parents=True, exist_ok=True)
 
     config_path = target_dir / CONFIG_FILE
     secrets_path = target_dir / SECRETS_FILE
 
-    if (config_path.exists() or secrets_path.exists()) and not force:
-        click.confirm(
-            f"Config already exists at {config_path} or {secrets_path}. Overwrite?",
-            abort=True,
-        )
+    if config_path.exists() or secrets_path.exists():
+        if if_missing:
+            click.echo(
+                f"Config already present at {config_path} or {secrets_path}; "
+                "no action taken (--if-missing).",
+            )
+            sys.exit(0)
+        if not force:
+            click.confirm(
+                f"Config already exists at {config_path} or {secrets_path}. Overwrite?",
+                abort=True,
+            )
 
     click.echo(click.style("regstack init — app configuration only.\n", bold=True))
     click.echo("This wizard never provisions infrastructure. It only writes config files.\n")
@@ -95,11 +126,12 @@ def init(target_dir: Path, *, force: bool) -> None:
         type=click.Choice(["console", "smtp", "ses"]),
         default="console",
     )
-    if email_backend != "console":
+    if email_backend == "ses":
         click.echo(
             click.style(
-                f"Note: {email_backend!r} backend lands in M2; the wizard will write your "
-                "config, but the running app will refuse to send mail until then.",
+                "Tip: `regstack ses setup` is a guided wizard that validates "
+                "credentials and sender-domain verification against AWS before "
+                "writing the config. Consider that instead.",
                 fg="yellow",
             )
         )
@@ -116,6 +148,16 @@ def init(target_dir: Path, *, force: bool) -> None:
         smtp_starttls = click.confirm("Use STARTTLS?", default=True)
         smtp_user = click.prompt("SMTP username", default="")
         smtp_pass = click.prompt("SMTP password", default="", hide_input=True) or None
+        if smtp_user and smtp_pass is None:
+            click.echo(
+                click.style(
+                    "Warning: SMTP username set but no password — leaving "
+                    "REGSTACK_EMAIL__SMTP_PASSWORD unset. Set it via the secrets "
+                    "file or env var before the app starts, or authenticated "
+                    "SMTP sends will fail.",
+                    fg="yellow",
+                )
+            )
     elif email_backend == "ses":
         ses_region = click.prompt("AWS region", default="eu-west-1")
 

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/cli/migrate.py

@@ -6,6 +6,7 @@ from pathlib import Path
 import click
 
 from regstack.backends.factory import detect_backend_kind
+from regstack.cli._paths import resolve_toml_path
 from regstack.cli._runtime import load_runtime_config
 
 
@@ -15,18 +16,26 @@ from regstack.cli._runtime import load_runtime_config
 )
 @click.option(
     "--config",
-    "toml_path",
-    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    "config_path_in",
+    type=click.Path(exists=True, path_type=Path),
     default=None,
-    help="Path to regstack.toml (default: search cwd / $REGSTACK_CONFIG).",
+    help=(
+        "Path to regstack.toml (or a directory containing it). "
+        "Default: search cwd / $REGSTACK_CONFIG."
+    ),
 )
 @click.option(
     "--target",
     default="head",
     show_default=True,
-    help="Revision to upgrade to (e.g. 'head', '0001', '+1').",
+    help=(
+        "Alembic revision to upgrade to (e.g. 'head', '0001', '+1'). "
+        "Note: distinct from the global --target/--config flag pair on "
+        "config-writing commands."
+    ),
 )
-def migrate(toml_path: Path | None, target: str) -> None:
+def migrate(config_path_in: Path | None, target: str) -> None:
+    toml_path = resolve_toml_path(config_path_in)
     """Idempotent: re-running on a DB at the target revision is a no-op.
 
     Mongo backends are silently skipped — TTL indexes are installed by

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/cli/validate/cli.py

@@ -251,7 +251,9 @@ def validate(
             timeout=timeout,
         )
     )
-    sys.exit(exit_code)
+    # Clamp to 0/1 for predictable shell composition; the per-check
+    # failure count is rendered in the report above. (Review #4.)
+    sys.exit(1 if exit_code else 0)
 
 
 async def _run(

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/config/schema.py

@@ -229,10 +229,12 @@ class RegStackConfig(BaseSettings):
     confirm_email_change_rate_limit: str | None = None
     delete_account_rate_limit: str | None = None
     oauth_exchange_rate_limit: str | None = None
-    # DEPRECATED in favour of the per-route fields above; kept for
-    # back-compat with configs that set them. Unused by the router.
-    login_max_per_minute: Annotated[int, Field(ge=1)] = 5
-    login_max_per_hour: Annotated[int, Field(ge=1)] = 20
+    # Phone routes send paid SMS and brute-force a 6-digit code, so
+    # they need IP throttles regardless of the per-code attempt counter
+    # in mfa_codes. (Review #6.)
+    phone_start_rate_limit: str | None = None
+    phone_confirm_rate_limit: str | None = None
+    phone_disable_rate_limit: str | None = None
 
     # Sub-configs
     email: EmailConfig = Field(default_factory=EmailConfig)

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/email/composer.py

@@ -89,7 +89,9 @@ class MailComposer:
 
     # --- Public renderers -------------------------------------------------
 
-    def verification(self, *, to: str, full_name: str | None, url: str) -> EmailMessage:
+    def verification(
+        self, *, to: str, full_name: str | None, url: str, ttl_hours: int
+    ) -> EmailMessage:
         return self._compose(
             kind="verification",
             to=to,
@@ -97,6 +99,7 @@ class MailComposer:
                 "app_name": self._app_name,
                 "full_name": full_name or "",
                 "url": url,
+                "ttl_hours": ttl_hours,
             },
         )
 

regstack-0.8.1/src/regstack/email/templates/sms_phone_setup.txt

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

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/email/templates/verification.html

@@ -6,7 +6,7 @@
 </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>Thanks for signing up to <strong>{{ app_name }}</strong>. Please confirm your email address by clicking the link below. It is valid for {{ ttl_hours }} hours.</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>

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/email/templates/verification.txt

@@ -1,6 +1,6 @@
 Hi{% if full_name %} {{ full_name }}{% endif %},
 
-Thanks for signing up to {{ app_name }}. Please confirm your email address by visiting the link below:
+Thanks for signing up to {{ app_name }}. Please confirm your email address by visiting the link below. It is valid for {{ ttl_hours }} hours.
 
   {{ url }}
 

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/hooks/events.py

@@ -24,6 +24,7 @@ KNOWN_EVENTS = {
     "email_change_requested",
     "email_changed",
     "phone_setup_started",
+    "phone_setup_disabled",
     "mfa_login_started",
     "mfa_enabled",
     "mfa_disabled",

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/routers/account.py

@@ -137,7 +137,9 @@ def build_account_router(rs: RegStack) -> APIRouter:
         # via the users.update_email unique constraint.
         clash = await rs.users.get_by_email(payload.new_email)
         accepted = MessageResponse(
-            message="If that email address is not already in use, a confirmation link has been sent.",
+            message=(
+                "If the address is available, a confirmation link has been sent. Check your email."
+            ),
         )
         if clash is not None:
             log.info(
@@ -176,7 +178,7 @@ def build_account_router(rs: RegStack) -> APIRouter:
         except TokenError as exc:
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
-                detail="Token is invalid or has expired.",
+                detail="Email-change link is invalid or has expired. Request a new one.",
             ) from exc
 
         user = await rs.users.get_by_id(user_id)

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/routers/admin.py

@@ -184,7 +184,12 @@ def build_admin_router(rs: RegStack) -> APIRouter:
         await rs.pending.upsert(pending)
 
         url = rs.config.resolve_verify_url(raw)
-        message = rs.mail.verification(to=user.email, full_name=user.full_name, url=url)
+        message = rs.mail.verification(
+            to=user.email,
+            full_name=user.full_name,
+            url=url,
+            ttl_hours=max(ttl // 3600, 1),
+        )
         await rs.email.send(message)
         await rs.hooks.fire("verification_requested", email=user.email, url=url)
         return MessageResponse(message=f"Verification email sent to {user.email}.")

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/routers/login.py

@@ -19,13 +19,30 @@ if TYPE_CHECKING:
     from regstack.models.user import BaseUser
 
 
-_INVALID = HTTPException(
-    status_code=status.HTTP_401_UNAUTHORIZED,
-    detail="Invalid email or password.",
-)
 _LOGIN_MFA_PURPOSE = "login_mfa"
 
 
+async def _build_invalid(rs: RegStack, email: str) -> HTTPException:
+    """Build a 401 that includes the user-facing attempts-remaining
+    count when lockout is enabled — matches the shape MFA uses for
+    its wrong-code response so the two flows feel symmetrical to a
+    user typing the wrong credentials. (Review #15.)
+
+    Returns a fresh exception each call because ``attempts_remaining``
+    changes between calls; the previous module-level constant was
+    cached and couldn't carry per-call state.
+    """
+    remaining = await rs.lockout.attempts_remaining(email)
+    if remaining is None or remaining == 0:
+        # remaining == 0 means lockout is about to fire on the next
+        # attempt; the 429 from `lockout.check` carries the
+        # "Try again in N seconds" message — don't pre-announce it.
+        detail = "Invalid email or password."
+    else:
+        detail = f"Invalid email or password. {remaining} attempt(s) remaining."
+    return HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=detail)
+
+
 class MfaPendingResponse(BaseModel):
     status: str = "mfa_required"
     mfa_pending_token: str
@@ -69,7 +86,7 @@ def build_login_router(rs: RegStack) -> APIRouter:
         user = await rs.users.get_by_email(payload.email)
         if user is None or user.id is None:
             await rs.lockout.record_failure(payload.email)
-            raise _INVALID
+            raise await _build_invalid(rs, payload.email)
         # Password verification runs first so the is_active and
         # is_verified branches below are only reachable by an attacker
         # who already knows the password. Without this ordering, an
@@ -83,7 +100,7 @@ def build_login_router(rs: RegStack) -> APIRouter:
             payload.password, user.hashed_password
         ):
             await rs.lockout.record_failure(payload.email)
-            raise _INVALID
+            raise await _build_invalid(rs, payload.email)
         # Even with the right password, disabled / unverified accounts
         # must still increment the lockout counter — otherwise a
         # password-stuffing attacker who happens to be holding the
@@ -122,7 +139,7 @@ def build_login_router(rs: RegStack) -> APIRouter:
         except TokenError as exc:
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
-                detail="MFA token is invalid or has expired.",
+                detail="Sign-in session is invalid or has expired. Start over from sign-in.",
             ) from exc
 
         result = await rs.mfa_codes.verify(user_id=user_id, kind="login_mfa", raw_code=payload.code)

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/routers/password.py

@@ -44,7 +44,10 @@ def build_password_router(rs: RegStack) -> APIRouter:
 
         # Anti-enumeration: same response regardless of whether the user exists.
         ack = MessageResponse(
-            message="If an account exists for that email, a reset link has been sent."
+            message=(
+                "If the address matches an active account, a reset link has been sent. "
+                "Check your email."
+            )
         )
         user = await rs.users.get_by_email(payload.email)
         if user is None or user.id is None or not user.is_active:
@@ -84,14 +87,24 @@ def build_password_router(rs: RegStack) -> APIRouter:
         except TokenError as exc:
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
-                detail="Reset token is invalid or has expired.",
+                detail="Reset link is invalid or has expired. Request a new one.",
             ) from exc
 
+        # Refuse to re-use a reset token. The token's jti is added to the
+        # blacklist on first success, so a second click of the same link
+        # gets the same "invalid or has expired" response that an
+        # expired-token attempt sees. (Review #17.)
+        if await rs.blacklist.is_revoked(token_payload.jti):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Reset link is invalid or has expired. Request a new one.",
+            )
+
         user = await rs.users.get_by_id(token_payload.sub)
         if user is None or user.id is None or not user.is_active:
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
-                detail="Reset token does not match an active account.",
+                detail="Reset link does not match an active account.",
             )
 
         new_hash = rs.password_hasher.hash(payload.new_password)
@@ -100,6 +113,8 @@ def build_password_router(rs: RegStack) -> APIRouter:
         # stolen session token would otherwise outlive the password change.
         await rs.users.update_password(user.id, new_hash)
         await rs.lockout.clear(user.email)
+        # Blacklist the reset token so the same link can't be used twice.
+        await rs.blacklist.revoke(token_payload.jti, token_payload.exp)
         await rs.hooks.fire("password_reset_completed", user=user)
         return MessageResponse(message="Password has been reset. Please sign in.")
 

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/routers/phone.py

@@ -122,7 +122,7 @@ def build_phone_router(rs: RegStack) -> APIRouter:
         except TokenError as exc:
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
-                detail="Pending token is invalid or has expired.",
+                detail="Phone-setup session is invalid or has expired. Start setup again.",
             ) from exc
 
         result = await rs.mfa_codes.verify(
@@ -164,6 +164,11 @@ def build_phone_router(rs: RegStack) -> APIRouter:
         await rs.users.set_phone(user.id, None)
         await rs.users.set_mfa_enabled(user.id, is_mfa_enabled=False)
         await rs.mfa_codes.delete(user_id=user.id)
+        # Fire phone_setup_disabled (factor-specific) before mfa_disabled
+        # (any factor). Subscribers that care which factor was removed
+        # listen for the former; subscribers that just want "MFA is off
+        # for this user" listen for the latter.
+        await rs.hooks.fire("phone_setup_disabled", user=user)
         await rs.hooks.fire("mfa_disabled", user=user)
         return MessageResponse(message="SMS 2FA disabled.")
 

{regstack-0.8.0 → regstack-0.8.1}/src/regstack/routers/register.py

@@ -91,6 +91,7 @@ async def _start_verification(
         to=payload.email,
         full_name=payload.full_name,
         url=url,
+        ttl_hours=max(ttl // 3600, 1),
     )
     await rs.email.send(message)
     await rs.hooks.fire("verification_requested", email=payload.email, url=url)