feat(auth): Add optional authentication system (#22)

Backend:
- Add User model with username, hashed password, role, is_active
- Add passlib[bcrypt] and python-jose[cryptography] dependencies
- Create auth.py with JWT utilities, password hashing, role checking
- Add /auth endpoints: status, setup, login, me, users CRUD
- Add role-based permission system (viewer/operator/editor/admin)
- Environment: SPOOLMAN_AUTH_ENABLED, SPOOLMAN_AUTH_SECRET_KEY
- Migration for user table

Frontend:
- Add AuthProvider context with login/logout/setup
- Add LoginPage component with setup mode for first user
- Add ProtectedRoute wrapper for auth-required pages
- Add axios interceptor to attach JWT token to requests
- Add User Management tab in Settings (admin only)
- Add translation keys for auth UI

When SPOOLMAN_AUTH_ENABLED=true:
- Users must login to access the app
- First visit shows setup page to create admin account
- Role-based access control for future endpoint protection

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

spoolman/api/v1/auth.py

@@ -0,0 +1,289 @@
+"""Authentication API endpoints."""
+
+import logging
+from datetime import datetime
+from typing import Annotated, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordRequestForm
+from pydantic import BaseModel, Field
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from spoolman import auth
+from spoolman.auth import (
+    RequireAdmin,
+    Role,
+    Token,
+    UserResponse,
+    authenticate_user,
+    create_access_token,
+    get_current_user,
+    get_password_hash,
+    get_user_by_username,
+    is_auth_enabled,
+)
+from spoolman.database import models
+from spoolman.database.database import get_db_session
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(
+    prefix="/auth",
+    tags=["auth"],
+)
+
+
+class AuthStatusResponse(BaseModel):
+    """Authentication status response."""
+
+    enabled: bool
+    has_users: bool
+
+
+class UserCreateRequest(BaseModel):
+    """Request to create a new user."""
+
+    username: str = Field(..., min_length=3, max_length=64)
+    password: str = Field(..., min_length=6)
+    role: Role = Role.VIEWER
+
+
+class UserUpdateRequest(BaseModel):
+    """Request to update a user."""
+
+    password: Optional[str] = Field(None, min_length=6)
+    role: Optional[Role] = None
+    is_active: Optional[bool] = None
+
+
+class SetupRequest(BaseModel):
+    """Initial setup request to create admin user."""
+
+    username: str = Field(..., min_length=3, max_length=64)
+    password: str = Field(..., min_length=6)
+
+
+@router.get(
+    "/status",
+    name="Get auth status",
+    description="Check if authentication is enabled and if any users exist.",
+    response_model=AuthStatusResponse,
+)
+async def get_auth_status(
+    db: Annotated[AsyncSession, Depends(get_db_session)],
+) -> AuthStatusResponse:
+    """Get authentication status."""
+    result = await db.execute(select(func.count()).select_from(models.User))
+    user_count = result.scalar() or 0
+    return AuthStatusResponse(
+        enabled=is_auth_enabled(),
+        has_users=user_count > 0,
+    )
+
+
+@router.post(
+    "/setup",
+    name="Initial setup",
+    description="Create the first admin user. Only works if no users exist.",
+    response_model=UserResponse,
+)
+async def setup(
+    body: SetupRequest,
+    db: Annotated[AsyncSession, Depends(get_db_session)],
+) -> UserResponse:
+    """Create the first admin user during initial setup."""
+    # Check if any users exist
+    result = await db.execute(select(func.count()).select_from(models.User))
+    user_count = result.scalar() or 0
+
+    if user_count > 0:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Setup already completed. Users already exist.",
+        )
+
+    # Create admin user
+    user = models.User(
+        username=body.username,
+        hashed_password=get_password_hash(body.password),
+        role=Role.ADMIN.value,
+        is_active=True,
+        created_at=datetime.utcnow(),
+    )
+    db.add(user)
+    await db.commit()
+    await db.refresh(user)
+
+    logger.info("Initial admin user created: %s", body.username)
+    return UserResponse.from_db(user)
+
+
+@router.post(
+    "/login",
+    name="Login",
+    description="Authenticate and get an access token.",
+    response_model=Token,
+)
+async def login(
+    form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
+    db: Annotated[AsyncSession, Depends(get_db_session)],
+) -> Token:
+    """Authenticate user and return JWT token."""
+    if not is_auth_enabled():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Authentication is not enabled",
+        )
+
+    user = await authenticate_user(db, form_data.username, form_data.password)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect username or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    access_token = create_access_token(
+        data={"sub": user.username, "role": user.role}
+    )
+    return Token(access_token=access_token)
+
+
+@router.get(
+    "/me",
+    name="Get current user",
+    description="Get the currently authenticated user's info.",
+    response_model=UserResponse,
+)
+async def get_me(
+    current_user: Annotated[Optional[models.User], Depends(get_current_user)],
+) -> UserResponse:
+    """Get current user info."""
+    if current_user is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated",
+        )
+    return UserResponse.from_db(current_user)
+
+
+# User management endpoints (admin only)
+
+
+@router.get(
+    "/users",
+    name="List users",
+    description="Get all users (admin only).",
+    response_model=list[UserResponse],
+    dependencies=[RequireAdmin],
+)
+async def list_users(
+    db: Annotated[AsyncSession, Depends(get_db_session)],
+) -> list[UserResponse]:
+    """List all users."""
+    result = await db.execute(select(models.User).order_by(models.User.username))
+    users = result.scalars().all()
+    return [UserResponse.from_db(u) for u in users]
+
+
+@router.post(
+    "/users",
+    name="Create user",
+    description="Create a new user (admin only).",
+    response_model=UserResponse,
+    dependencies=[RequireAdmin],
+)
+async def create_user(
+    body: UserCreateRequest,
+    db: Annotated[AsyncSession, Depends(get_db_session)],
+) -> UserResponse:
+    """Create a new user."""
+    # Check if username exists
+    existing = await get_user_by_username(db, body.username)
+    if existing:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Username already exists",
+        )
+
+    user = models.User(
+        username=body.username,
+        hashed_password=get_password_hash(body.password),
+        role=body.role.value,
+        is_active=True,
+        created_at=datetime.utcnow(),
+    )
+    db.add(user)
+    await db.commit()
+    await db.refresh(user)
+
+    logger.info("User created: %s (role: %s)", body.username, body.role.value)
+    return UserResponse.from_db(user)
+
+
+@router.patch(
+    "/users/{user_id}",
+    name="Update user",
+    description="Update a user (admin only).",
+    response_model=UserResponse,
+    dependencies=[RequireAdmin],
+)
+async def update_user(
+    user_id: int,
+    body: UserUpdateRequest,
+    db: Annotated[AsyncSession, Depends(get_db_session)],
+) -> UserResponse:
+    """Update a user."""
+    user = await db.get(models.User, user_id)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found",
+        )
+
+    if body.password is not None:
+        user.hashed_password = get_password_hash(body.password)
+    if body.role is not None:
+        user.role = body.role.value
+    if body.is_active is not None:
+        user.is_active = body.is_active
+
+    await db.commit()
+    await db.refresh(user)
+
+    logger.info("User updated: %s", user.username)
+    return UserResponse.from_db(user)
+
+
+@router.delete(
+    "/users/{user_id}",
+    name="Delete user",
+    description="Delete a user (admin only).",
+    dependencies=[RequireAdmin],
+)
+async def delete_user(
+    user_id: int,
+    current_user: Annotated[Optional[models.User], Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db_session)],
+) -> dict:
+    """Delete a user."""
+    user = await db.get(models.User, user_id)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found",
+        )
+
+    # Prevent self-deletion
+    if current_user and user.id == current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Cannot delete your own account",
+        )
+
+    await db.delete(user)
+    await db.commit()
+
+    logger.info("User deleted: %s", user.username)
+    return {"message": "User deleted"}

