feat: add role-based admin support for multiple admin users

- Add Role model and user_roles association table (many-to-many)
- Add password_hash column to User model (nullable, for future bcrypt)
- Keep is_admin boolean for backward compatibility
- Add is_admin_effective property: true if legacy is_admin OR 'admin' role
- Update auth dependency (get_current_admin_user) to use is_admin_effective
- Update bootstrap login to auto-create 'admin' role and assign on login
- Update Google OAuth login to use is_admin_effective for token creation
- Add migrate_roles.py: idempotent migration script to backfill roles
- Add unit tests for Role, User, association table, and is_admin_effective

backend/app/api/auth.py

@@ -57,8 +57,18 @@ async def login(payload: LoginRequest):
 
     # This is handled in the auth router to keep it self-contained
     from app.database import async_session
+    from app.user_models import Role
 
     async with async_session() as session:
+        # Ensure the 'admin' role exists
+        result = await session.execute(select(Role).where(Role.name == "admin"))
+        admin_role = result.scalar_one_or_none()
+        if admin_role is None:
+            admin_role = Role(name="admin", description="Full administrative access")
+            session.add(admin_role)
+            await session.commit()
+            await session.refresh(admin_role)
+
         # Find or create the bootstrap admin user
         result = await session.execute(
             select(User).where(
@@ -74,11 +84,16 @@ async def login(payload: LoginRequest):
                 auth_provider="local",
                 is_admin=True,
             )
+            user.roles.append(admin_role)
             session.add(user)
-            await session.commit()
-            await session.refresh(user)
+        else:
+            # Ensure existing bootstrap user also has the role
+            if admin_role not in user.roles:
+                user.roles.append(admin_role)
+        await session.commit()
+        await session.refresh(user)
 
-    token = create_access_token(user.id, user.is_admin)
+    token = create_access_token(user.id, user.is_admin_effective)
     return TokenResponse(access_token=token)
 
 
@@ -102,7 +117,7 @@ async def login_with_google(payload: GoogleLoginRequest, session: AsyncSession =
         await session.commit()
         await session.refresh(user)
 
-    token = create_access_token(user.id, user.is_admin)
+    token = create_access_token(user.id, user.is_admin_effective)
     return TokenResponse(access_token=token)
 
 

backend/app/auth.py

@@ -98,8 +98,11 @@ async def get_current_user(
 async def get_current_admin_user(
     current_user: User = Depends(get_current_user),
 ) -> User:
-    """Raise 403 if the current user is not an admin."""
-    if not current_user.is_admin:
+    """Raise 403 if the current user is not an admin.
+
+    Checks both the legacy is_admin flag and the new role-based admin role.
+    """
+    if not current_user.is_admin_effective:
         raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Admin access required")
     return current_user
 

backend/app/user_models.py

@@ -1,11 +1,47 @@
+"""User, Role, and UserRole models — supports multiple admin roles."""
+
 from datetime import datetime
 
-from sqlalchemy import Column, Integer, String, Boolean, DateTime
-from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy import (
+    Boolean,
+    Column,
+    DateTime,
+    ForeignKey,
+    Integer,
+    String,
+    Table,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import DeclarativeBase, relationship
 
 from app.models import Base
 
 
+# ── Many-to-many: users ↔ roles ──────────────────────────────────────────────
+
+user_roles = Table(
+    "user_roles",
+    Base.metadata,
+    Column("user_id", Integer, ForeignKey("users.id", ondelete="CASCADE"), primary_key=True),
+    Column("role_id", Integer, ForeignKey("roles.id", ondelete="CASCADE"), primary_key=True),
+)
+
+
+# ── Role ─────────────────────────────────────────────────────────────────────
+
+class Role(Base):
+    __tablename__ = "roles"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    name = Column(String(50), unique=True, nullable=False)
+    description = Column(Text, nullable=True)
+
+    users = relationship("User", secondary=user_roles, back_populates="roles")
+
+
+# ── User ─────────────────────────────────────────────────────────────────────
+
 class User(Base):
     __tablename__ = "users"
 
@@ -14,5 +50,16 @@ class User(Base):
     display_name = Column(String(100), nullable=False)
     avatar_url = Column(String(500), nullable=True)
     auth_provider = Column(String(20), nullable=False, default="google")
+    password_hash = Column(String(255), nullable=True)
     is_admin = Column(Boolean, default=False)
     created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+
+    # Role-based admin (many-to-many)
+    roles = relationship("Role", secondary=user_roles, back_populates="users")
+
+    @property
+    def is_admin_effective(self) -> bool:
+        """True when is_admin=True (legacy) OR the user has an 'admin' role."""
+        if self.is_admin:
+            return True
+        return any(role.name == "admin" for role in self.roles)