feat(users): invite by email — a one-time link where the invitee makes their own account (milestone 496)

The operator's ask: an invite link sent by mail, the key in the URL, and
the new user choosing their own username, password and email.

- user_invites (migration 0037): the key's sha256 only, the address, the
  role and days the admin chose, who sent it, used/revoked.
- core/invites: create (revokes an older open invite to the address),
  renew (new key, new clock), find_pending, the four states, signup checks.
- /invite/<key>, outside sign-in and throttled like login: the invitee's
  username, email (prefilled, theirs to change) and password; the account
  takes the admin's role, the key is used up in the same transaction and
  they are signed in. A bad key gets one plain message.
- Settings › Users: Invite by email (address, role, 1/7/30 days), sent from
  the admin in their zone; without a mail server, or if sending fails, the
  link is shown once to copy. Invites not yet used are listed with Resend
  and Withdraw.
- Audit: user.invited, user.invite_resent, user.invite_revoked, user.joined.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

steward/models/__init__.py

@@ -1,6 +1,7 @@
 from .base import Base
 from .users import User
 from .api_tokens import ApiToken
+from .invites import UserInvite
 from .hosts import Host
 from .monitors import Monitor, MonitorResult, MonitorType
 from .metrics import PluginMetric
@@ -12,7 +13,7 @@ from .settings import AppSetting
 from .dashboard import Dashboard, DashboardWidget, DashboardShareToken
 
 __all__ = [
-    "Base", "User", "ApiToken",
+    "Base", "User", "ApiToken", "UserInvite",
     "Host",
     "Monitor", "MonitorResult", "MonitorType",
     "PluginMetric",

steward/models/invites.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+from datetime import datetime, timezone
+from sqlalchemy import DateTime, Enum, ForeignKey, Integer, String
+from sqlalchemy.orm import Mapped, mapped_column
+from .base import Base
+from .users import UserRole
+
+
+class UserInvite(Base):
+    """An emailed invitation to make a local account (milestone 496). The link
+    carries a one-time key; only its sha256 is stored, as for API tokens. The
+    admin chose the role and how many days the link works; the invitee
+    chooses their own username, email and password."""
+    __tablename__ = "user_invites"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    key_hash: Mapped[str] = mapped_column(String(64), unique=True, nullable=False)
+    # Where the invite was sent; the invitee may sign up with another address.
+    email: Mapped[str] = mapped_column(String(255), nullable=False)
+    role: Mapped[UserRole] = mapped_column(Enum(UserRole), nullable=False, default=UserRole.viewer)
+    days: Mapped[int] = mapped_column(Integer, nullable=False, default=7)
+    invited_by: Mapped[str | None] = mapped_column(
+        String(36), ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=lambda: datetime.now(timezone.utc))
+    # When the current key was sent; a resend replaces the key and restarts the clock.
+    sent_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=lambda: datetime.now(timezone.utc))
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    used_by: Mapped[str | None] = mapped_column(
+        String(36), ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)