spoolman/api/v1/models.py

@@ -444,6 +444,7 @@ class Info(BaseModel):
     db_type: str = Field(examples=["sqlite"])
     git_commit: Optional[str] = Field(None, examples=["a1b2c3d"])
     build_date: Optional[SpoolmanDateTime] = Field(None, examples=["2021-01-01T00:00:00Z"])
+    auth_enabled: bool = Field(default=False, examples=[False])
 
 
 class HealthCheck(BaseModel):

spoolman/api/v1/router.py

@@ -15,7 +15,7 @@ from spoolman.database.database import backup_global_db
 from spoolman.exceptions import ItemNotFoundError
 from spoolman.ws import websocket_manager
 
-from . import backup as backup_module, export, externaldb, field, filament, models, other, print_job, setting, spool, vendor
+from . import auth, backup as backup_module, export, externaldb, field, filament, models, other, print_job, setting, spool, vendor
 
 logger = logging.getLogger(__name__)
 
@@ -57,6 +57,7 @@ async def info() -> models.Info:
         db_type=str(env.get_database_type() or "sqlite"),
         git_commit=env.get_commit_hash(),
         build_date=env.get_build_date(),
+        auth_enabled=auth.is_auth_enabled(),
     )
 
 
@@ -114,3 +115,4 @@ app.include_router(externaldb.router)
 app.include_router(export.router)
 app.include_router(backup_module.router)
 app.include_router(print_job.router)
+app.include_router(auth.router)

spoolman/auth.py

