regstack 0.1.0__py3-none-any.whl

regstack/config/schema.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Literal
+
+from pydantic import AnyHttpUrl, BaseModel, EmailStr, Field, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+EmailBackend = Literal["console", "smtp", "ses"]
+SmsBackend = Literal["null", "sns", "twilio"]
+JwtAlgorithm = Literal["HS256", "HS384", "HS512"]
+TokenTransport = Literal["bearer", "cookie"]
+
+
+class EmailConfig(BaseModel):
+    backend: EmailBackend = "console"
+    from_address: EmailStr = "noreply@example.com"
+    from_name: str = "RegStack"
+
+    smtp_host: str | None = None
+    smtp_port: int = 587
+    smtp_starttls: bool = True
+    smtp_username: str | None = None
+    smtp_password: SecretStr | None = None
+
+    ses_region: str = "eu-west-1"
+    ses_profile: str | None = None
+
+
+class SmsConfig(BaseModel):
+    backend: SmsBackend = "null"
+    from_number: str | None = None
+
+    sns_region: str = "eu-west-1"
+
+    twilio_account_sid: str | None = None
+    twilio_auth_token: SecretStr | None = None
+
+
+class RegStackConfig(BaseSettings):
+    """Top-level configuration for an embedded regstack instance.
+
+    Loading order (highest priority first):
+        1. Programmatic kwargs.
+        2. Environment variables (``REGSTACK_*``, nested via ``__``).
+        3. TOML file at ``$REGSTACK_CONFIG`` or ``./regstack.toml``.
+        4. Field defaults defined here.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="REGSTACK_",
+        env_nested_delimiter="__",
+        extra="ignore",
+        populate_by_name=True,
+    )
+
+    # Identity / hosting
+    app_name: str = "RegStack"
+    base_url: AnyHttpUrl = AnyHttpUrl("http://localhost:8000")
+    cookie_domain: str | None = None
+    behind_proxy: bool = False
+
+    # Database
+    mongodb_url: SecretStr = SecretStr("mongodb://localhost:27017")
+    mongodb_database: str = "regstack"
+    user_collection: str = "users"
+    pending_collection: str = "pending_registrations"
+    blacklist_collection: str = "token_blacklist"
+    login_attempt_collection: str = "login_attempts"
+    mfa_code_collection: str = "mfa_codes"
+
+    # JWT
+    jwt_secret: SecretStr = Field(default_factory=lambda: SecretStr(""))
+    jwt_algorithm: JwtAlgorithm = "HS256"
+    jwt_ttl_seconds: Annotated[int, Field(ge=60, le=60 * 60 * 24 * 30)] = 7200
+    jwt_audience: str | None = None
+    transport: TokenTransport = "bearer"
+
+    # Verification & password-reset & email-change token lifetimes
+    verification_token_ttl_seconds: Annotated[int, Field(ge=60)] = 60 * 60 * 24
+    password_reset_token_ttl_seconds: Annotated[int, Field(ge=60)] = 60 * 30
+    email_change_token_ttl_seconds: Annotated[int, Field(ge=60)] = 60 * 60
+
+    # SMS / 2FA
+    sms_code_length: Annotated[int, Field(ge=4, le=10)] = 6
+    sms_code_ttl_seconds: Annotated[int, Field(ge=30, le=60 * 30)] = 300
+    sms_code_max_attempts: Annotated[int, Field(ge=1, le=20)] = 5
+    mfa_pending_token_ttl_seconds: Annotated[int, Field(ge=60, le=60 * 30)] = 600
+
+    # Feature flags
+    require_verification: bool = True
+    allow_registration: bool = True
+    enable_password_reset: bool = True
+    enable_account_deletion: bool = True
+    enable_admin_router: bool = False
+    enable_ui_router: bool = False
+    enable_sms_2fa: bool = False
+    enable_oauth: bool = False  # reserved; no providers ship in v1
+
+    # Login lockout (M2: count failed attempts per email in a sliding window)
+    rate_limit_disabled: bool = False
+    login_lockout_threshold: Annotated[int, Field(ge=1)] = 5
+    login_lockout_window_seconds: Annotated[int, Field(ge=10)] = 900
+
+    # Reserved for future route-level rate limiting (slowapi-style).
+    login_max_per_minute: Annotated[int, Field(ge=1)] = 5
+    login_max_per_hour: Annotated[int, Field(ge=1)] = 20
+
+    # Sub-configs
+    email: EmailConfig = Field(default_factory=EmailConfig)
+    sms: SmsConfig = Field(default_factory=SmsConfig)
+
+    # Branding / theming
+    brand_logo_url: str | None = None
+    brand_tagline: str | None = None
+    extra_template_dirs: list[Path] = Field(default_factory=list)
+    extra_static_dirs: list[Path] = Field(default_factory=list)
+
+    # SSR ui_router URLs
+    api_prefix: str = "/api/auth"
+    ui_prefix: str = "/account"
+    static_prefix: str = "/regstack-static"
+    theme_css_url: str | None = None  # if set, loaded AFTER bundled defaults
+
+    @field_validator("jwt_secret")
+    @classmethod
+    def _warn_empty_secret(cls, v: SecretStr) -> SecretStr:
+        # An empty secret is allowed at construction time so defaults remain
+        # usable in tests; production callers should populate it explicitly
+        # or via the wizard. Validation that *requires* it lives at the
+        # RegStack façade boundary so test fixtures can opt out.
+        return v
+
+    @classmethod
+    def load(
+        cls,
+        toml_path: Path | str | None = None,
+        secrets_env_path: Path | str | None = None,
+        **overrides: object,
+    ) -> RegStackConfig:
+        """Convenience constructor delegating to ``regstack.config.loader.load_config``."""
+        from regstack.config.loader import load_config
+
+        return load_config(
+            toml_path=toml_path,
+            secrets_env_path=secrets_env_path,
+            **overrides,
+        )

regstack/config/secrets.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+
+
+def derive_secret(master: str | bytes, purpose: str) -> bytes:
+    """Derive a purpose-specific secret from the master JWT secret.
+
+    Uses HMAC-SHA256 so every subsystem (verification tokens, password reset
+    tokens, refresh tokens, etc.) signs with a different key. Compromising one
+    derived key does not compromise the master.
+    """
+    if isinstance(master, str):
+        master = master.encode("utf-8")
+    return hmac.new(master, purpose.encode("utf-8"), hashlib.sha256).digest()
+
+
+def generate_secret(num_bytes: int = 64) -> str:
+    """Return a URL-safe random secret suitable for the JWT master key."""
+    return secrets.token_urlsafe(num_bytes)

regstack/db/__init__.py

@@ -0,0 +1,17 @@
+from regstack.db.indexes import install_indexes
+from regstack.db.repositories.blacklist_repo import BlacklistRepo
+from regstack.db.repositories.login_attempt_repo import LoginAttemptRepo
+from regstack.db.repositories.mfa_code_repo import MfaCodeRepo, MfaVerifyOutcome, MfaVerifyResult
+from regstack.db.repositories.pending_repo import PendingRepo
+from regstack.db.repositories.user_repo import UserRepo
+
+__all__ = [
+    "BlacklistRepo",
+    "LoginAttemptRepo",
+    "MfaCodeRepo",
+    "MfaVerifyOutcome",
+    "MfaVerifyResult",
+    "PendingRepo",
+    "UserRepo",
+    "install_indexes",
+]

regstack/db/client.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pymongo import AsyncMongoClient
+
+if TYPE_CHECKING:
+    from pymongo.asynchronous.database import AsyncDatabase
+
+    from regstack.config.schema import RegStackConfig
+
+
+def make_client(config: RegStackConfig) -> AsyncMongoClient:
+    """Build an AsyncMongoClient with the settings regstack expects.
+
+    ``tz_aware=True`` makes BSON datetimes round-trip as UTC-aware values; the
+    JWT and bulk-revocation comparisons assume aware datetimes throughout.
+    """
+    return AsyncMongoClient(
+        config.mongodb_url.get_secret_value(),
+        tz_aware=True,
+    )
+
+
+def get_database(client: AsyncMongoClient, config: RegStackConfig) -> AsyncDatabase:
+    return client[config.mongodb_database]

regstack/db/indexes.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from pymongo import ASCENDING, IndexModel
+
+if TYPE_CHECKING:
+    from pymongo.asynchronous.database import AsyncDatabase
+
+    from regstack.config.schema import RegStackConfig
+
+log = logging.getLogger(__name__)
+
+
+async def install_indexes(db: AsyncDatabase, config: RegStackConfig) -> None:
+    """Create the indexes regstack relies on. Safe to call repeatedly."""
+    users = db[config.user_collection]
+    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"),
+        ]
+    )
+
+    log.info("regstack indexes installed on database %s", db.name)

regstack/db/repositories/blacklist_repo.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import contextlib
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from pymongo.errors import DuplicateKeyError
+
+if TYPE_CHECKING:
+    from pymongo.asynchronous.database import AsyncDatabase
+
+
+class BlacklistRepo:
+    """Per-token revocation store. The `exp` field has a TTL index that
+    auto-reaps documents once the underlying token would have expired anyway.
+    """
+
+    def __init__(self, db: AsyncDatabase, collection_name: str) -> None:
+        self._collection = db[collection_name]
+
+    async def revoke(self, jti: str, exp: datetime) -> None:
+        # Idempotent — re-revoking the same jti is a no-op.
+        with contextlib.suppress(DuplicateKeyError):
+            await self._collection.insert_one({"jti": jti, "exp": exp})
+
+    async def is_revoked(self, jti: str) -> bool:
+        doc = await self._collection.find_one({"jti": jti}, projection={"_id": 1})
+        return doc is not None

regstack/db/repositories/login_attempt_repo.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+
+from regstack.models.login_attempt import LoginAttempt
+
+if TYPE_CHECKING:
+    from pymongo.asynchronous.database import AsyncDatabase
+
+
+class LoginAttemptRepo:
+    def __init__(self, db: AsyncDatabase, collection_name: str) -> None:
+        self._collection = db[collection_name]
+
+    async def record_failure(
+        self, email: str, *, when: datetime | None = None, ip: str | None = None
+    ) -> None:
+        attempt = LoginAttempt(email=email, when=when or datetime.now(UTC), ip=ip)
+        await self._collection.insert_one(attempt.to_mongo())
+
+    async def count_recent(self, email: str, *, window: timedelta, now: datetime) -> int:
+        cutoff = now - window
+        return await self._collection.count_documents({"email": email, "when": {"$gte": cutoff}})
+
+    async def clear(self, email: str) -> None:
+        await self._collection.delete_many({"email": email})

regstack/db/repositories/mfa_code_repo.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from regstack.auth.tokens import hash_token
+from regstack.models.mfa_code import MfaCode, MfaKind
+
+if TYPE_CHECKING:
+    from pymongo.asynchronous.database import AsyncDatabase
+
+    from regstack.auth.clock import Clock
+
+
+class MfaVerifyOutcome(StrEnum):
+    OK = "ok"
+    WRONG = "wrong"
+    EXPIRED = "expired"
+    LOCKED = "locked"
+    MISSING = "missing"
+
+
+@dataclass(slots=True, frozen=True)
+class MfaVerifyResult:
+    outcome: MfaVerifyOutcome
+    attempts_remaining: int = 0
+
+
+class MfaCodeRepo:
+    def __init__(self, db: AsyncDatabase, collection_name: str, *, clock: Clock) -> None:
+        self._collection = db[collection_name]
+        self._clock = clock
+
+    async def put(self, code: MfaCode) -> None:
+        """Upsert by ``(user_id, kind)`` — re-issuing a code overwrites
+        any previous outstanding code, so old SMS messages stop working
+        as soon as a new one is sent.
+        """
+        doc = code.to_mongo()
+        await self._collection.find_one_and_replace(
+            {"user_id": code.user_id, "kind": code.kind},
+            doc,
+            upsert=True,
+        )
+
+    async def verify(
+        self,
+        *,
+        user_id: str,
+        kind: MfaKind,
+        raw_code: str,
+    ) -> MfaVerifyResult:
+        doc = await self._collection.find_one({"user_id": user_id, "kind": kind})
+        if doc is None:
+            return MfaVerifyResult(MfaVerifyOutcome.MISSING)
+        attempts = int(doc.get("attempts", 0))
+        max_attempts = int(doc.get("max_attempts", 5))
+        if attempts >= max_attempts:
+            await self._collection.delete_one({"_id": doc["_id"]})
+            return MfaVerifyResult(MfaVerifyOutcome.LOCKED)
+
+        if doc["expires_at"] <= self._clock.now():
+            await self._collection.delete_one({"_id": doc["_id"]})
+            return MfaVerifyResult(MfaVerifyOutcome.EXPIRED)
+
+        if doc["code_hash"] != hash_token(raw_code):
+            new_attempts = attempts + 1
+            await self._collection.update_one(
+                {"_id": doc["_id"]}, {"$set": {"attempts": new_attempts}}
+            )
+            remaining = max(max_attempts - new_attempts, 0)
+            if remaining == 0:
+                await self._collection.delete_one({"_id": doc["_id"]})
+                return MfaVerifyResult(MfaVerifyOutcome.LOCKED)
+            return MfaVerifyResult(MfaVerifyOutcome.WRONG, attempts_remaining=remaining)
+
+        await self._collection.delete_one({"_id": doc["_id"]})
+        return MfaVerifyResult(MfaVerifyOutcome.OK)
+
+    async def delete(self, *, user_id: str, kind: MfaKind | None = None) -> None:
+        query: dict[str, object] = {"user_id": user_id}
+        if kind is not None:
+            query["kind"] = kind
+        await self._collection.delete_many(query)
+
+    async def find(self, *, user_id: str, kind: MfaKind) -> dict[str, object] | None:
+        return await self._collection.find_one({"user_id": user_id, "kind": kind})
+
+    @staticmethod
+    def make_code_hash(raw_code: str) -> str:
+        return hash_token(raw_code)
+
+
+def now_plus_seconds(clock: Clock, seconds: int) -> datetime:
+    from datetime import timedelta
+
+    return clock.now() + timedelta(seconds=seconds)

regstack/db/repositories/pending_repo.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from bson import ObjectId
+from pymongo.errors import DuplicateKeyError
+
+from regstack.models.pending_registration import PendingRegistration
+
+if TYPE_CHECKING:
+    from pymongo.asynchronous.database import AsyncDatabase
+
+
+class PendingAlreadyExistsError(Exception):
+    """A pending registration with this email already exists."""
+
+
+class PendingRepo:
+    def __init__(self, db: AsyncDatabase, collection_name: str) -> None:
+        self._collection = db[collection_name]
+
+    async def upsert(self, pending: PendingRegistration) -> PendingRegistration:
+        """Insert or replace the pending registration for this email.
+
+        Resends overwrite an outstanding row so the most recent token is the
+        only valid one — old links stop working as soon as a new one is sent.
+        """
+        doc = pending.to_mongo()
+        result = await self._collection.find_one_and_replace(
+            {"email": pending.email},
+            doc,
+            upsert=True,
+            return_document=True,
+        )
+        if result is not None and "_id" in result:
+            pending.id = str(result["_id"])
+        return pending
+
+    async def create(self, pending: PendingRegistration) -> PendingRegistration:
+        try:
+            result = await self._collection.insert_one(pending.to_mongo())
+        except DuplicateKeyError as exc:
+            raise PendingAlreadyExistsError(pending.email) from exc
+        pending.id = str(result.inserted_id)
+        return pending
+
+    async def find_by_token_hash(self, token_hash: str) -> PendingRegistration | None:
+        doc = await self._collection.find_one({"token_hash": token_hash})
+        return self._hydrate(doc)
+
+    async def find_by_email(self, email: str) -> PendingRegistration | None:
+        doc = await self._collection.find_one({"email": email})
+        return self._hydrate(doc)
+
+    async def delete_by_id(self, pending_id: str) -> None:
+        if not ObjectId.is_valid(pending_id):
+            return
+        await self._collection.delete_one({"_id": ObjectId(pending_id)})
+
+    async def delete_by_email(self, email: str) -> None:
+        await self._collection.delete_one({"email": email})
+
+    async def purge_expired(self, now: datetime | None = None) -> int:
+        """Manual reaper for callers that don't trust the TTL background sweep."""
+        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) -> PendingRegistration | None:
+        if doc is None:
+            return None
+        if isinstance(doc.get("_id"), ObjectId):
+            doc["_id"] = str(doc["_id"])
+        return PendingRegistration.model_validate(doc)

