regstack 0.6.0__tar.gz → 0.8.0__tar.gz

{regstack-0.6.0 → regstack-0.8.0}/CHANGELOG.md

@@ -5,6 +5,220 @@ authoritative copy lives at
 [`docs/changelog.md`](docs/changelog.md) and is rendered into the
 Sphinx docs.
 
+## Unreleased
+
+## 0.8.0 — 2026-05-19
+
+`regstack ses setup` guided wizard, plus two security fixes from
+the 2026-05-18 daily review.
+
+**Added: `regstack ses setup`.** A pywebview wizard for the SES
+email backend, mirroring the existing `regstack oauth setup` flow.
+Nine steps walk through region selection, credential source
+(`profile` / `explicit` / `chain`), sender-domain identity
+verification (via SES `GetIdentityVerificationAttributes`),
+sandbox detection (via `GetAccount` with `GetSendQuota` heuristic
+fallback for IAM-restricted policies), and a live test send.
+Non-clobbering tomlkit + secrets.env merge. Headless
+`--print-only` mode for CI / scripting. Gated behind the joint
+extra: `pip install 'regstack[wizard,ses]'`.
+
+**Fixed: theme-designer preview no longer ships well-known credentials
+in the wheel.** `designer.html` had `alice@example.com` /
+`hunter2hunter2` as `value=` attributes on its login-form preview;
+flipped to `placeholder=` so the wheel doesn't carry well-known
+example creds that could be mistaken for real fixtures.
+(Daily security review 2026-05-18 · I-1.)
+
+**Fixed: Google OAuth token-exchange error no longer echoes the
+response body.** `exchange_code()` previously raised
+`OAuthTokenExchangeError(f"... {body!r}")` on the rare 200-without-id_token
+edge case. The body can contain a live short-lived `access_token` in
+that path, and the OAuth router logs the exception text at WARNING.
+Dropped `{body!r}` from the message; regression test in
+`tests/unit/test_oauth_google.py` pins that a planted token never
+appears in the exception's `str()` or `args`.
+(Daily security review 2026-05-18 · I-2.)
+
+## 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-0.6.0 → regstack-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.6.0
+Version: 0.8.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
@@ -28,7 +28,7 @@ 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: python-multipart>=0.0.27
 Requires-Dist: sqlalchemy[asyncio]>=2.0
 Provides-Extra: dev
 Requires-Dist: anyio>=4.3; extra == 'dev'
@@ -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), and `regstack doctor` (config validator)
+✔ 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)
 ✔ Three storage backends: SQLite, PostgreSQL, MongoDB — chosen by URL
 ```
 

{regstack-0.6.0 → regstack-0.8.0}/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), and `regstack doctor` (config validator)
+✔ 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)
 ✔ Three storage backends: SQLite, PostgreSQL, MongoDB — chosen by URL
 ```
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "regstack"
-version = "0.6.0"
+version = "0.8.0"
 description = "Embeddable user registration, login, and account management for FastAPI apps. SQLite / Postgres / MongoDB."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -31,9 +31,10 @@ dependencies = [
     "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.
@@ -118,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.6.0 → regstack-0.8.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.6.0 → regstack-0.8.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.6.0 → regstack-0.8.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",
 }
 
 