@@ -0,0 +1,211 @@
+"""Authentication utilities and dependencies."""
+
+import logging
+import os
+import secrets
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from typing import Annotated, Optional
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from spoolman.database import models
+from spoolman.database.database import get_db_session
+
+logger = logging.getLogger(__name__)
+
+# JWT Configuration
+SECRET_KEY = os.environ.get("SPOOLMAN_AUTH_SECRET_KEY", secrets.token_urlsafe(32))
+ALGORITHM = "HS256"
+ACCESS_TOKEN_EXPIRE_MINUTES = int(os.environ.get("SPOOLMAN_AUTH_TOKEN_EXPIRE_MINUTES", "1440"))  # 24 hours default
+
+# Password hashing
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+# OAuth2 scheme - auto_error=False allows unauthenticated access when auth is disabled
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="api/v1/auth/login", auto_error=False)
+
+
+def is_auth_enabled() -> bool:
+    """Check if authentication is enabled via environment variable."""
+    return os.environ.get("SPOOLMAN_AUTH_ENABLED", "false").lower() in ("true", "1", "yes")
+
+
+class Role(str, Enum):
+    """User roles with increasing permissions."""
+
+    VIEWER = "viewer"  # Can only view
+    OPERATOR = "operator"  # Can view + record usage
+    EDITOR = "editor"  # Can view + use + create + edit
+    ADMIN = "admin"  # Full access
+
+
+# Role hierarchy - each role includes permissions of roles below it
+ROLE_HIERARCHY = {
+    Role.VIEWER: 0,
+    Role.OPERATOR: 1,
+    Role.EDITOR: 2,
+    Role.ADMIN: 3,
+}
+
+
+class Token(BaseModel):
+    """JWT token response."""
+
+    access_token: str
+    token_type: str = "bearer"
+
+
+class TokenData(BaseModel):
+    """Data extracted from JWT token."""
+
+    username: str
+    role: Role
+
+
+class UserResponse(BaseModel):
+    """User data returned by API (no password)."""
+
+    id: int
+    username: str
+    role: Role
+    is_active: bool
+    created_at: datetime
+
+    @staticmethod
+    def from_db(user: models.User) -> "UserResponse":
+        """Convert database model to response model."""
+        return UserResponse(
+            id=user.id,
+            username=user.username,
+            role=Role(user.role),
+            is_active=user.is_active,
+            created_at=user.created_at,
+        )
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a plain password against a hashed password."""
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def get_password_hash(password: str) -> str:
+    """Hash a password."""
+    return pwd_context.hash(password)
+
+
+def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
+    """Create a JWT access token."""
+    to_encode = data.copy()
+    expire = datetime.now(timezone.utc) + (expires_delta or timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES))
+    to_encode.update({"exp": expire})
+    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
+
+
+async def get_user_by_username(db: AsyncSession, username: str) -> Optional[models.User]:
+    """Get a user by username."""
+    result = await db.execute(select(models.User).where(models.User.username == username))
+    return result.scalar_one_or_none()
+
+
+async def authenticate_user(db: AsyncSession, username: str, password: str) -> Optional[models.User]:
+    """Authenticate a user by username and password."""
+    user = await get_user_by_username(db, username)
+    if not user or not verify_password(password, user.hashed_password):
+        return None
+    if not user.is_active:
+        return None
+    return user
+
+
+async def get_current_user(
+    token: Annotated[Optional[str], Depends(oauth2_scheme)],
+    db: Annotated[AsyncSession, Depends(get_db_session)],
+) -> Optional[models.User]:
+    """Get the current authenticated user from JWT token.
+
+    Returns None if auth is disabled or no token provided.
+    Raises HTTPException if token is invalid.
+    """
+    if not is_auth_enabled():
+        return None
+
+    if token is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+        username: str = payload.get("sub")
+        if username is None:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid token",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+    except JWTError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    user = await get_user_by_username(db, username)
+    if user is None or not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User not found or inactive",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    return user
+
+
+def require_role(minimum_role: Role):
+    """Dependency factory that requires a minimum role level.
+
+    Usage:
+        @router.post("/spool", dependencies=[Depends(require_role(Role.EDITOR))])
+        async def create_spool(...):
+            ...
+    """
+
+    async def role_checker(
+        current_user: Annotated[Optional[models.User], Depends(get_current_user)],
+    ) -> Optional[models.User]:
+        # If auth is disabled, allow all operations
+        if not is_auth_enabled():
+            return None
+
+        if current_user is None:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Not authenticated",
+            )
+
+        user_role = Role(current_user.role)
+        if ROLE_HIERARCHY[user_role] < ROLE_HIERARCHY[minimum_role]:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Requires {minimum_role.value} role or higher",
+            )
+
+        return current_user
+
+    return role_checker
+
+
+# Common dependencies for different permission levels
+RequireViewer = Depends(require_role(Role.VIEWER))
+RequireOperator = Depends(require_role(Role.OPERATOR))
+RequireEditor = Depends(require_role(Role.EDITOR))
+RequireAdmin = Depends(require_role(Role.ADMIN))

spoolman/database/models.py

@@ -163,3 +163,20 @@ class SpoolField(Base):
     spool: Mapped["Spool"] = relationship(back_populates="extra")
     key: Mapped[str] = mapped_column(String(64), primary_key=True, index=True)
     value: Mapped[str] = mapped_column(Text())
+
+
+class User(Base):
+    """User account for authentication."""
+
+    __tablename__ = "user"
+
+    id: Mapped[int] = mapped_column(primary_key=True, index=True)
+    username: Mapped[str] = mapped_column(String(64), unique=True, index=True)
+    hashed_password: Mapped[str] = mapped_column(String(128))
+    role: Mapped[str] = mapped_column(
+        String(16),
+        default="viewer",
+        comment="Role: 'admin', 'editor', 'operator', 'viewer'.",
+    )
+    is_active: Mapped[bool] = mapped_column(default=True)
+    created_at: Mapped[datetime] = mapped_column()