regstack/db/repositories/user_repo.py

@@ -0,0 +1,169 @@
+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.auth.clock import Clock, SystemClock
+from regstack.models.user import BaseUser
+
+if TYPE_CHECKING:
+    from pymongo.asynchronous.database import AsyncDatabase
+
+
+class UserAlreadyExistsError(Exception):
+    """Raised when an attempt is made to insert a user with a duplicate email."""
+
+
+def _bulk_revoke_cutoff(now: datetime) -> datetime:
+    """The cutoff timestamp recorded on the user document. Stored at full
+    microsecond precision; the JWT ``iat`` claim is also emitted as a float
+    so the ``iat < cutoff`` comparison is exact and a fresh login completing
+    even microseconds after a password / email change is recognised as
+    later-than-cutoff.
+    """
+    return now
+
+
+class UserRepo:
+    def __init__(
+        self,
+        db: AsyncDatabase,
+        collection_name: str,
+        *,
+        clock: Clock | None = None,
+    ) -> None:
+        self._collection = db[collection_name]
+        self._clock: Clock = clock or SystemClock()
+
+    async def create(self, user: BaseUser) -> BaseUser:
+        doc = user.to_mongo()
+        try:
+            result = await self._collection.insert_one(doc)
+        except DuplicateKeyError as exc:
+            raise UserAlreadyExistsError(user.email) from exc
+        user.id = str(result.inserted_id)
+        return user
+
+    async def get_by_email(self, email: str) -> BaseUser | None:
+        doc = await self._collection.find_one({"email": email})
+        return self._hydrate(doc)
+
+    async def get_by_id(self, user_id: str) -> BaseUser | None:
+        if not ObjectId.is_valid(user_id):
+            return None
+        doc = await self._collection.find_one({"_id": ObjectId(user_id)})
+        return self._hydrate(doc)
+
+    async def set_last_login(self, user_id: str, when: datetime) -> None:
+        await self._collection.update_one(
+            {"_id": ObjectId(user_id)},
+            {"$set": {"last_login": when, "updated_at": self._clock.now()}},
+        )
+
+    async def set_tokens_invalidated_after(self, user_id: str, when: datetime) -> None:
+        await self._collection.update_one(
+            {"_id": ObjectId(user_id)},
+            {
+                "$set": {
+                    "tokens_invalidated_after": _bulk_revoke_cutoff(when),
+                    "updated_at": self._clock.now(),
+                }
+            },
+        )
+
+    async def update_password(self, user_id: str, hashed_password: str) -> None:
+        now = self._clock.now()
+        await self._collection.update_one(
+            {"_id": ObjectId(user_id)},
+            {
+                "$set": {
+                    "hashed_password": hashed_password,
+                    "tokens_invalidated_after": _bulk_revoke_cutoff(now),
+                    "updated_at": now,
+                }
+            },
+        )
+
+    async def set_active(self, user_id: str, *, is_active: bool) -> None:
+        await self._collection.update_one(
+            {"_id": ObjectId(user_id)},
+            {"$set": {"is_active": is_active, "updated_at": self._clock.now()}},
+        )
+
+    async def set_superuser(self, user_id: str, *, is_superuser: bool) -> None:
+        await self._collection.update_one(
+            {"_id": ObjectId(user_id)},
+            {"$set": {"is_superuser": is_superuser, "updated_at": self._clock.now()}},
+        )
+
+    async def set_full_name(self, user_id: str, full_name: str | None) -> None:
+        await self._collection.update_one(
+            {"_id": ObjectId(user_id)},
+            {"$set": {"full_name": full_name, "updated_at": self._clock.now()}},
+        )
+
+    async def set_phone(self, user_id: str, phone_number: str | None) -> None:
+        await self._collection.update_one(
+            {"_id": ObjectId(user_id)},
+            {"$set": {"phone_number": phone_number, "updated_at": self._clock.now()}},
+        )
+
+    async def set_mfa_enabled(self, user_id: str, *, is_mfa_enabled: bool) -> None:
+        await self._collection.update_one(
+            {"_id": ObjectId(user_id)},
+            {"$set": {"is_mfa_enabled": is_mfa_enabled, "updated_at": self._clock.now()}},
+        )
+
+    async def update_email(self, user_id: str, new_email: str) -> None:
+        """Atomically swap the user's email. Bumps tokens_invalidated_after so
+        any session bound to the old email becomes useless.
+        """
+        now = self._clock.now()
+        try:
+            await self._collection.update_one(
+                {"_id": ObjectId(user_id)},
+                {
+                    "$set": {
+                        "email": new_email,
+                        "tokens_invalidated_after": _bulk_revoke_cutoff(now),
+                        "updated_at": now,
+                    }
+                },
+            )
+        except DuplicateKeyError as exc:
+            raise UserAlreadyExistsError(new_email) from exc
+
+    async def delete(self, user_id: str) -> bool:
+        if not ObjectId.is_valid(user_id):
+            return False
+        result = await self._collection.delete_one({"_id": ObjectId(user_id)})
+        return bool(result.deleted_count)
+
+    async def count(self, *, filter_: dict[str, Any] | None = None) -> int:
+        return await self._collection.count_documents(filter_ or {})
+
+    async def list_paged(
+        self,
+        *,
+        skip: int = 0,
+        limit: int = 50,
+        sort: tuple[str, int] = ("created_at", -1),
+    ) -> list[BaseUser]:
+        cursor = self._collection.find().sort([sort]).skip(skip).limit(limit)
+        out: list[BaseUser] = []
+        async for doc in cursor:
+            user = self._hydrate(doc)
+            if user is not None:
+                out.append(user)
+        return out
+
+    @staticmethod
+    def _hydrate(doc: dict[str, Any] | None) -> BaseUser | None:
+        if doc is None:
+            return None
+        if isinstance(doc.get("_id"), ObjectId):
+            doc["_id"] = str(doc["_id"])
+        return BaseUser.model_validate(doc)