regstack 0.2.5__tar.gz → 0.3.0__tar.gz

{regstack-0.2.5 → regstack-0.3.0}/CHANGELOG.md

@@ -5,6 +5,53 @@ authoritative copy lives at
 [`docs/changelog.md`](docs/changelog.md) and is rendered into the
 Sphinx docs.
 
+## 0.3.0 — 2026-04-30
+
+**OAuth — Sign in with Google.** Opt-in via the new `oauth` extra
+and `enable_oauth=True`. Five JSON endpoints, an SSR
+`/account/oauth-complete` page, "Sign in with Google" button on the
+login page, and a Connected-accounts panel on `/account/me`.
+
+Schema migration `0002_oauth.py` creates `oauth_identities` +
+`oauth_states` and makes `users.hashed_password` nullable
+(OAuth-only users have no password). Roll forward via
+`regstack migrate` or first-boot `install_schema()` — no manual
+intervention.
+
+Account-linking policy defaults to **refuse**: if a Google sign-in
+arrives carrying an email that already belongs to a password-
+registered user, the callback returns `?error=email_in_use` and the
+user must sign in then explicitly link from `/account/me`. Hosts
+that consciously accept the email-recycling threat for UX can flip
+`oauth.auto_link_verified_emails = true`. See
+[`docs/oauth.md`](https://regstack.readthedocs.io/en/latest/oauth.html)
+and [`tasks/oauth-design.md`](https://github.com/jdrumgoole/regstack/blob/main/tasks/oauth-design.md)
+for the full threat model.
+
+**Migration**
+
+- Install the new extra: `uv add 'regstack[oauth]'`.
+- Set `enable_oauth = true` and provide `oauth.google_client_id` +
+  `oauth.google_client_secret`.
+- Run `regstack migrate` (SQL backends only) or rely on
+  `install_schema()` at first boot.
+
+`BaseUser.hashed_password` is now `str | None`. Code that imported
+the field type explicitly will need to widen it.
+
+## 0.2.6 — 2026-04-28
+
+Bug fix.
+
+- **Fix:** `/admin/stats` reported `pending_registrations: 0` on
+  every SQL backend. The route reached into the Mongo repo's private
+  `_collection` attribute and silently fell back to `0` when the
+  attribute was absent. Added `count_unexpired(now=None)` to
+  `PendingRepoProtocol` with Mongo + SQL implementations and routed
+  through `rs.clock.now()` so the count respects the injected clock.
+  New parametrized integration test exercises the count on every
+  backend.
+
 ## 0.2.5 — 2026-04-28
 
 Bug fix + tooling.

{regstack-0.2.5 → regstack-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.2.5
+Version: 0.3.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
@@ -36,6 +36,7 @@ Requires-Dist: asyncpg>=0.29; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: invoke>=2.2; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pyjwt[crypto]>=2.8; extra == 'dev'
 Requires-Dist: pymongo>=4.9; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
@@ -52,6 +53,8 @@ Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
 Requires-Dist: sphinx>=7.3; extra == 'docs'
 Provides-Extra: mongo
 Requires-Dist: pymongo>=4.9; extra == 'mongo'
+Provides-Extra: oauth
+Requires-Dist: pyjwt[crypto]>=2.8; extra == 'oauth'
 Provides-Extra: postgres
 Requires-Dist: asyncpg>=0.29; extra == 'postgres'
 Provides-Extra: ses

{regstack-0.2.5 → regstack-0.3.0}/docs/changelog.md

@@ -3,6 +3,119 @@
 All notable changes to this project are documented here. Versions follow
 [Semantic Versioning](https://semver.org/) once `1.0.0` ships.
 
+## 0.3.0 — 2026-04-30
+
+**OAuth — Sign in with Google.** Built across four PRs (M1–M4 of
+[`tasks/oauth-design.md`](https://github.com/jdrumgoole/regstack/blob/main/tasks/oauth-design.md));
+this is the release cut that wraps them up.
+
+### Added
+
+- New optional extra `oauth = ["pyjwt[crypto]>=2.8"]`.
+- New `enable_oauth` flag and `OAuthConfig` sub-model
+  (`google_client_id`, `google_client_secret`, `google_redirect_uri`,
+  `auto_link_verified_emails`, `enforce_mfa_on_oauth_signin`,
+  `state_ttl_seconds`, `completion_ttl_seconds`).
+- `regstack.oauth` package — `OAuthProvider` ABC, `OAuthRegistry`,
+  `OAuthTokens`, `OAuthUserInfo`, error hierarchy, and the concrete
+  `GoogleProvider` (Authorization Code with PKCE, ID-token
+  verification via `pyjwt[crypto]` + `PyJWKClient` against Google's
+  JWKS).
+- Five JSON endpoints (mounted lazily when `enable_oauth=True` and a
+  provider is registered):
+  - `GET    /oauth/{provider}/start`
+  - `GET    /oauth/{provider}/callback`
+  - `POST   /oauth/exchange`
+  - `POST   /oauth/{provider}/link/start` (auth)
+  - `DELETE /oauth/{provider}/link` (auth)
+  - `GET    /oauth/providers` (auth)
+- New SSR page `/account/oauth-complete` (token-handoff round-trip).
+- "Sign in with Google" button on `/account/login` and a Connected-
+  accounts panel on `/account/me`. Login page surfaces callback
+  errors via `?error=<code>` with translated banners.
+- Two new repo protocols: `OAuthIdentityRepoProtocol`,
+  `OAuthStateRepoProtocol`. Mongo + SQL implementations with
+  parametrized integration tests over all three backends.
+- Four new hook events: `oauth_signin_started`,
+  `oauth_signin_completed`, `oauth_account_linked`,
+  `oauth_account_unlinked`.
+- `tests/_fake_google/` — in-process provider stub so the OAuth
+  test suite stays offline and parallel-safe.
+- New docs page [`docs/oauth.md`](oauth.md) — host guide.
+
+### Changed (potentially breaking)
+
+- **`BaseUser.hashed_password: str` → `str | None`.** OAuth-only
+  users have no password. The login route rejects password attempts
+  on these accounts with the same generic 401 wrong-password gets
+  (no enumeration). `change-password`, `change-email`, and
+  `delete-account` all return 400 for OAuth-only users with a
+  pointer at the password-reset flow, which doubles as a "set
+  initial password" path.
+- `users.hashed_password` is now nullable in the SQL schema —
+  migration `0002_oauth.py` flips the column via `batch_alter_table`
+  (SQLite-safe). Existing rows are unaffected.
+- New SQL tables `oauth_identities` and `oauth_states`. Mongo
+  collections + indexes added by `install_schema()`.
+
+### Security defaults
+
+- **Account-linking policy defaults to refuse.** When a Google
+  sign-in carries an email that already belongs to a regstack user,
+  the callback returns `?error=email_in_use`. Hosts can opt into
+  auto-linking via `oauth.auto_link_verified_emails = true`, which
+  also requires `email_verified=true` on the ID token. The threat
+  model is in `tasks/oauth-design.md` § 1.
+- **Server-side PKCE.** `code_verifier` is stored on the
+  `oauth_states` row and never enters the URL.
+- **One-time token-handoff.** `/oauth/exchange` consumes the state
+  row atomically; second exchange returns 404.
+- **Refuse to unlink the only sign-in method.** Returns 400 for
+  OAuth-only users attempting to unlink their only provider.
+- **OAuth sessions are normal session JWTs** — the existing
+  `tokens_invalidated_after` bulk-revoke applies, so a password
+  change kills any OAuth-issued session too.
+
+### Migration notes
+
+- Install the extra: `uv add 'regstack[oauth]'`.
+- Configure: set `enable_oauth = true` and provide
+  `oauth.google_client_id` + `oauth.google_client_secret` (the
+  secret in `regstack.secrets.env` as
+  `REGSTACK_OAUTH__GOOGLE_CLIENT_SECRET`).
+- Schema: roll forward via `regstack migrate` or rely on
+  `install_schema()` at first boot.
+
+## 0.2.6 — 2026-04-28
+
+**Bug fix.**
+
+### Fixed
+
+- ``/admin/stats`` reported ``pending_registrations: 0`` on every SQL
+  backend. The route reached into the Mongo repo's private
+  ``_collection`` attribute and silently fell back to ``0`` when the
+  attribute was absent — the kind of failure that survives a
+  multi-backend refactor when the integration tests don't pin the
+  number.
+
+### Added
+
+- ``PendingRepoProtocol.count_unexpired(now=None) -> int``, with Mongo
+  and SQL implementations. "Unexpired" rather than a raw row count
+  because SQL backends accumulate dead rows until ``purge_expired``
+  runs; an admin looking at "pending: 47" wants 47 *live* rows.
+- The admin stats route now routes the count through
+  ``rs.clock.now()``. Without this, ``FrozenClock``-driven tests
+  would see every row as "expired" because the route would be reading
+  wall-clock time while the rest of the system runs on the injected
+  clock. Same shape of clock-injection drift the bulk-revoke fix
+  closed earlier.
+- New parametrized integration test
+  ``test_stats_pending_registrations_count_unexpired`` runs against
+  SQLite + Mongo + Postgres and confirms the count excludes expired
+  rows on every backend.
+
 ## 0.2.5 — 2026-04-28
 
 **Bug fix + tooling.**

{regstack-0.2.5 → regstack-0.3.0}/docs/index.md

@@ -120,6 +120,7 @@ configuration
 architecture
 security
 embedding
+oauth
 theming
 cli
 ```

regstack-0.3.0/docs/oauth.md

@@ -0,0 +1,135 @@
+# OAuth (Sign in with Google)
+
+regstack ships an opt-in OAuth subsystem. v1 supports Google; the
+abstraction is shaped so adding GitHub / Microsoft / Apple later is a
+new module under `regstack/oauth/providers/` plus one config field.
+
+This page walks a host through enabling it. The full design — including
+the threat model and the four-milestone build sequence the
+implementation followed — is in
+[`tasks/oauth-design.md`](https://github.com/jdrumgoole/regstack/blob/main/tasks/oauth-design.md).
+
+## What you get
+
+When OAuth is enabled and at least one provider is configured:
+
+- **Five JSON endpoints** under `/api/auth/oauth/`:
+  - `GET  /oauth/{provider}/start` — public; redirects to the provider.
+  - `GET  /oauth/{provider}/callback` — public; handles the redirect back.
+  - `POST /oauth/exchange` — single-use; SPA trades the state-id for a
+    session JWT.
+  - `POST /oauth/{provider}/link/start` — authenticated; returns the URL
+    to navigate the browser to.
+  - `DELETE /oauth/{provider}/link` — authenticated; unlinks one identity.
+  - `GET  /oauth/providers` — authenticated; lists configured + linked
+    providers (drives the SSR connected-accounts panel).
+- **A "Sign in with Google" button** on the bundled SSR login page.
+- **A "Connected accounts" panel** on the SSR `/account/me` page.
+- **Four hook events**: `oauth_signin_started`, `oauth_signin_completed`,
+  `oauth_account_linked`, `oauth_account_unlinked`.
+
+## Install the extra
+
+```bash
+uv add 'regstack[oauth]'
+```
+
+The `oauth` extra pulls in `pyjwt[crypto]>=2.8`, which transitively
+includes `cryptography`. ID-token signature verification needs RSA, so
+this is unavoidable.
+
+## Register a Google client
+
+In the [Google Cloud Console](https://console.cloud.google.com/apis/credentials):
+
+1. Create an **OAuth 2.0 Client ID** of type **Web application**.
+2. Add an **Authorized redirect URI** that exactly matches the URL
+   regstack will receive callbacks at — by default that's
+   `<your base_url><api_prefix>/oauth/google/callback`. For a local
+   dev server with the defaults that's
+   `http://localhost:8000/api/auth/oauth/google/callback`.
+3. Copy the **client ID** and **client secret** out — you'll set them
+   on regstack next.
+
+## Configure regstack
+
+```toml
+# regstack.toml
+enable_oauth = true
+
+[oauth]
+google_client_id = "12345.apps.googleusercontent.com"
+# google_client_secret lives in regstack.secrets.env
+# google_redirect_uri = "https://your.app/api/auth/oauth/google/callback"   # optional override
+auto_link_verified_emails = false   # security choice — see below
+```
+
+```bash
+# regstack.secrets.env
+REGSTACK_OAUTH__GOOGLE_CLIENT_SECRET=...
+```
+
+The router is mounted only when `enable_oauth=true` AND
+`google_client_id` AND `google_client_secret` are all set.
+
+## The account-linking decision
+
+When a Google sign-in arrives carrying an email that already belongs to
+a regstack user (created via password registration), regstack has to
+choose between three policies:
+
+| Policy | Behaviour |
+|---|---|
+| **Refuse** (default) | Return `?error=email_in_use` on the redirect. The user must sign in with their existing password, then link Google from `/account/me`. |
+| **Auto-link verified** | If Google's `email_verified=true`, silently link the new identity to the existing user. UX win, but trusts Google's email-verified claim *forever*. |
+| **Always create new** | Make a second account. |
+
+regstack defaults to **refuse**. To opt into auto-linking — accepting
+that an attacker who later acquires a recycled Gmail address could sign
+in as the original regstack user — set
+`oauth.auto_link_verified_emails = true`.
+
+The full threat-model writeup is in
+[`tasks/oauth-design.md`](https://github.com/jdrumgoole/regstack/blob/main/tasks/oauth-design.md).
+
+## OAuth-only users
+
+A Google sign-up creates a regstack user with `hashed_password = None`.
+Three knock-on effects, all handled:
+
+- **Login route** rejects password attempts on these accounts with the
+  same generic 401 a wrong-password attempt gets — never reveal that
+  an account exists but has no password.
+- **`change-password` / `change-email` / `delete-account`** all need
+  the current password. For OAuth-only users they return 400 with a
+  pointer at the password-reset flow, which doubles as a "set initial
+  password" path.
+- **`DELETE /oauth/{provider}/link`** refuses if it would remove the
+  user's only sign-in method (no password set, no other linked
+  provider). The error is `400 last sign-in method`.
+
+## Hooks
+
+```python
+@regstack.on("oauth_signin_completed")
+async def _track_signin(*, user, provider, mode, was_new):
+    if was_new:
+        await analytics.track("signup", {"user": user.id, "provider": provider})
+    else:
+        await analytics.track("login", {"user": user.id, "provider": provider})
+
+
+@regstack.on("oauth_account_linked")
+async def _notify_link(*, user, provider):
+    await mailer.send_link_notification(to=user.email, provider=provider)
+```
+
+The full event list is in the
+[architecture guide](architecture.md#hooks).
+
+## Disabling OAuth
+
+Flip `enable_oauth = false` (or leave the credentials unset). The
+router won't mount; the SSR login page won't render the button; the
+`/me` panel hides the section. No other configuration changes are
+required.

{regstack-0.2.5 → regstack-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "regstack"
-version = "0.2.5"
+version = "0.3.0"
 description = "Embeddable user registration, login, and account management for FastAPI apps. SQLite / Postgres / MongoDB."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -40,6 +40,7 @@ mongo = ["pymongo>=4.9"]
 ses = ["aioboto3>=12.3"]
 sns = ["aioboto3>=12.3"]
 twilio = ["twilio>=9.0"]
+oauth = ["pyjwt[crypto]>=2.8"]
 docs = [
     "sphinx>=7.3",
     "myst-parser>=3.0",
@@ -62,6 +63,8 @@ dev = [
     # All backend drivers in dev so the parametrized test suite can run.
     "pymongo>=4.9",
     "asyncpg>=0.29",
+    # OAuth provider tests need the crypto bits to verify ID tokens.
+    "pyjwt[crypto]>=2.8",
 ]
 
 [project.scripts]

regstack-0.3.0/src/regstack/__init__.py

@@ -0,0 +1,12 @@
+from regstack.app import RegStack
+from regstack.config.schema import EmailConfig, OAuthConfig, RegStackConfig, SmsConfig
+from regstack.version import __version__
+
+__all__ = [
+    "EmailConfig",
+    "OAuthConfig",
+    "RegStack",
+    "RegStackConfig",
+    "SmsConfig",
+    "__version__",
+]

{regstack-0.2.5 → regstack-0.3.0}/src/regstack/app.py

@@ -29,6 +29,7 @@ if TYPE_CHECKING:
     from jinja2 import Environment
 
     from regstack.backends.base import Backend
+    from regstack.oauth import OAuthRegistry
 
 
 class RegStack:
@@ -131,6 +132,8 @@ class RegStack:
         self.blacklist = self.backend.blacklist
         self.attempts = self.backend.attempts
         self.mfa_codes = self.backend.mfa_codes
+        self.oauth_identities = self.backend.oauth_identities
+        self.oauth_states = self.backend.oauth_states
 
         self.lockout = LockoutService(attempts=self.attempts, config=config, clock=self.clock)
         self.email: EmailService = email_service or build_email_service(config.email)
@@ -141,12 +144,38 @@ class RegStack:
         )
         self.hooks = HookRegistry()
         self.deps = AuthDependencies(jwt=self.jwt, users=self.users, blacklist=self.blacklist)
+        self.oauth = self._build_oauth_registry()
         self._template_dirs: list[Path] = list(config.extra_template_dirs)
         self._ui_env: Environment | None = None
         self._router: APIRouter | None = None
         self._ui_router: APIRouter | None = None
         self._static_files: StaticFiles | None = None
 
+    def _build_oauth_registry(self) -> OAuthRegistry:
+        """Build the OAuth registry, populated from config.
+
+        The ``regstack.oauth`` import is lazy so the package keeps
+        importing on a base install (no ``oauth`` extra). When
+        ``enable_oauth`` is off the registry is empty; the router won't
+        be mounted regardless.
+        """
+        from regstack.oauth import OAuthRegistry
+
+        registry = OAuthRegistry()
+        if not self.config.enable_oauth:
+            return registry
+        oauth_cfg = self.config.oauth
+        if oauth_cfg.google_client_id and oauth_cfg.google_client_secret:
+            from regstack.oauth.providers.google import GoogleProvider
+
+            registry.register(
+                GoogleProvider(
+                    client_id=oauth_cfg.google_client_id,
+                    client_secret=oauth_cfg.google_client_secret.get_secret_value(),
+                )
+            )
+        return registry
+
     @property
     def router(self) -> APIRouter:
         """The composite JSON ``APIRouter``.

{regstack-0.2.5 → regstack-0.3.0}/src/regstack/backends/base.py

@@ -20,6 +20,8 @@ if TYPE_CHECKING:
         BlacklistRepoProtocol,
         LoginAttemptRepoProtocol,
         MfaCodeRepoProtocol,
+        OAuthIdentityRepoProtocol,
+        OAuthStateRepoProtocol,
         PendingRepoProtocol,
         UserRepoProtocol,
     )
@@ -51,6 +53,8 @@ class Backend(ABC):
     blacklist: BlacklistRepoProtocol
     attempts: LoginAttemptRepoProtocol
     mfa_codes: MfaCodeRepoProtocol
+    oauth_identities: OAuthIdentityRepoProtocol
+    oauth_states: OAuthStateRepoProtocol
 
     # --- Lifecycle -------------------------------------------------------
 

{regstack-0.2.5 → regstack-0.3.0}/src/regstack/backends/mongo/backend.py

@@ -8,6 +8,10 @@ from regstack.backends.mongo.indexes import install_indexes
 from regstack.backends.mongo.repositories.blacklist_repo import BlacklistRepo
 from regstack.backends.mongo.repositories.login_attempt_repo import LoginAttemptRepo
 from regstack.backends.mongo.repositories.mfa_code_repo import MfaCodeRepo
+from regstack.backends.mongo.repositories.oauth_identity_repo import (
+    MongoOAuthIdentityRepo,
+)
+from regstack.backends.mongo.repositories.oauth_state_repo import MongoOAuthStateRepo
 from regstack.backends.mongo.repositories.pending_repo import PendingRepo
 from regstack.backends.mongo.repositories.user_repo import UserRepo
 
@@ -36,6 +40,8 @@ class MongoBackend(Backend):
         self.blacklist = BlacklistRepo(self._db, config.blacklist_collection)
         self.attempts = LoginAttemptRepo(self._db, config.login_attempt_collection)
         self.mfa_codes = MfaCodeRepo(self._db, config.mfa_code_collection, clock=clock)
+        self.oauth_identities = MongoOAuthIdentityRepo(self._db, config.oauth_identity_collection)
+        self.oauth_states = MongoOAuthStateRepo(self._db, config.oauth_state_collection)
 
     async def install_schema(self) -> None:
         await install_indexes(self._db, self.config)

{regstack-0.2.5 → regstack-0.3.0}/src/regstack/backends/mongo/indexes.py

@@ -67,4 +67,31 @@ async def install_indexes(db: AsyncDatabase, config: RegStackConfig) -> None:
         ]
     )
 
+    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",
+            ),
+        ]
+    )
+
     log.info("regstack indexes installed on database %s", db.name)

{regstack-0.2.5 → regstack-0.3.0}/src/regstack/backends/mongo/repositories/__init__.py

@@ -1,6 +1,10 @@
 from regstack.backends.mongo.repositories.blacklist_repo import BlacklistRepo
 from regstack.backends.mongo.repositories.login_attempt_repo import LoginAttemptRepo
 from regstack.backends.mongo.repositories.mfa_code_repo import MfaCodeRepo
+from regstack.backends.mongo.repositories.oauth_identity_repo import (
+    MongoOAuthIdentityRepo,
+)
+from regstack.backends.mongo.repositories.oauth_state_repo import MongoOAuthStateRepo
 from regstack.backends.mongo.repositories.pending_repo import PendingRepo
 from regstack.backends.mongo.repositories.user_repo import UserRepo
 
@@ -8,6 +12,8 @@ __all__ = [
     "BlacklistRepo",
     "LoginAttemptRepo",
     "MfaCodeRepo",
+    "MongoOAuthIdentityRepo",
+    "MongoOAuthStateRepo",
     "PendingRepo",
     "UserRepo",
 ]

regstack-0.3.0/src/regstack/backends/mongo/repositories/oauth_identity_repo.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from bson import ObjectId
+from pymongo.errors import DuplicateKeyError
+
+from regstack.backends.protocols import OAuthIdentityAlreadyLinkedError
+from regstack.models.oauth_identity import OAuthIdentity
+
+if TYPE_CHECKING:
+    from pymongo.asynchronous.database import AsyncDatabase
+
+
+class MongoOAuthIdentityRepo:
+    def __init__(self, db: AsyncDatabase, collection_name: str) -> None:
+        self._collection = db[collection_name]
+
+    async def create(self, identity: OAuthIdentity) -> OAuthIdentity:
+        try:
+            result = await self._collection.insert_one(identity.to_mongo())
+        except DuplicateKeyError as exc:
+            raise OAuthIdentityAlreadyLinkedError(
+                f"{identity.provider}/{identity.subject_id}"
+            ) from exc
+        identity.id = str(result.inserted_id)
+        return identity
+
+    async def find_by_subject(self, *, provider: str, subject_id: str) -> OAuthIdentity | None:
+        doc = await self._collection.find_one({"provider": provider, "subject_id": subject_id})
+        return self._hydrate(doc)
+
+    async def list_for_user(self, user_id: str) -> list[OAuthIdentity]:
+        cursor = self._collection.find({"user_id": user_id}).sort("linked_at", 1)
+        out: list[OAuthIdentity] = []
+        async for doc in cursor:
+            identity = self._hydrate(doc)
+            if identity is not None:
+                out.append(identity)
+        return out
+
+    async def delete(self, *, user_id: str, provider: str) -> bool:
+        result = await self._collection.delete_one({"user_id": user_id, "provider": provider})
+        return bool(result.deleted_count)
+
+    async def delete_by_user_id(self, user_id: str) -> int:
+        result = await self._collection.delete_many({"user_id": user_id})
+        return int(result.deleted_count)
+
+    async def touch_last_used(self, *, provider: str, subject_id: str, when: datetime) -> None:
+        await self._collection.update_one(
+            {"provider": provider, "subject_id": subject_id},
+            {"$set": {"last_used_at": when}},
+        )
+
+    @staticmethod
+    def _hydrate(doc: dict[str, Any] | None) -> OAuthIdentity | None:
+        if doc is None:
+            return None
+        if isinstance(doc.get("_id"), ObjectId):
+            doc["_id"] = str(doc["_id"])
+        return OAuthIdentity.model_validate(doc)

regstack-0.3.0/src/regstack/backends/mongo/repositories/oauth_state_repo.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from regstack.models.oauth_state import OAuthState
+
+if TYPE_CHECKING:
+    from pymongo.asynchronous.database import AsyncDatabase
+
+
+class MongoOAuthStateRepo:
+    def __init__(self, db: AsyncDatabase, collection_name: str) -> None:
+        self._collection = db[collection_name]
+
+    async def create(self, state: OAuthState) -> None:
+        # We use the caller-supplied id as _id directly so consume() can
+        # delete by primary key without needing a separate index.
+        doc = state.to_mongo()
+        await self._collection.insert_one(doc)
+
+    async def find(self, state_id: str) -> OAuthState | None:
+        doc = await self._collection.find_one({"_id": state_id})
+        return self._hydrate(doc)
+
+    async def set_result_token(self, state_id: str, token: str) -> None:
+        await self._collection.update_one(
+            {"_id": state_id},
+            {"$set": {"result_token": token}},
+        )
+
+    async def consume(self, state_id: str) -> OAuthState | None:
+        doc = await self._collection.find_one_and_delete({"_id": state_id})
+        return self._hydrate(doc)
+
+    async def purge_expired(self, now: datetime | None = None) -> int:
+        cutoff = now or datetime.now(UTC)
+        result = await self._collection.delete_many({"expires_at": {"$lt": cutoff}})
+        return int(result.deleted_count)
+
+    @staticmethod
+    def _hydrate(doc: dict[str, Any] | None) -> OAuthState | None:
+        if doc is None:
+            return None
+        return OAuthState.model_validate(doc)

{regstack-0.2.5 → regstack-0.3.0}/src/regstack/backends/mongo/repositories/pending_repo.py

@@ -64,6 +64,10 @@ class PendingRepo:
         result = await self._collection.delete_many({"expires_at": {"$lt": cutoff}})
         return int(result.deleted_count)
 
+    async def count_unexpired(self, now: datetime | None = None) -> int:
+        cutoff = now or datetime.now(UTC)
+        return await self._collection.count_documents({"expires_at": {"$gt": cutoff}})
+
     @staticmethod
     def _hydrate(doc: dict[str, Any] | None) -> PendingRegistration | None:
         if doc is None: