Add model-driven identity contract (configurable login/recovery, email-optional accounts)

Author: igorbenav

crudauth/__init__.py

@@ -39,6 +39,8 @@ async def me(user: Principal = Depends(auth.current_user())):
 )
 from .crud_auth import CRUDAuth
 from .hooks import AuthHooks, HookContext
+from .identity import IdentityConfig
+from .models.mixin import AuthUserMixin, make_auth_identity
 from .oauth import OAuthCredentials
 from .principal import Principal
 from .provisioning import NewUserContext, NewUserFields
@@ -62,6 +64,9 @@ async def me(user: Principal = Depends(auth.current_user())):
     "EmailChannel",
     "AuthHooks",
     "HookContext",
+    "IdentityConfig",
+    "AuthUserMixin",
+    "make_auth_identity",
     "NewUserContext",
     "NewUserFields",
     "Transport",

crudauth/crud_auth.py

@@ -39,6 +39,7 @@ async def me(user: Principal = Depends(auth.current_user())):
     UnauthorizedException,
 )
 from .hooks import AuthHooks
+from .identity import IdentityConfig
 from .oauth import OAuthAccountService, OAuthProviderFactory
 from .oauth.router import build_oauth_router
 from .principal import Principal
@@ -99,6 +100,7 @@ def __init__(
         SECRET_KEY: str,
         transports: Sequence[Transport] | None = None,
         column_map: dict[str, str] | None = None,
+        identity: IdentityConfig | None = None,
         oauth: dict[str, Any] | None = None,
         email: Any = None,
         channels: list[DeliveryChannel] | None = None,
@@ -201,7 +203,11 @@ def __init__(
         if not SECRET_KEY:
             raise ValueError("SECRET_KEY is required")
         self.session = session
-        self.repo = UserRepository(user_model, column_map, register_extra_fields)
+        self.identity = identity or IdentityConfig()
+        self.repo = UserRepository(
+            user_model, column_map, register_extra_fields, login_fields=self.identity.login
+        )
+        self._validate_identity(oauth=oauth, email=email)
         self.new_user_fields = new_user_fields
         self._new_user_defaults = self.repo.filter_provisioning_data(new_user_defaults or {})
         self.hooks = hooks or AuthHooks()
@@ -235,7 +241,7 @@ def __init__(
 
         self._email_service: EmailFlowService | None = None
         self._email_token_store: AbstractSessionStorage[Any] | None = None
-        if email is not None or channels:
+        if self.identity.recovery is not None and (email is not None or channels):
             self._build_email(email, channels, algorithm)
 
         self._oauth_router: APIRouter | None = None
@@ -276,6 +282,34 @@ def _build_lockout(
             fail_open=False,
         )
 
+    def _validate_identity(self, *, oauth: dict[str, Any] | None, email: Any) -> None:
+        """Check the identity contract against the model, fail-closed at construction.
+
+        The model owns the shape; this asserts the config agrees with it, so a
+        login field that isn't a unique column, a non-unique recovery field, OAuth
+        without an email login, or an email flow on a model with no email column
+        all raise here rather than splitting into a silent second source of truth.
+        """
+        for login_field in self.identity.login:
+            if not self.repo.is_unique_column(login_field):
+                raise ValueError(
+                    f"identity.login field '{login_field}' is not a unique column on the user "
+                    "model; every login field must be a single-field unique column."
+                )
+        recovery = self.identity.recovery
+        if recovery is not None and not self.repo.is_unique_column(recovery):
+            raise ValueError(
+                f"identity.recovery field '{recovery}' is not a unique column on the user "
+                "model; the recovery field must be a single-field unique column."
+            )
+        if oauth and "email" not in self.identity.login:
+            raise ValueError(
+                "OAuth requires 'email' in identity.login - OAuth links and creates accounts "
+                "by email, so an email-less contract cannot enable OAuth."
+            )
+        if email is not None and not self.repo.has("email"):
+            raise ValueError("email=EmailConfig(...) requires an 'email' column on the user model.")
+
     def _warn_on_register_extra_fields(self, extra: set[str] | None) -> None:
         """Warn when ``register_extra_fields`` tries to opt in a privileged field.
 
@@ -518,6 +552,11 @@ async def admin(_: Principal = Depends(auth.current_user(superuser=True))):
                 ...
             ```
         """
+        if verified and not self.repo.has("email"):
+            raise ValueError(
+                "current_user(verified=True) gates on email_verified, which requires an "
+                "email column on the user model. (PR-1 placeholder; recovery_verified is PR 2.)"
+            )
         selected = self._select_transports(transport)
         required_scopes = list(scopes or [])
 

crudauth/identity.py

@@ -0,0 +1,40 @@
+"""The identity contract: the login/recovery intent the model's columns can't carry.
+
+The model owns the *shape* (which columns exist, nullable, unique);
+[IdentityConfig][crudauth.identity.IdentityConfig] owns the *intent* a schema
+can't express, and [CRUDAuth][crudauth.crud_auth.CRUDAuth] validates the two
+against each other at construction, so a config that contradicts the model fails
+loudly at startup instead of splitting into a silent second source of truth.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+__all__ = ["IdentityConfig"]
+
+
+@dataclass(frozen=True)
+class IdentityConfig:
+    """How an account's identity behaves, validated against the model at construction.
+
+    Attributes:
+        login: Logical fields a login identifier is matched against, in order;
+            first match wins. Each must be a unique column on the model (asserted
+            at construction, which is what makes first-match-wins safe).
+        recovery: The single field verify/reset/change is delivered against, or
+            ``None`` to disable recovery (the recovery endpoints aren't mounted).
+            Must be a unique column when set.
+
+    Example:
+        ```python
+        # username login, phone recovery
+        CRUDAuth(..., identity=IdentityConfig(login=["username"], recovery="phone"))
+
+        # anonymous: username login, no recovery at all
+        CRUDAuth(..., identity=IdentityConfig(login=["username"], recovery=None))
+        ```
+    """
+
+    login: list[str] = field(default_factory=lambda: ["email", "username"])
+    recovery: str | None = "email"

crudauth/models/mixin.py

@@ -1,63 +1,144 @@
-"""The [AuthUserMixin][crudauth.models.mixin.AuthUserMixin] - inherit it and get every column crudauth needs.
-
-Your own columns coexist freely. If you have an existing table with different
-column names, don't rename your schema - map the contract via
-``column_map=`` on [CRUDAuth][crudauth.crud_auth.CRUDAuth] instead.
+"""The auth user-model columns, emitted by [make_auth_identity]
+[crudauth.models.mixin.make_auth_identity].
+
+Inherit [AuthUserMixin][crudauth.models.mixin.AuthUserMixin] (the default output)
+and get every column crudauth needs. Your own columns coexist freely. For a
+different account shape (username-only login, phone recovery, no recovery at all)
+call the factory yourself. If you have an existing table with different column
+names, don't rename your schema - map the contract via ``column_map=`` on
+[CRUDAuth][crudauth.crud_auth.CRUDAuth] instead.
 """
 
 from __future__ import annotations
 
 from datetime import datetime, timezone
+from typing import Any, Iterable
 
 from sqlalchemy import DateTime, String
 from sqlalchemy.orm import Mapped, mapped_column
 
-__all__ = ["AuthUserMixin"]
+__all__ = ["AuthUserMixin", "make_auth_identity"]
 
 
 def _utcnow() -> datetime:
     return datetime.now(timezone.utc)
 
 
-class AuthUserMixin:
-    """Declarative mixin supplying the full set of columns crudauth relies on.
-
-    Note:
-        ``token_version`` is a monotonic credential epoch: bearer tokens embed it
-        as the ``ver`` claim and a password reset bumps it, so a reset rejects
-        every outstanding bearer token. See
-        [BearerTransport][crudauth.transports.bearer.transport.BearerTransport].
+def make_auth_identity(
+    *,
+    identifiers: Iterable[str] = ("email", "username"),
+    recovery: str | None = "email",
+    oauth: bool = True,
+) -> type[Any]:
+    """Build a declarative mixin carrying crudauth's user columns for one account shape.
+
+    The model is the source of truth for shape: this emits the columns, and
+    [CRUDAuth][crudauth.crud_auth.CRUDAuth] reads them back at construction, so the
+    two can't disagree. ``username``, ``hashed_password``, the status flags,
+    ``token_version``, and the timestamps are always emitted; ``email`` and the
+    oauth-linkage columns are conditional.
+
+    Args:
+        identifiers: Logical fields a user may log in with. Each becomes a
+            ``NOT NULL`` unique column. ``email`` here makes the email column
+            required.
+        recovery: The single field recovery (verify/reset/change) is delivered
+            against, or ``None`` for an account shape with no recovery. ``"email"``
+            (and not an identifier) makes the email column nullable but unique.
+        oauth: Emit the oauth-linkage columns (``oauth_provider`` / ``google_id`` /
+            ``github_id`` / timestamps). Required for OAuth login.
+
+    Returns:
+        A declarative mixin class. Inherit it on your model alongside ``Base``.
 
     Example:
         ```python
+        # the default - email + username login, email recovery (today's shape)
         class User(Base, AuthUserMixin):
             __tablename__ = "users"
-            full_name: Mapped[str | None] = mapped_column(default=None)
+
+        # username-only login, phone recovery
+        Identity = make_auth_identity(identifiers=["username"], recovery="phone")
+        class User(Base, Identity):
+            __tablename__ = "users"
+            phone: Mapped[str | None] = mapped_column(unique=True, default=None)
         ```
     """
-
-    # --- core identity -------------------------------------------------------
-    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
-    email: Mapped[str] = mapped_column(String(320), unique=True, index=True)
-    username: Mapped[str] = mapped_column(String(64), unique=True, index=True)
-    hashed_password: Mapped[str] = mapped_column(String(255))
-
-    # --- status flags --------------------------------------------------------
-    is_active: Mapped[bool] = mapped_column(default=True)
-    is_superuser: Mapped[bool] = mapped_column(default=False)
-    email_verified: Mapped[bool] = mapped_column(default=False)
-
-    token_version: Mapped[int] = mapped_column(default=0)
-
-    # --- oauth linkage -------------------------------------------------------
-    oauth_provider: Mapped[str | None] = mapped_column(String(32), default=None)
-    google_id: Mapped[str | None] = mapped_column(String(64), unique=True, index=True, default=None)
-    github_id: Mapped[str | None] = mapped_column(String(64), unique=True, index=True, default=None)
-    oauth_created_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), default=None)
-    oauth_updated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), default=None)
-
-    # --- timestamps ----------------------------------------------------------
-    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
-    updated_at: Mapped[datetime | None] = mapped_column(
-        DateTime(timezone=True), default=None, onupdate=_utcnow
+    ns: dict[str, Any] = {}
+    ann: dict[str, Any] = {}
+
+    def add(name: str, annotation: Any, column: Any) -> None:
+        ann[name] = annotation
+        ns[name] = column
+
+    identifier_set = set(identifiers)
+    email_is_identifier = "email" in identifier_set
+    email_is_recovery = recovery == "email"
+
+    add("id", Mapped[int], mapped_column(primary_key=True, autoincrement=True))
+    if email_is_identifier:
+        add("email", Mapped[str], mapped_column(String(320), unique=True, index=True))
+    elif email_is_recovery:
+        add(
+            "email",
+            Mapped[str | None],
+            mapped_column(String(320), unique=True, index=True, default=None),
+        )
+    add("username", Mapped[str], mapped_column(String(64), unique=True, index=True))
+    add("hashed_password", Mapped[str], mapped_column(String(255)))
+
+    add("is_active", Mapped[bool], mapped_column(default=True))
+    add("is_superuser", Mapped[bool], mapped_column(default=False))
+    add("email_verified", Mapped[bool], mapped_column(default=False))
+    add("token_version", Mapped[int], mapped_column(default=0))
+
+    if oauth:
+        add("oauth_provider", Mapped[str | None], mapped_column(String(32), default=None))
+        add(
+            "google_id",
+            Mapped[str | None],
+            mapped_column(String(64), unique=True, index=True, default=None),
+        )
+        add(
+            "github_id",
+            Mapped[str | None],
+            mapped_column(String(64), unique=True, index=True, default=None),
+        )
+        add(
+            "oauth_created_at",
+            Mapped[datetime | None],
+            mapped_column(DateTime(timezone=True), default=None),
+        )
+        add(
+            "oauth_updated_at",
+            Mapped[datetime | None],
+            mapped_column(DateTime(timezone=True), default=None),
+        )
+
+    add("created_at", Mapped[datetime], mapped_column(DateTime(timezone=True), default=_utcnow))
+    add(
+        "updated_at",
+        Mapped[datetime | None],
+        mapped_column(DateTime(timezone=True), default=None, onupdate=_utcnow),
     )
+
+    ns["__annotations__"] = ann
+    return type("AuthUserMixin", (), ns)
+
+
+AuthUserMixin = make_auth_identity()
+"""Default identity columns: email + username login, email recovery, oauth enabled.
+
+Inherit this for the standard account shape (it is exactly
+``make_auth_identity()``):
+
+```python
+class User(Base, AuthUserMixin):
+    __tablename__ = "users"
+    full_name: Mapped[str | None] = mapped_column(default=None)
+```
+
+``token_version`` is a monotonic credential epoch: bearer tokens embed it as the
+``ver`` claim and a password reset bumps it, so a reset rejects every outstanding
+bearer token.
+"""

crudauth/provisioning.py

@@ -63,11 +63,13 @@ class NewUserContext:
 
     @property
     def suggested_name(self) -> str:
-        """A display name to default to: the OAuth name if present, else the
-        email local-part."""
+        """A display name to default to: the OAuth name, else the email local-part,
+        else the username - so it stays useful across email and email-less shapes."""
         if self.oauth is not None and self.oauth.name:
             return self.oauth.name
-        return self.email.split("@")[0]
+        if self.email:
+            return self.email.split("@")[0]
+        return self.username
 
 
 NewUserFields = Callable[