feat: granular RBAC system with user groups, deny-list, permission registry, system-admin, self-mod prevention

app/models/group.py

@@ -0,0 +1,63 @@
+"""Group and UserGroup models for granular RBAC."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, Integer, String, UniqueConstraint, func
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.core.db import Base, TenantMixin
+
+
+class Group(Base, TenantMixin):
+    """Group entity with RBAC permissions and field-level permissions.
+
+    Groups are tenant-scoped. Users can be members of multiple groups.
+    Effective permissions = (role.permissions ∪ Σ(group.permissions)) − denied.
+    """
+
+    __tablename__ = "groups"
+    __table_args__ = (
+        UniqueConstraint("tenant_id", "name", name="uq_groups_tenant_name"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    name: Mapped[str] = mapped_column(String(100), nullable=False)
+    description: Mapped[str] = mapped_column(String(500), nullable=True, default=None)
+    permissions: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
+    denied_permissions: Mapped[list[str]] = mapped_column(
+        JSONB, nullable=False, default=list
+    )
+    field_permissions: Mapped[dict[str, Any]] = mapped_column(JSONB, default=dict, nullable=False)
+    permission_version: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=1, server_default="1"
+    )
+
+
+class UserGroup(Base):
+    """N:M association — user membership in groups (per tenant)."""
+
+    __tablename__ = "user_groups"
+    __table_args__ = (
+        UniqueConstraint("user_id", "group_id", "tenant_id", name="uq_user_groups_user_group_tenant"),
+    )
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), primary_key=True
+    )
+    group_id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), ForeignKey("groups.id", ondelete="CASCADE"), primary_key=True
+    )
+    tenant_id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )