regstack 0.5.9__tar.gz → 0.7.0__tar.gz

{regstack-0.5.9 → regstack-0.7.0}/.gitignore

@@ -32,3 +32,15 @@ docs/_autosummary/
 /regstack-bootstrap.json
 **/regstack.secrets.env
 **/regstack-bootstrap.json
+
+# Defensive: keep credential material out of any commit, even from a
+# misconfigured local dev env. None of these are checked in today, but
+# the .env / *.pem / etc. patterns are recurring audit recommendations.
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+*.jks
+*.crt

{regstack-0.5.9 → regstack-0.7.0}/CHANGELOG.md

@@ -5,6 +5,276 @@ authoritative copy lives at
 [`docs/changelog.md`](docs/changelog.md) and is rendered into the
 Sphinx docs.
 
+## Unreleased
+
+## 0.7.0 — 2026-05-17
+
+Two-week sprint that lands the `regstack validate` end-to-end probe,
+seven security-review findings, a clutch of host-integration
+ergonomic wins (per-link email URL templates, optional auth
+dependency, admin `promote_pending`, explicit SES credentials), and
+two breaking API trims (`UserPublic._id` → `id`,
+`TokenTransport = "bearer"` only).
+
+The headline is `regstack validate` — a new CLI command that drives
+a real deployed install through every auth flow (register, verify,
+login, logout, password reset, change-email, OAuth start, SMS 2FA)
+from a remote operator workstation, scraping one-time tokens out of
+the deployment's stdout via a `--log-source` of your choice
+(`file:`, `ssh:`, `docker:`, `cmd:`). The companion to `regstack
+doctor`: doctor checks the loaded config, validate checks the
+running service.
+
+**Breaking.**
+
+- **`UserPublic` JSON key is `id`, not `_id`.** The `alias="_id"`
+  on `UserPublic.id` (and the accompanying `populate_by_name=True`)
+  is removed. Every endpoint returning a `UserPublic` —
+  `POST /api/auth/register`, `GET /api/auth/me`, `PATCH /api/auth/me`,
+  and the admin user endpoints — now sends `id` on the wire.
+  `BaseUser` (the Mongo-document model) keeps the alias because it
+  round-trips to BSON via `to_mongo()`; only the API contract is
+  touched. Clients that read `body["_id"]` should switch to
+  `body["id"]`. Hosts hand-rolling a `/me` override solely to swap
+  the key shape can drop it.
+- **`TokenTransport` literal narrowed to `Literal["bearer"]`.**
+  `"cookie"` was previously accepted by config validation but
+  silently no-op'd (no router ever set `Set-Cookie`). Hosts that
+  set `transport = "cookie"` now get a clear pydantic
+  `literal_error` at startup instead of a silent
+  security-misconfiguration. `RegStackConfig.cookie_domain` is
+  removed along with it. `regstack init` no longer offers the
+  cookie option either.
+
+**Added.**
+
+- **`regstack validate`.** End-to-end probe of a deployed install
+  — registers a throwaway user, walks every auth flow, then
+  deletes it. Reads one-time tokens out of the deployment's
+  stdout via `--log-source` (file / ssh / docker / arbitrary
+  command). Skip phases with `--skip`. Companion to `regstack
+  doctor` (which only validates loaded config). See
+  `regstack validate --help` for the full operator runbook.
+- **`email.log_bodies` and `sms.log_bodies` config flags** to
+  promote the console / null backends' body log lines from
+  DEBUG → INFO without enabling DEBUG globally. `email.log_bodies`
+  defaults to `False`; `sms.log_bodies` defaults to `True`
+  (preserves prior null-SMS behaviour). Other backends ignore.
+- **`RegStackConfig.email_link_prefix` + auto-resolve from
+  `ui_prefix`.** Verification / reset / email-change links now
+  default to `<base_url><ui_prefix>/verify?token=...` when the
+  bundled UI router is enabled, instead of bare `/verify`. Hosts
+  whose SPA owns the auth pages can pin a path explicitly via
+  `email_link_prefix`; the bundled UI hosts get the right links
+  automatically.
+- **`EmailConfig.from_name` defaults to `app_name`** when unset.
+  Hosts that change `app_name` to brand outgoing email also get
+  the matching `From:` header automatically. Explicit `from_name`
+  values still win.
+- **Per-link email URL templates.** Three new optional fields on
+  `RegStackConfig` — `verify_url_template`,
+  `password_reset_url_template`, `email_change_url_template` —
+  let SPAs whose router shape doesn't fit
+  `/verify?token=...` rewrite the email links. Templates
+  substitute `{base_url}` and `{token}` literally. Hash-routed
+  SPA: `"{base_url}/#/verify/{token}"`. Sibling subdomain:
+  `"https://auth.example.com/verify/{token}"`. Default unset
+  falls back to the prefix-based composition above. New helpers
+  `RegStackConfig.resolve_{verify,password_reset,email_change}_url(token)`.
+- **`current_user_optional` dependency.** Companion to
+  `current_user` / `current_admin` on `regstack.deps`. Returns
+  `BaseUser | None` instead of raising 401, for endpoints that
+  render differently for signed-in vs anonymous callers (cart
+  icon, comment-author prefill). Every form of auth failure —
+  missing header, wrong scheme, malformed / expired / revoked
+  token, deleted or bulk-revoked user — collapses to `None`.
+- **`RegStack.promote_pending(email)` + admin route.** Converts
+  a `PendingRegistration` row directly into a verified active
+  user, bypassing the email-link round-trip. Hashed password and
+  full name carry over verbatim. Fires the same `user_verified`
+  hook as `POST /verify`. Useful for admin rescue of stuck
+  signups, batch seeding from a known-good list, and dev
+  fixtures. Exposed as `POST /admin/pending/{email}/promote`
+  when the admin router is enabled.
+- **Explicit SES credential fields on `EmailConfig`.** New
+  `ses_access_key_id` / `ses_secret_access_key` (both `SecretStr |
+  None`) let hosts pass AWS creds directly instead of relying on
+  boto3's env-var fallthrough. Validated as a pair, mutually
+  exclusive with `ses_profile`.
+
+**Security.**
+
+- **CVE-2026-42561 — `python-multipart>=0.0.27`.** Closes a
+  network-exploitable DoS via unbounded multipart part-header
+  parsing (CVSS 7.5). Previous floor `>=0.0.26` had the earlier
+  CVE-2026-40347 fix only.
+- **sdist no longer ships internal docs to PyPI.** Added a
+  `[tool.hatch.build.targets.sdist]` exclude block. The published
+  source tarball used to contain `CLAUDE.md` (with a developer
+  home-directory path), the security-review prompt, the full test
+  suite, build tooling, and (when built from a worktree) a `.git`
+  text file pointing at the operator's worktrees directory.
+- **Defensive `ObjectId.is_valid()` on nine Mongo UserRepo
+  mutations.** `set_last_login`, `set_tokens_invalidated_after`,
+  `update_password`, `set_active`, `set_superuser`, `set_full_name`,
+  `set_phone`, `set_mfa_enabled`, and `update_email` now match
+  `get_by_id` / `delete`: invalid input no-ops instead of raising
+  `bson.errors.InvalidId` (which would have surfaced as a 500 on
+  any future caller passing raw external input).
+- **Per-IP rate-limit map covers `/login/mfa-confirm` and
+  `/oauth/exchange`.** Two new config fields:
+  `login_mfa_confirm_rate_limit`, `oauth_exchange_rate_limit`.
+  The per-code attempt counter on `mfa_codes` defends each
+  individual code; this adds the per-IP layer against distributed
+  guessing across many source IPs.
+- **OAuth callback `error` query parameter sanitized before
+  logging.** A compromised or malicious OAuth provider could
+  previously inject newlines / ANSI escapes into the log stream
+  via the `error=...` redirect. The callback now strips control
+  characters and caps length at 200 before logging.
+- **`oauth_states.mode` validated at the MongoDB storage layer.**
+  A `$jsonSchema` validator on the collection enforces
+  `mode IN ('signin', 'link')`, matching the SQL backend's
+  existing `CheckConstraint`. `OAuthState.model_validate()`
+  already enforced this at the app layer; this is defence-in-depth.
+- **Migration `0002` downgrade refuses to roll back when OAuth-only
+  users exist.** The downgrade re-applies `NOT NULL` to
+  `users.hashed_password`; if any row has `NULL` (OAuth-only
+  signup), it now raises `RuntimeError` with a clear remediation
+  message instead of silently succeeding on SQLite (where
+  `batch_alter_table`'s CREATE-COPY-DROP-RENAME path skipped
+  NOT NULL enforcement).
+- **PEP 740 sigstore attestations on the PyPI publish workflow.**
+  Each published wheel / sdist is now cryptographically bound to
+  the specific GitHub Actions run that produced it, so consumers
+  can verify the artefact came from this repo's CI.
+- **`workflow_dispatch` removed from `publish.yml`.** Manual runs
+  previously uploaded artefacts to Actions storage with no
+  version validation, where they could be confused with a real
+  release build. Tag-push is the only supported trigger.
+
+**Fixed.**
+
+- **`regstack doctor --send-test-email` honours the new `from_name`
+  fall-back.** Before, the probe path passed `config.email.from_name`
+  (now `Optional[str]`) straight into `EmailMessage.from_name`
+  (typed `str`), producing a `None <addr>` From: header when
+  unset.
+- **`install_schema()` survives a legacy unnamed unique-on-email
+  index.** A host that previously ran
+  `db.users.create_index([("email", 1)], unique=True)` from its
+  own pre-regstack auth code has a Mongo-auto-named `email_1`
+  index. `install_indexes` previously crashed on first boot with
+  `IndexOptionsConflict`. It now detects any unnamed/legacy
+  unique index over `{"email": 1}`, drops it, and proceeds.
+  Idempotent on a healthy DB.
+- **`POST /verify` no longer 500s on the admin-promote-meets-user-
+  clicks-verify race.** The endpoint now catches
+  `UserAlreadyExistsError` from `users.create` and returns a
+  graceful 400 ("This email is already registered. Please sign
+  in.") instead of letting the unique-constraint violation bubble
+  up as a 500.
+
+**Internal.**
+
+- **GitHub Actions pinned ahead of Node 20 deprecation.**
+  `actions/checkout` v4→v6.0.2, `astral-sh/setup-uv` v3→v8.1.0,
+  `actions/upload-artifact` v4→v7.0.1, `actions/download-artifact`
+  v4→v8.0.1. All pins remain commit SHAs.
+- **Daily scheduled security-review reports** land under
+  `docs/security-reports/` for 2026-05-15 through 2026-05-17.
+  The 2026-05-17 report is `[security-clean]`: all warnings from
+  the prior two days resolved in this release.
+
+## 0.6.0 — 2026-05-14
+
+**Breaking change for wizard users.** The GUI setup wizards
+(`regstack oauth setup`, `regstack theme design`) are now behind a
+new optional `wizard` extra. `pip install regstack` no longer pulls
+in `pywebview`, `tomlkit`, or `uvicorn[standard]` — three heavy
+wizard-only dependencies that every library consumer was paying for,
+including a platform browser engine on every fresh install. A
+recurring audit recommendation since 0.5.0.
+
+**Migration.**
+
+- If you only embed regstack in a FastAPI app (no `regstack oauth
+  setup` or `regstack theme design`): no action needed. The base
+  install is now significantly slimmer.
+- If you use either setup wizard: install the new extra —
+  `pip install 'regstack[wizard]'` or `uv sync --extra wizard`.
+  Running a wizard subcommand without the extra now exits with a
+  one-line install hint (no ImportError traceback).
+- The `dev` extra continues to pull in the wizard deps directly so
+  `inv test-all` keeps working without an explicit `--extra wizard`.
+
+Bumped to **0.6.0** (not 0.5.12) because removing top-level deps is
+the kind of change that can surprise downstream `pip install
+regstack` callers — even though "the GUI wizard CLIs need an extra
+now" is the only observable effect.
+
+## 0.5.11 — 2026-05-14
+
+CI / workflow hygiene. No runtime code changes.
+
+- **All third-party GitHub Actions pinned to commit SHAs.**
+  `actions/checkout@v4`, `astral-sh/setup-uv@v3`,
+  `actions/upload-artifact@v4`, and `actions/download-artifact@v4` now
+  use commit SHAs in `.github/workflows/publish.yml` and
+  `.github/workflows/test.yml`, with `# v4` / `# v3` trailing comments
+  so future operators can resolve and bump. `pypa/gh-action-pypi-publish`
+  was already SHA-pinned (#37). A tag swap upstream can no longer
+  substitute a malicious version.
+- **`permissions:` blocks added to every workflow + job.** Both
+  workflows now declare a `permissions: contents: read` default at
+  the workflow level and re-state it per job (so a future addition of
+  a write-needing action doesn't silently inherit elevated scopes).
+  The `publish` job continues to declare `id-token: write` (OIDC
+  trusted-publisher exchange) — that's the only scope above
+  read-only anywhere in the workflows.
+- **`.gitignore` defensive additions.** `.env`, `.env.*`, and the
+  common credential-file patterns (`*.pem`, `*.key`, `*.p12`,
+  `*.pfx`, `*.jks`, `*.crt`) are now ignored at the repo root. None
+  are present today; this is belt-and-braces for misconfigured local
+  dev environments. A recurring audit recommendation.
+
+## 0.5.10 — 2026-05-14
+
+Security fixes from the 2026-05-13 / 2026-05-14 daily reviews. All
+warnings, no criticals — but several are real exploitable issues.
+
+**Security.**
+
+- **Open-redirect bypass in OAuth `redirect_to`.** `_validate_redirect`
+  was forwarding `urlsplit`'s judgment, but browsers normalize values
+  like `/\evil.com` and `////evil.com` into the protocol-relative
+  `//evil.com` — both of which `urlsplit` reports as same-origin
+  paths. The validator now rejects any backslash plus any value that
+  doesn't start with a single `/` followed by a non-slash character.
+- **CVE-2025-62727 — `fastapi` floor raised to `>=0.120.0`.** Starlette
+  DoS via large request bodies after multipart processing.
+- **CVE-2025-27516 — `jinja2` floor raised to `>=3.1.6`.** Sandbox
+  breakout via the `|attr` filter (only relevant if hosts allow
+  user-controlled templates; tightening the floor regardless).
+- **Login lockout no longer skips disabled / unverified accounts.**
+  `POST /login` now records a failure before raising HTTP 403 for
+  `is_active=False` and (when `require_verification=True`)
+  `is_verified=False` users. Password verification was also re-ordered
+  to run **before** those checks, so an attacker without the password
+  can't distinguish disabled vs active accounts by HTTP code alone.
+- **`POST /change-email` no longer enumerates registered addresses.**
+  An authenticated attacker could previously iterate the email
+  namespace via the 409 vs 202 response distinction. The endpoint now
+  always returns 202; if the candidate is already registered, no
+  confirmation email is sent (the legitimate user finds out by not
+  receiving it). Matches the existing anti-enumeration stance on
+  `/forgot-password` and `/resend-verification`.
+- **Admin resend-verification rejects OAuth-only users.** Previously
+  attempted to construct a `PendingRegistration` from a user with
+  `hashed_password=None`, which either failed validation or stored
+  the literal string `"None"` in the pending row. Now returns 400
+  with a clear message.
+
 ## 0.5.9 — 2026-05-13
 
 **`OAuthConfig.enforce_mfa_on_oauth_signin` is now wired.** The flag

{regstack-0.5.9 → regstack-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.5.9
+Version: 0.7.0
 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
@@ -22,17 +22,14 @@ Requires-Dist: alembic>=1.13
 Requires-Dist: click>=8.1
 Requires-Dist: dnspython>=2.6
 Requires-Dist: email-validator>=2.1
-Requires-Dist: fastapi>=0.110
-Requires-Dist: jinja2>=3.1
+Requires-Dist: fastapi>=0.120.0
+Requires-Dist: jinja2>=3.1.6
 Requires-Dist: pwdlib[argon2]>=0.2.1
 Requires-Dist: pydantic-settings>=2.2
 Requires-Dist: pydantic>=2.6
 Requires-Dist: pyjwt>=2.12.1
-Requires-Dist: python-multipart>=0.0.26
-Requires-Dist: pywebview>=5.0
+Requires-Dist: python-multipart>=0.0.27
 Requires-Dist: sqlalchemy[asyncio]>=2.0
-Requires-Dist: tomlkit>=0.13
-Requires-Dist: uvicorn[standard]>=0.29
 Provides-Extra: dev
 Requires-Dist: anyio>=4.3; extra == 'dev'
 Requires-Dist: asyncpg>=0.29; extra == 'dev'
@@ -47,8 +44,10 @@ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest-playwright>=0.5; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pywebview>=5.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Requires-Dist: slowapi>=0.1.9; extra == 'dev'
+Requires-Dist: tomlkit>=0.13; extra == 'dev'
 Requires-Dist: uvicorn[standard]>=0.29; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: furo>=2024.1; extra == 'docs'
@@ -72,6 +71,10 @@ Provides-Extra: sns
 Requires-Dist: aioboto3>=12.3; extra == 'sns'
 Provides-Extra: twilio
 Requires-Dist: twilio>=9.0; extra == 'twilio'
+Provides-Extra: wizard
+Requires-Dist: pywebview>=5.0; extra == 'wizard'
+Requires-Dist: tomlkit>=0.13; extra == 'wizard'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'wizard'
 Description-Content-Type: text/markdown
 
 # regstack

{regstack-0.5.9 → regstack-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "regstack"
-version = "0.5.9"
+version = "0.7.0"
 description = "Embeddable user registration, login, and account management for FastAPI apps. SQLite / Postgres / MongoDB."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -17,29 +17,30 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "fastapi>=0.110",
+    # fastapi>=0.120.0 picks up CVE-2025-62727 (Starlette DoS via large
+    # request bodies after multipart processing).
+    "fastapi>=0.120.0",
     "pydantic>=2.6",
     "pydantic-settings>=2.2",
     "pwdlib[argon2]>=0.2.1",
     # pyjwt>=2.12.1 includes the fix for CVE-2026-32597 (`crit` header bypass).
     "pyjwt>=2.12.1",
-    "jinja2>=3.1",
+    # jinja2>=3.1.6 picks up CVE-2025-27516 (sandbox breakout via the
+    # `|attr` filter; only relevant if hosts allow user-controlled
+    # templates, but we tighten the floor anyway).
+    "jinja2>=3.1.6",
     "click>=8.1",
     "dnspython>=2.6",
-    # python-multipart>=0.0.26 picks up CVE-2026-40347 (DoS via oversized
-    # multipart preamble).
-    "python-multipart>=0.0.26",
+    # python-multipart>=0.0.27 picks up CVE-2026-40347 (DoS via oversized
+    # multipart preamble) and CVE-2026-42561 (DoS via unbounded part-header
+    # count/size — CVSS 7.5, network-exploitable).
+    "python-multipart>=0.0.27",
     "email-validator>=2.1",
     "aiosmtplib>=3.0",
     # SQL stack — bundled by default because SQLite is the default backend.
     "sqlalchemy[asyncio]>=2.0",
     "aiosqlite>=0.20",
     "alembic>=1.13",
-    # OAuth setup wizard (regstack oauth setup) — needs a webview shell,
-    # a small in-process FastAPI server, and round-trip-safe TOML editing.
-    "pywebview>=5.0",
-    "tomlkit>=0.13",
-    "uvicorn[standard]>=0.29",
 ]
 
 [project.optional-dependencies]
@@ -51,6 +52,16 @@ twilio = ["twilio>=9.0"]
 # cryptography>=46.0.7 picks up CVE-2026-26007 (ECC subgroup attack on the
 # JWKS code path) plus CVE-2026-34073 and CVE-2026-39892.
 oauth = ["pyjwt[crypto]>=2.12.1", "cryptography>=46.0.7"]
+# Interactive setup wizards (`regstack oauth setup`, `regstack theme
+# design`). These open a native pywebview window over a local 127.0.0.1
+# FastAPI server and use tomlkit for non-destructive TOML merging.
+# Optional because library consumers who never run the GUI tools don't
+# need a platform browser engine pulled in by pywebview.
+wizard = [
+    "pywebview>=5.0",
+    "tomlkit>=0.13",
+    "uvicorn[standard]>=0.29",
+]
 # Per-route rate limiting on the auth router. The limiter itself can be
 # host-supplied (so hosts that already use slowapi share the same Limiter
 # state), otherwise regstack constructs an in-memory one.
@@ -86,6 +97,10 @@ dev = [
     "pytest-playwright>=0.5",
     # Rate-limit tests exercise the slowapi integration.
     "slowapi>=0.1.9",
+    # Wizard surface (now an optional `wizard` extra) — tests exercise
+    # the setup/theme-designer routes, writers, and Playwright e2e.
+    "pywebview>=5.0",
+    "tomlkit>=0.13",
 ]
 
 [project.scripts]
@@ -104,6 +119,34 @@ packages = ["src/regstack"]
 # Hatch's package autodiscovery already picks up template / static assets
 # under src/regstack — no force-include needed (it would double-pack).
 
+[tool.hatch.build.targets.sdist]
+# Hatchling's sdist default includes every git-tracked file. Without this
+# block the published source tarball ships internal planning docs,
+# security-review prompts, the full test suite, and CI configuration to
+# anyone who runs `pip download --no-binary`. The wheel target above is
+# already tight (src/regstack only); this list is the matching sdist
+# discipline. Flagged as W-2 in the 2026-05-15 / 2026-05-16 security
+# reviews — CLAUDE.md in particular contains a developer home path.
+exclude = [
+    ".git",
+    ".github/",
+    ".python-version",
+    ".readthedocs.yaml",
+    "CLAUDE.md",
+    "docs/",
+    "examples/",
+    "scripts/",
+    "tasks.py",
+    "tasks/",
+    "tests/",
+    "uv.lock",
+]
+# Note on `.git`: hatchling normally skips it because it's a directory, but
+# when this repo is built from a git *worktree* (e.g. release prep on a
+# branch), `.git` is a 1-line text file containing an absolute path to the
+# primary repo's worktrees dir — which leaks the developer's home directory
+# into PyPI. Excluding it explicitly is harmless for non-worktree builds.
+
 [tool.pytest.ini_options]
 minversion = "8.0"
 asyncio_mode = "auto"

{regstack-0.5.9 → regstack-0.7.0}/src/regstack/app.py

@@ -341,6 +341,60 @@ class RegStack:
         )
         return await self.users.create(user)
 
+    async def promote_pending(self, email: str) -> BaseUser:
+        """Convert a pending registration directly into a verified user.
+
+        Bypasses the email-link round-trip. Useful when:
+
+        - a user lost their verification link and ``resend-verification``
+          isn't an option (admin-triggered onboarding, dev fixtures);
+        - a CLI batch operation seeds users from a known-good list;
+        - an admin is rescuing a stuck signup.
+
+        The pending row's ``hashed_password`` and ``full_name`` carry
+        over verbatim — the user logs in with the password they
+        originally registered with. The pending row is deleted on
+        success. Fires the ``user_verified`` hook so analytics /
+        downstream listeners see the same event the email-driven
+        ``POST /verify`` produces.
+
+        Args:
+            email: The email address whose pending registration should
+                be promoted.
+
+        Returns:
+            The newly persisted, active, verified
+            :class:`~regstack.models.user.BaseUser`.
+
+        Raises:
+            LookupError: If no pending registration exists for that
+                email (caller's job to surface as 404 / CLI error).
+            UserAlreadyExistsError: If a non-pending user with that
+                email already exists (caller's job to surface as 409).
+        """
+        pending = await self.pending.find_by_email(email)
+        if pending is None:
+            raise LookupError(f"No pending registration for {email!r}.")
+        # Match ``POST /verify``'s contract: an expired pending row is
+        # not a valid promotion target. Mongo's TTL reap is eventual
+        # and the SQL backends only purge on ``purge_expired()``, so a
+        # row past its window can still appear here. Treat it as
+        # missing rather than silently promoting a stale invitation.
+        if pending.expires_at <= self.clock.now():
+            await self.pending.delete_by_email(pending.email)
+            raise LookupError(f"Pending registration for {email!r} has expired.")
+        user = BaseUser(
+            email=pending.email,
+            hashed_password=pending.hashed_password,
+            full_name=pending.full_name,
+            is_active=True,
+            is_verified=True,
+        )
+        user = await self.users.create(user)
+        await self.pending.delete_by_email(pending.email)
+        await self.hooks.fire("user_verified", user=user)
+        return user
+
     # --- Extension surface ------------------------------------------------
 
     def set_email_backend(self, service: EmailService) -> None:

{regstack-0.5.9 → regstack-0.7.0}/src/regstack/auth/dependencies.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Awaitable, Callable
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Optional
 
 from fastapi import Depends, HTTPException, Request, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
@@ -14,6 +14,10 @@ if TYPE_CHECKING:
     from regstack.models.user import BaseUser
 
 UserDependency = Callable[..., Awaitable["BaseUser"]]
+# typing.Optional avoids a PEP-604 union-inside-string-forward-ref,
+# which some mypy / pyright configurations refuse to resolve when
+# BaseUser is only imported under TYPE_CHECKING.
+OptionalUserDependency = Callable[..., Awaitable[Optional["BaseUser"]]]
 
 _bearer = HTTPBearer(auto_error=False)
 
@@ -82,6 +86,37 @@ class AuthDependencies:
 
         return _dep
 
+    def current_user_optional(self) -> OptionalUserDependency:
+        """Return a FastAPI dependency that yields the user or ``None``.
+
+        For endpoints that render differently for authenticated vs
+        anonymous callers (think "show your cart icon if logged in").
+        Treats every form of auth failure — missing header, bad scheme,
+        expired token, revoked jti, deleted user, bulk-revoked session
+        — as anonymous and returns ``None`` rather than raising 401.
+
+        On success the user is stashed on
+        ``request.state.regstack_user`` (same as :meth:`current_user`),
+        so downstream middleware sees the same shape for either path.
+
+        Returns:
+            A callable suitable for ``Depends(...)``. Never raises an
+            ``HTTPException`` — auth problems collapse to ``None``.
+        """
+
+        async def _dep(
+            request: Request,
+            creds: HTTPAuthorizationCredentials | None = Depends(_bearer),
+        ) -> BaseUser | None:
+            try:
+                user = await self._authenticate(creds)
+            except HTTPException:
+                return None
+            request.state.regstack_user = user
+            return user
+
+        return _dep
+
     def current_admin(self) -> UserDependency:
         """Return a FastAPI dependency that yields a *superuser*.
 

{regstack-0.5.9 → regstack-0.7.0}/src/regstack/auth/rate_limit.py

@@ -43,6 +43,7 @@ if TYPE_CHECKING:
 # decoration walks the assembled APIRouter and matches by `route.path`.
 ROUTE_LIMIT_MAP: dict[str, str] = {
     "login_rate_limit": "/login",
+    "login_mfa_confirm_rate_limit": "/login/mfa-confirm",
     "register_rate_limit": "/register",
     "forgot_password_rate_limit": "/forgot-password",
     "reset_password_rate_limit": "/reset-password",
@@ -52,6 +53,7 @@ ROUTE_LIMIT_MAP: dict[str, str] = {
     "change_email_rate_limit": "/change-email",
     "confirm_email_change_rate_limit": "/confirm-email-change",
     "delete_account_rate_limit": "/account",
+    "oauth_exchange_rate_limit": "/oauth/exchange",
 }