P1.6: secure guest invitation tokens (secrets.token_urlsafe + SHA-256 hash + one-time use + session revocation)

app/models/__init__.py

@@ -12,6 +12,7 @@ from app.models.contact_folder_permission import ContactFolderPermission
 from app.models.contact_merge import ContactMergeHistory
 from app.models.entity_permission import EntityPermission
 from app.models.guest_user import GuestUser
+from app.models.guest_invitation import GuestInvitation
 from app.models.entity_policy import EntityPolicy
 from app.models.permission_template import PermissionTemplate
 from app.models.permission_delegation import PermissionDelegation
@@ -55,6 +56,7 @@ __all__ = [
     "ContactFolderPermission",
     "ContactMergeHistory",
     "EntityPermission",
+    "GuestInvitation",
     "GuestUser",
     "PermissionDelegation",
     "PermissionTemplate",

app/models/guest_invitation.py

@@ -0,0 +1,43 @@
+"""Guest invitation model — secure token-based invitations."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, String, func
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.core.db import Base
+
+
+class GuestInvitation(Base):
+    """Secure invitation token for guest users.
+
+    Token is a random 32-byte URL-safe string.
+    Only the hash is stored in the database.
+    One-time use: used_at is set on acceptance.
+    """
+
+    __tablename__ = "guest_invitations"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    guest_user_id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True),
+        ForeignKey("guest_users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    token_hash: Mapped[str] = mapped_column(String(64), nullable=False, unique=True, index=True)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True, default=None)
+    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True, default=None)
+    created_by: Mapped[uuid.UUID | None] = mapped_column(
+        PGUUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )