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>

alembic/versions/20260103_1500_004_add_group_roles_mapping.py

@@ -0,0 +1,141 @@
+"""Add group_roles mapping and update role schema
+
+Revision ID: 004
+Revises: f0349c95aa5d
+Create Date: 2026-01-03
+
+Changes:
+- Add category column to roles (default 'general')
+- Drop authentik_group column from roles (decoupled architecture)
+- Create user_groups association table
+- Create group_roles association table
+- Update role names from domain:action to domain.general:action
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "004"
+down_revision: Union[str, None] = "f0349c95aa5d"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Add category column to roles
+    op.add_column(
+        "roles",
+        sa.Column(
+            "category",
+            sa.String(50),
+            nullable=False,
+            server_default="general",
+            comment="Permission category within domain (general for full access, or specific tool)",
+        ),
+    )
+
+    # Update role names from domain:action to domain.general:action
+    op.execute(
+        """
+        UPDATE roles
+        SET name = REPLACE(name, ':', '.general:')
+        WHERE name NOT LIKE '%.%:%'
+        """
+    )
+
+    # Update the comment on the name column
+    op.alter_column(
+        "roles",
+        "name",
+        comment="Role name in format domain.category:action (e.g., control-room.general:admin)",
+    )
+
+    # Drop the authentik_group unique index first
+    op.drop_index("ix_roles_authentik_group", table_name="roles")
+
+    # Drop authentik_group column (no longer needed with group_roles mapping)
+    op.drop_column("roles", "authentik_group")
+
+    # Create user_groups association table
+    op.create_table(
+        "user_groups",
+        sa.Column(
+            "user_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            primary_key=True,
+        ),
+        sa.Column(
+            "group_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("groups.id", ondelete="CASCADE"),
+            primary_key=True,
+        ),
+    )
+
+    # Create group_roles association table
+    op.create_table(
+        "group_roles",
+        sa.Column(
+            "group_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("groups.id", ondelete="CASCADE"),
+            primary_key=True,
+        ),
+        sa.Column(
+            "role_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("roles.id", ondelete="CASCADE"),
+            primary_key=True,
+        ),
+    )
+
+
+def downgrade() -> None:
+    # Drop association tables
+    op.drop_table("group_roles")
+    op.drop_table("user_groups")
+
+    # Add back authentik_group column
+    op.add_column(
+        "roles",
+        sa.Column(
+            "authentik_group",
+            sa.String(255),
+            nullable=True,
+            comment="Corresponding Authentik group name",
+        ),
+    )
+
+    # Restore authentik_group values from role names
+    op.execute(
+        """
+        UPDATE roles
+        SET authentik_group = 'tatlock-' || REPLACE(REPLACE(name, '.general:', '-'), ':', '-')
+        """
+    )
+
+    # Recreate the unique index
+    op.create_index("ix_roles_authentik_group", "roles", ["authentik_group"], unique=True)
+
+    # Revert role names from domain.general:action to domain:action
+    op.execute(
+        """
+        UPDATE roles
+        SET name = REPLACE(name, '.general:', ':')
+        WHERE name LIKE '%.general:%'
+        """
+    )
+
+    # Update the comment on the name column
+    op.alter_column(
+        "roles",
+        "name",
+        comment="Role name in format domain:action",
+    )
+
+    # Drop category column
+    op.drop_column("roles", "category")