feat: add authentication and user management with Authentik integration

- Add PostgreSQL database with async SQLAlchemy
- Add Alembic migrations for schema management
- Add User, Role, UserPreferences, ApiKey models
- Add auth endpoints: /auth/me, /auth/users, /auth/users/sync-from-authentik
- Add token validation via Authentik userinfo endpoint
- Add bulk user sync from Authentik admin API
- Add database health check to diagnostics

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

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

src/db/models/__init__.py

@@ -0,0 +1,17 @@
+"""
+SQLAlchemy Models for Core-API
+
+Database models for authentication, authorization, and user management.
+"""
+from src.db.models.user import User
+from src.db.models.role import Role, UserRole
+from src.db.models.user_preferences import UserPreferences
+from src.db.models.api_key import ApiKey
+
+__all__ = [
+    "User",
+    "Role",
+    "UserRole",
+    "UserPreferences",
+    "ApiKey",
+]

src/db/models/api_key.py

@@ -0,0 +1,98 @@
+"""
+API Key Model
+
+Provides API key authentication as fallback for OIDC.
+Keys are tied to user accounts and inherit user permissions.
+"""
+import uuid
+from datetime import datetime
+
+from sqlalchemy import String, ForeignKey, DateTime, func
+from sqlalchemy.dialects.postgresql import UUID, ARRAY
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.db.database import Base
+
+from typing import TYPE_CHECKING, List
+
+if TYPE_CHECKING:
+    from src.db.models.user import User
+
+
+class ApiKey(Base):
+    """
+    API Key model for programmatic access
+
+    API keys provide an alternative to OIDC for:
+    - Local development without SSO
+    - Service-to-service communication
+    - Scripts and automation
+
+    Keys inherit the user's roles but can optionally
+    be restricted to a subset of scopes.
+    """
+
+    __tablename__ = "api_keys"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4,
+    )
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    name: Mapped[str] = mapped_column(
+        String(100),
+        nullable=False,
+        comment="Human-readable key name (e.g., 'Dev Laptop', 'CI/CD')",
+    )
+    key_hash: Mapped[str] = mapped_column(
+        String(255),
+        nullable=False,
+        comment="SHA-256 hash of the API key",
+    )
+    key_prefix: Mapped[str] = mapped_column(
+        String(8),
+        nullable=False,
+        comment="First 8 chars of key for identification (e.g., 'cak_abc1')",
+    )
+    scopes: Mapped[List[str] | None] = mapped_column(
+        ARRAY(String),
+        nullable=True,
+        comment="Optional scope restriction (subset of user roles)",
+    )
+    expires_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+        comment="Optional expiration timestamp",
+    )
+    last_used_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+        comment="Last time this key was used",
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+    )
+
+    # Relationships
+    user: Mapped["User"] = relationship(
+        "User",
+        back_populates="api_keys",
+    )
+
+    def __repr__(self) -> str:
+        return f"<ApiKey {self.key_prefix}... ({self.name})>"
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if the API key has expired"""
+        if self.expires_at is None:
+            return False
+        return datetime.now(self.expires_at.tzinfo) > self.expires_at

src/db/models/role.py

@@ -0,0 +1,93 @@
+"""
+Role Models
+
+Defines domain-scoped permissions mapped from Authentik groups.
+Format: {domain}:{action} (e.g., control-room:admin, media:viewer)
+"""
+import uuid
+from typing import TYPE_CHECKING, List
+
+from sqlalchemy import String, ForeignKey
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.db.database import Base
+
+if TYPE_CHECKING:
+    from src.db.models.user import User
+
+
+class Role(Base):
+    """
+    Role model for domain-scoped permissions
+
+    Roles are seeded from configuration, not user-editable.
+    Each role maps to an Authentik group (e.g., tatlock-control-room-admin).
+
+    Domains: control-room, library, media, ai, housekeeper, developer, documents, gaming, admin
+    Actions: viewer, user, editor, admin (hierarchical)
+    """
+
+    __tablename__ = "roles"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4,
+    )
+    name: Mapped[str] = mapped_column(
+        String(100),
+        unique=True,
+        nullable=False,
+        index=True,
+        comment="Role name in format domain:action (e.g., control-room:admin)",
+    )
+    domain: Mapped[str] = mapped_column(
+        String(50),
+        nullable=False,
+        index=True,
+        comment="Permission domain (e.g., control-room, media, ai)",
+    )
+    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(
+        "User",
+        secondary="user_roles",
+        back_populates="roles",
+        lazy="selectin",
+    )
+
+    def __repr__(self) -> str:
+        return f"<Role {self.name}>"
+
+
+class UserRole(Base):
+    """
+    Association table for User-Role many-to-many relationship
+
+    Synced from Authentik groups during user authentication.
+    """
+
+    __tablename__ = "user_roles"
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    role_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("roles.id", ondelete="CASCADE"),
+        primary_key=True,
+    )

src/db/models/user.py

@@ -0,0 +1,94 @@
+"""
+User Model
+
+Represents users synced from Authentik SSO.
+"""
+import uuid
+from datetime import datetime
+from typing import TYPE_CHECKING, List
+
+from sqlalchemy import String, Boolean, DateTime, func
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.db.database import Base
+
+if TYPE_CHECKING:
+    from src.db.models.role import Role
+    from src.db.models.user_preferences import UserPreferences
+    from src.db.models.api_key import ApiKey
+
+
+class User(Base):
+    """
+    User model synced from Authentik
+
+    Users are created/updated when they authenticate via OIDC.
+    The authentik_id links to the Authentik user record.
+    """
+
+    __tablename__ = "users"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4,
+    )
+    authentik_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        unique=True,
+        nullable=False,
+        index=True,
+    )
+    email: Mapped[str] = mapped_column(
+        String(255),
+        unique=True,
+        nullable=False,
+        index=True,
+    )
+    name: Mapped[str] = mapped_column(
+        String(255),
+        nullable=False,
+    )
+    avatar_url: Mapped[str | None] = mapped_column(
+        String(500),
+        nullable=True,
+    )
+    api_keys_enabled: Mapped[bool] = mapped_column(
+        Boolean,
+        default=True,
+        nullable=False,
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+    )
+    last_login: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+    )
+
+    # Relationships
+    roles: Mapped[List["Role"]] = relationship(
+        "Role",
+        secondary="user_roles",
+        back_populates="users",
+        lazy="selectin",
+    )
+    preferences: Mapped["UserPreferences"] = relationship(
+        "UserPreferences",
+        back_populates="user",
+        uselist=False,
+        lazy="selectin",
+        cascade="all, delete-orphan",
+    )
+    api_keys: Mapped[List["ApiKey"]] = relationship(
+        "ApiKey",
+        back_populates="user",
+        lazy="selectin",
+        cascade="all, delete-orphan",
+    )
+
+    def __repr__(self) -> str:
+        return f"<User {self.email}>"

src/db/models/user_preferences.py

@@ -0,0 +1,61 @@
+"""
+User Preferences Model
+
+Stores user-specific settings like theme and default room.
+"""
+import uuid
+
+from sqlalchemy import String, ForeignKey
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.db.database import Base
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from src.db.models.user import User
+
+
+class UserPreferences(Base):
+    """
+    User preferences model
+
+    Stores user-specific settings that persist across sessions.
+    Extended settings stored in preferences_json for flexibility.
+    """
+
+    __tablename__ = "user_preferences"
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    theme: Mapped[str] = mapped_column(
+        String(20),
+        default="system",
+        nullable=False,
+        comment="Theme preference: system, light, dark",
+    )
+    default_room: Mapped[str] = mapped_column(
+        String(50),
+        default="front-hall",
+        nullable=False,
+        comment="Default room for housekeeping features",
+    )
+    preferences_json: Mapped[dict] = mapped_column(
+        JSONB,
+        default=dict,
+        nullable=False,
+        comment="Extended preferences as JSON",
+    )
+
+    # Relationships
+    user: Mapped["User"] = relationship(
+        "User",
+        back_populates="preferences",
+    )
+
+    def __repr__(self) -> str:
+        return f"<UserPreferences user_id={self.user_id}>"