feat: folder permissions (ACLs) - share folders with users/groups, inherit to subfolders, permission dialog UI

app/models/__init__.py

@@ -8,6 +8,7 @@ from app.models.audit import AuditLog, DeletionLog
 from app.models.auth import ApiToken, PasswordResetToken
 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_history import EntityHistory
 from app.models.currency import Currency
@@ -45,6 +46,7 @@ __all__ = [
     "Contact",
     "ContactPerson",
     "ContactFolder",
+    "ContactFolderPermission",
     "ContactMergeHistory",
     "EntityHistory",
     "Currency",

app/models/contact_folder_permission.py

@@ -0,0 +1,90 @@
+"""Contact folder permission model — ACLs for folder sharing."""
+
+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 ContactFolderPermission(Base, TenantMixin):
+    """ACL entry for a contact folder.
+
+    Grants a specific permission level to a user or group for a folder.
+    When ``inherit_to_subfolders`` is True, the permission also applies
+    to all descendant folders.
+
+    Permission levels:
+    - ``none``   — no access (explicit deny)
+    - ``read``   — view folder and its contacts
+    - ``write``  — read + edit contacts, add contacts to folder
+    - ``admin``  — read + write + delete contacts + manage folder permissions
+    """
+
+    __tablename__ = "contact_folder_permissions"
+    __table_args__ = (
+        UniqueConstraint(
+            "folder_id",
+            "user_id",
+            "group_id",
+            "tenant_id",
+            name="uq_cfp_folder_user_group_tenant",
+        ),
+        # Ensure exactly one of user_id or group_id is set (not both, not neither)
+        CheckConstraint(
+            "(user_id IS NOT NULL AND group_id IS NULL) OR "
+            "(user_id IS NULL AND group_id IS NOT NULL)",
+            name="ck_cfp_exactly_one_principal",
+        ),
+        Index("ix_cfp_folder", "folder_id"),
+        Index("ix_cfp_user", "user_id"),
+        Index("ix_cfp_group", "group_id"),
+        Index("ix_cfp_tenant", "tenant_id"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    folder_id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True),
+        ForeignKey("contact_folders.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    user_id: Mapped[uuid.UUID | None] = mapped_column(
+        PGUUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=True,
+    )
+    group_id: Mapped[uuid.UUID | None] = mapped_column(
+        PGUUID(as_uuid=True),
+        ForeignKey("groups.id", ondelete="CASCADE"),
+        nullable=True,
+    )
+    permission_level: Mapped[str] = mapped_column(
+        String(20), nullable=False, default="read"
+    )  # none | read | write | admin
+    inherit_to_subfolders: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True, server_default="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(),
+    )