regstack-0.8.0/src/regstack/backends/mongo/indexes.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from pymongo import ASCENDING, IndexModel
+
+if TYPE_CHECKING:
+    from pymongo.asynchronous.database import AsyncDatabase
+
+    from regstack.backends.mongo.client import MongoDoc
+    from regstack.config.schema import RegStackConfig
+
+log = logging.getLogger(__name__)
+
+
+async def install_indexes(db: AsyncDatabase[MongoDoc], config: RegStackConfig) -> None:
+    """Create the indexes regstack relies on. Safe to call repeatedly."""
+    users = db[config.user_collection]
+    await _drop_conflicting_email_index(users)
+    await users.create_indexes(
+        [IndexModel([("email", ASCENDING)], unique=True, name="email_unique")]
+    )
+
+    blacklist = db[config.blacklist_collection]
+    # TTL on `exp` lets MongoDB reap revoked tokens when they would have
+    # expired anyway. expireAfterSeconds=0 means "delete when the date is
+    # in the past" — the value at `exp` is the deletion deadline.
+    await blacklist.create_indexes(
+        [
+            IndexModel([("jti", ASCENDING)], unique=True, name="jti_unique"),
+            IndexModel([("exp", ASCENDING)], expireAfterSeconds=0, name="exp_ttl"),
+        ]
+    )
+
+    pending = db[config.pending_collection]
+    await pending.create_indexes(
+        [
+            IndexModel([("email", ASCENDING)], unique=True, name="pending_email_unique"),
+            IndexModel([("token_hash", ASCENDING)], unique=True, name="pending_token_unique"),
+            IndexModel([("expires_at", ASCENDING)], expireAfterSeconds=0, name="pending_ttl"),
+        ]
+    )
+
+    attempts = db[config.login_attempt_collection]
+    # Sparse-ish TTL — rows survive `login_lockout_window_seconds` after
+    # `when`. The TTL value comes from config so tightening the lockout
+    # window also tightens cleanup.
+    await attempts.create_indexes(
+        [
+            IndexModel([("email", ASCENDING), ("when", ASCENDING)], name="email_when"),
+            IndexModel(
+                [("when", ASCENDING)],
+                expireAfterSeconds=config.login_lockout_window_seconds,
+                name="when_ttl",
+            ),
+        ]
+    )
+
+    mfa = db[config.mfa_code_collection]
+    await mfa.create_indexes(
+        [
+            IndexModel(
+                [("user_id", ASCENDING), ("kind", ASCENDING)],
+                unique=True,
+                name="user_kind_unique",
+            ),
+            IndexModel([("expires_at", ASCENDING)], expireAfterSeconds=0, name="mfa_ttl"),
+        ]
+    )
+
+    oauth_identities = db[config.oauth_identity_collection]
+    await oauth_identities.create_indexes(
+        [
+            IndexModel(
+                [("provider", ASCENDING), ("subject_id", ASCENDING)],
+                unique=True,
+                name="provider_subject_unique",
+            ),
+            IndexModel(
+                [("user_id", ASCENDING), ("provider", ASCENDING)],
+                unique=True,
+                name="user_provider_unique",
+            ),
+        ]
+    )
+
+    oauth_states = db[config.oauth_state_collection]
+    await oauth_states.create_indexes(
+        [
+            IndexModel(
+                [("expires_at", ASCENDING)],
+                expireAfterSeconds=0,
+                name="oauth_state_ttl",
+            ),
+        ]
+    )
+    await _ensure_oauth_states_validator(db, config.oauth_state_collection)
+
+    log.info("regstack indexes installed on database %s", db.name)
+
+
+async def _drop_conflicting_email_index(users: Any) -> None:
+    """Drop an unnamed unique index on ``email`` left over from a host's
+    pre-regstack auth code.
+
+    Mongo cannot rename an index in place. Hosts that previously ran
+    ``db.users.create_index([("email", ASCENDING)], unique=True)`` from
+    their own code end up with the auto-generated name ``email_1`` on
+    the same key + uniqueness regstack wants under ``email_unique``.
+    A fresh ``install_indexes`` then raises ``IndexOptionsConflict``
+    on its first boot under regstack.
+
+    This helper detects ANY index over exactly ``{"email": 1}`` with
+    ``unique=True`` that is not already named ``email_unique``, and
+    drops it so the canonical-name create on the next line succeeds.
+    We deliberately do not require the legacy name to be exactly
+    ``email_1`` — any other rename (e.g. a host that named theirs
+    ``users_email_uq``) would hit the same conflict.
+
+    Idempotent — re-running on a healthy database is a no-op because
+    the loop only matches indexes that aren't already the canonical
+    one. Safe even if the collection doesn't exist yet (the
+    ``index_information`` call returns an empty dict).
+    """
+    try:
+        existing = await users.index_information()
+    except Exception:  # pragma: no cover — defensive; missing namespace
+        return
+
+    for name, info in existing.items():
+        if name in ("_id_", "email_unique"):
+            continue
+        key = info.get("key")
+        if key != [("email", 1)]:
+            continue
+        if not info.get("unique"):
+            continue
+        log.warning(
+            "Dropping legacy unique-on-email index %r on %s.users to "
+            "make room for email_unique (regstack canonical name).",
+            name,
+            users.database.name,
+        )
+        await users.drop_index(name)
+
+
+async def _ensure_oauth_states_validator(db: AsyncDatabase[MongoDoc], collection_name: str) -> None:
+    """Pin ``oauth_states.mode`` to ``signin`` / ``link`` at the DB level.
+
+    Mirrors the SQL backend's ``CheckConstraint("mode IN ('signin', 'link')")``.
+    ``OAuthState.model_validate()`` already enforces this at the application
+    layer on every read, so this is defence-in-depth rather than a closed
+    exploit path — flagged as I-5 in the 2026-05-15 / 2026-05-16 security
+    reviews.
+
+    Uses ``validationLevel="moderate"`` so re-running ``install_indexes``
+    on a populated collection does not retroactively reject pre-existing
+    rows; the constraint applies to inserts and updates that touch
+    ``mode``.
+    """
+    from pymongo.errors import OperationFailure
+
+    validator = {
+        "$jsonSchema": {
+            "bsonType": "object",
+            "properties": {
+                "mode": {"enum": ["signin", "link"]},
+            },
+        }
+    }
+    try:
+        await db.command(
+            {
+                "collMod": collection_name,
+                "validator": validator,
+                "validationLevel": "moderate",
+                "validationAction": "error",
+            }
+        )
+    except OperationFailure as exc:
+        # collMod fails on a non-existent collection. Create it with the
+        # validator attached instead; either path leaves the collection
+        # with the schema in place.
+        if "NamespaceNotFound" not in str(exc) and exc.code != 26:  # 26 = NamespaceNotFound
+            raise
+        await db.create_collection(
+            collection_name,
+            validator=validator,
+            validationLevel="moderate",
+            validationAction="error",
+        )