sprint20-23: tests + documentation + guest access + infrastructure + migrations 0059

app/models/__init__.py

@@ -11,6 +11,7 @@ from app.models.contact_folder import ContactFolder
 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.entity_policy import EntityPolicy
 from app.models.permission_template import PermissionTemplate
 from app.models.permission_delegation import PermissionDelegation
@@ -54,6 +55,7 @@ __all__ = [
     "ContactFolderPermission",
     "ContactMergeHistory",
     "EntityPermission",
+    "GuestUser",
     "PermissionDelegation",
     "PermissionTemplate",
     "EntityPolicy",

app/models/guest_user.py

@@ -0,0 +1,60 @@
+"""Guest User model — for time-limited guest access via entity permissions."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Index, String, func
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.core.db import Base, TenantMixin
+
+
+class GuestUser(Base, TenantMixin):
+    """Guest user with time-limited access to shared entities.
+
+    Guests are invited by tenant admins and can only access entities
+    that have explicit entity_permissions with principal_type='guest'.
+    """
+
+    __tablename__ = "guest_users"
+    __table_args__ = (
+        Index("ix_guest_users_email_tenant", "email", "tenant_id", unique=True),
+        Index("ix_guest_users_status", "status", "tenant_id"),
+        Index("ix_guest_users_invited_by", "invited_by"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    email: Mapped[str] = mapped_column(String(255), nullable=False)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    password_hash: Mapped[str | None] = mapped_column(
+        String(255), nullable=True, default=None
+    )
+    tenant_id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True),
+        ForeignKey("tenants.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    invited_by: Mapped[uuid.UUID | None] = mapped_column(
+        PGUUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    status: Mapped[str] = mapped_column(
+        String(20), nullable=False, default="invited"
+    )  # 'invited', 'active', 'expired', 'revoked'
+    expires_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True, default=None
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now(),
+        onupdate=func.now(),
+    )