feat(auth): implement group-role mapping and permission system

Architecture changes:
- Permission format: domain.category:action (e.g., control-room.general:admin)
- Decoupled groups from roles via group_roles mapping table
- Groups are organizational (synced from Authentik)
- Roles are permissions (admin-managed via API)

New features:
- require_permission() and require_any_permission() dependency factories
- Action hierarchy: admin > editor > user > viewer
- Global admin override (admin.general:admin grants all)
- Group-role management endpoints (assign/remove roles)
- GET /auth/roles endpoint to list all roles

Database changes:
- Added category column to roles table (default: general)
- Removed authentik_group column (decoupled)
- Added group_roles association table
- Added user_groups association table
- Migration updates role names to domain.general:action format

Tests:
- 67 new tests for auth service and controller
- Covers token validation, user sync, role sync
- Covers group-role assignment/removal
- Covers schema conversions and permission system

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/domains/auth/models.py

@@ -26,6 +26,13 @@ user_groups = Table(
     Column("group_id", UUID(as_uuid=True), ForeignKey("groups.id", ondelete="CASCADE"), primary_key=True),
 )
 
+group_roles = Table(
+    "group_roles",
+    Base.metadata,
+    Column("group_id", UUID(as_uuid=True), ForeignKey("groups.id", ondelete="CASCADE"), primary_key=True),
+    Column("role_id", UUID(as_uuid=True), ForeignKey("roles.id", ondelete="CASCADE"), primary_key=True),
+)
+
 
 # =============================================================================
 # User Model
@@ -114,8 +121,13 @@ class Role(Base):
     """
     Role model for domain-scoped permissions
 
+    Permission format: domain.category:action
+    - domain: Main area (control-room, library, media, ai, etc.)
+    - category: Sub-area within domain (general for full access, or specific tools)
+    - action: Permission level (viewer, user, editor, admin)
+
     Roles are seeded from configuration, not user-editable.
-    Each role maps to an Authentik group (e.g., tatlock-control-room-admin).
+    Groups are assigned roles via the group_roles mapping table.
 
     Domains: control-room, library, media, ai, housekeeper, developer, documents, gaming, admin
     Actions: viewer, user, editor, admin (hierarchical)
@@ -133,7 +145,7 @@ class Role(Base):
         unique=True,
         nullable=False,
         index=True,
-        comment="Role name in format domain:action (e.g., control-room:admin)",
+        comment="Role name in format domain.category:action (e.g., control-room.general:admin)",
     )
     domain: Mapped[str] = mapped_column(
         String(50),
@@ -141,17 +153,17 @@ class Role(Base):
         index=True,
         comment="Permission domain (e.g., control-room, media, ai)",
     )
+    category: Mapped[str] = mapped_column(
+        String(50),
+        nullable=False,
+        default="general",
+        comment="Permission category within domain (general for full access, or specific tool)",
+    )
     action: Mapped[str] = mapped_column(
         String(20),
         nullable=False,
         comment="Permission action (viewer, user, editor, admin)",
     )
-    authentik_group: Mapped[str | None] = mapped_column(
-        String(255),
-        nullable=True,
-        unique=True,
-        comment="Corresponding Authentik group name (e.g., tatlock-control-room-admin)",
-    )
 
     # Relationships
     users: Mapped[List["User"]] = relationship(
@@ -160,6 +172,12 @@ class Role(Base):
         back_populates="roles",
         lazy="selectin",
     )
+    groups: Mapped[List["Group"]] = relationship(
+        "Group",
+        secondary="group_roles",
+        back_populates="roles",
+        lazy="selectin",
+    )
 
     def __repr__(self) -> str:
         return f"<Role {self.name}>"
@@ -247,6 +265,14 @@ class Group(Base):
         comment="Last sync from Authentik",
     )
 
+    # Relationships
+    roles: Mapped[List["Role"]] = relationship(
+        "Role",
+        secondary="group_roles",
+        back_populates="groups",
+        lazy="selectin",
+    )
+
     def __repr__(self) -> str:
         return f"<Group {self.name}>"