sprint1: entity_permissions table + owned_mixin + universal permission service + API + migrations 0049+0050

app/models/__init__.py

@@ -10,6 +10,8 @@ from app.models.contact import Contact, ContactPerson
 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.owned_mixin import OwnedMixin
 from app.models.entity_history import EntityHistory
 from app.models.currency import Currency
 from app.models.group import Group, UserGroup
@@ -48,6 +50,8 @@ __all__ = [
     "ContactFolder",
     "ContactFolderPermission",
     "ContactMergeHistory",
+    "EntityPermission",
+    "OwnedMixin",
     "EntityHistory",
     "Currency",
     "TaxRate",

app/models/address.py

@@ -9,6 +9,7 @@ from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
 
 
 class Address(Base, TenantMixin):

app/models/ai_conversation.py

@@ -11,6 +11,7 @@ from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
 
 
 class AIConversation(Base, TenantMixin):

app/models/attachment.py

@@ -10,6 +10,7 @@ from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
 
 
 class Attachment(Base, TenantMixin):

app/models/bank_account.py

@@ -9,6 +9,7 @@ from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
 
 
 class BankAccount(Base, TenantMixin):

app/models/contact.py

@@ -27,9 +27,10 @@ from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
 
 
-class Contact(Base, TenantMixin):
+class Contact(Base, TenantMixin, OwnedMixin):
     """Unified contact entity — can be a company or a person.
 
     type='company': name is the company name, firstname/surname empty.

app/models/custom_field_definition.py

@@ -10,6 +10,7 @@ from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
 
 
 class CustomFieldDefinition(Base, TenantMixin):

app/models/entity_history.py

@@ -12,6 +12,7 @@ from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
 
 
 class EntityHistory(Base, TenantMixin):

app/models/entity_permission.py

@@ -0,0 +1,109 @@
+"""Universal entity permission model — ACLs for ANY entity in the system.
+
+This single table stores permissions for contacts, files, mailboxes,
+calendar events, tasks, workflows, and any future entity type.
+
+Architecture:
+- entity_type + entity_id identify the datensatz
+- principal_type + principal_id identify who gets access
+- permission_level defines what they can do
+- expires_at enables time-limited sharing
+
+Resolution (highest wins):
+1. Owner → 'owner' (from owner_id on the entity)
+2. Direct user permission
+3. Group permission (via user_groups)
+4. Role permission (via user_tenants.role_id)
+5. No access → 'none'
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import (
+    Boolean,
+    CheckConstraint,
+    DateTime,
+    ForeignKey,
+    Index,
+    String,
+    UniqueConstraint,
+    func,
+)
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.core.db import Base, TenantMixin
+
+
+class EntityPermission(Base, TenantMixin):
+    """Universal ACL entry for any entity in the system.
+
+    entity_type examples: 'contact', 'dms_file', 'mailbox', 'calendar_event',
+    'task', 'workflow', 'contact_folder', etc.
+
+    principal_type: 'user', 'group', 'role', 'guest'
+
+    permission_level: 'none' | 'read' | 'write' | 'admin' | 'delete'
+    - none:   explicit deny (overrides allow)
+    - read:   view the entity
+    - write:  read + edit entity fields
+    - admin:  write + delete + manage permissions
+    - delete: admin + transfer ownership
+    """
+
+    __tablename__ = "entity_permissions"
+    __table_args__ = (
+        UniqueConstraint(
+            "entity_type",
+            "entity_id",
+            "principal_type",
+            "principal_id",
+            "tenant_id",
+            name="uq_ep_entity_principal_tenant",
+        ),
+        CheckConstraint(
+            "principal_type IN ('user', 'group', 'role', 'guest')",
+            name="ck_ep_principal_type",
+        ),
+        CheckConstraint(
+            "permission_level IN ('none', 'read', 'write', 'admin', 'delete')",
+            name="ck_ep_permission_level",
+        ),
+        Index("ix_ep_entity", "entity_type", "entity_id"),
+        Index("ix_ep_principal", "principal_type", "principal_id"),
+        Index("ix_ep_tenant", "tenant_id"),
+        Index("ix_ep_expires", "expires_at"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    entity_type: Mapped[str] = mapped_column(String(50), nullable=False)
+    entity_id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), nullable=False
+    )
+    principal_type: Mapped[str] = mapped_column(String(10), nullable=False)
+    principal_id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), nullable=False
+    )
+    permission_level: Mapped[str] = mapped_column(
+        String(20), nullable=False, default="read"
+    )
+    expires_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()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now(),
+        onupdate=func.now(),
+    )

app/models/notification.py

@@ -19,6 +19,7 @@ from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
 
 
 class Notification(Base, TenantMixin):

app/models/owned_mixin.py

@@ -0,0 +1,31 @@
+"""OwnedMixin — adds owner_id to any model for row-level ownership.
+
+Usage:
+    class Contact(Base, TenantMixin, OwnedMixin):
+        ...
+
+owner_id semantics:
+- NULL → "tenant-owned" (visible to all with module permission)
+- UUID → owned by that user (visible to owner + shared via entity_permissions)
+- When creating: owner_id = current_user.id (set automatically by service layer)
+- Transfer: only owner, admin, or system_admin can change owner_id
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import ForeignKey, Index
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class OwnedMixin:
+    """Mixin that adds owner_id column to a model."""
+
+    owner_id: Mapped[uuid.UUID | None] = mapped_column(
+        PGUUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )

app/models/saved_filter.py

@@ -11,6 +11,7 @@ from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
 
 
 class SavedFilter(Base, TenantMixin):

app/models/saved_view.py

@@ -11,6 +11,7 @@ from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
 
 
 class SavedView(Base, TenantMixin):

app/models/sequence.py

@@ -10,6 +10,7 @@ from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
 
 
 class Sequence(Base, TenantMixin):

app/models/webhook.py

@@ -9,6 +9,7 @@ from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
 
 
 class Webhook(Base, TenantMixin):

app/models/workflow.py

@@ -12,6 +12,7 @@ from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
 
 
 class Workflow(Base, TenantMixin):