= {
+ admin: "red",
+ editor: "blue",
+ operator: "green",
+ viewer: "default",
+ };
+
+ // If auth is not enabled, show message
+ if (!authStatus?.enabled) {
+ return (
+
+
+
{t("settings.users.auth_disabled")}
+ {t("settings.users.auth_disabled_hint")}
+
+ );
+ }
+
+ // If user is not admin, show access denied
+ if (!hasRole(currentUser, "admin")) {
+ return (
+
+
+
{t("settings.users.admin_required")}
+ {t("settings.users.admin_required_hint")}
+
+ );
+ }
+
+ return (
+ <>
+
+
+ {t("settings.users.title")}
+
+ } onClick={openCreateModal}>
+ {t("settings.users.add")}
+
+
+
+
+ dataSource={users}
+ rowKey="id"
+ loading={loading}
+ pagination={false}
+ columns={[
+ {
+ title: t("settings.users.username"),
+ dataIndex: "username",
+ key: "username",
+ render: (username: string, record: User) => (
+
+
+ {username}
+ {record.id === currentUser?.id && {t("settings.users.you")}}
+
+ ),
+ },
+ {
+ title: t("settings.users.role"),
+ dataIndex: "role",
+ key: "role",
+ render: (role: string) => {role.toUpperCase()},
+ },
+ {
+ title: t("settings.users.status"),
+ dataIndex: "is_active",
+ key: "is_active",
+ render: (isActive: boolean) => (
+ {isActive ? t("settings.users.active") : t("settings.users.inactive")}
+ ),
+ },
+ {
+ title: t("settings.users.actions"),
+ key: "actions",
+ width: 120,
+ render: (_: unknown, record: User) => (
+
+ } onClick={() => openEditModal(record)} />
+ handleDelete(record.id)}
+ disabled={record.id === currentUser?.id}
+ >
+ } disabled={record.id === currentUser?.id} />
+
+
+ ),
+ },
+ ]}
+ />
+
+ {
+ setModalOpen(false);
+ setEditingUser(null);
+ form.resetFields();
+ }}
+ onOk={() => form.submit()}
+ okText={editingUser ? t("buttons.save") : t("buttons.create")}
+ >
+
+ form={form}
+ layout="vertical"
+ onFinish={editingUser ? handleUpdate : handleCreate}
+ >
+
+
+
+
+
+
+
+
+
+
+
+
+ {currentUser && (
+
+
+
+ )}
+
+ );
+};
+
+export default UserSettings;
diff --git a/client/src/utils/axiosAuth.ts b/client/src/utils/axiosAuth.ts
new file mode 100644
index 0000000..b7681ba
--- /dev/null
+++ b/client/src/utils/axiosAuth.ts
@@ -0,0 +1,34 @@
+import { axiosInstance } from "@refinedev/simple-rest";
+
+const TOKEN_KEY = "spoolman_auth_token";
+
+/**
+ * Setup axios interceptor to add auth token to requests.
+ * Should be called once at app initialization.
+ */
+export function setupAxiosAuth() {
+ axiosInstance.interceptors.request.use(
+ (config) => {
+ const token = localStorage.getItem(TOKEN_KEY);
+ if (token) {
+ config.headers.Authorization = `Bearer ${token}`;
+ }
+ return config;
+ },
+ (error) => Promise.reject(error)
+ );
+
+ // Handle 401 responses by clearing token
+ axiosInstance.interceptors.response.use(
+ (response) => response,
+ (error) => {
+ if (error.response?.status === 401) {
+ // Clear invalid token
+ localStorage.removeItem(TOKEN_KEY);
+ // Optionally redirect to login
+ // window.location.href = "/login";
+ }
+ return Promise.reject(error);
+ }
+ );
+}
diff --git a/migrations/versions/2025_01_16_0100-d4e5f6g7h8i9_add_user_auth.py b/migrations/versions/2025_01_16_0100-d4e5f6g7h8i9_add_user_auth.py
new file mode 100644
index 0000000..e275ae5
--- /dev/null
+++ b/migrations/versions/2025_01_16_0100-d4e5f6g7h8i9_add_user_auth.py
@@ -0,0 +1,42 @@
+"""Add user authentication table.
+
+Revision ID: d4e5f6g7h8i9
+Revises: c3d4e5f6g7h8
+Create Date: 2025-01-16 01:00:00.000000
+
+"""
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "d4e5f6g7h8i9"
+down_revision = "c3d4e5f6g7h8"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+ op.create_table(
+ "user",
+ sa.Column("id", sa.Integer(), nullable=False),
+ sa.Column("username", sa.String(length=64), nullable=False),
+ sa.Column("hashed_password", sa.String(length=128), nullable=False),
+ sa.Column(
+ "role",
+ sa.String(length=16),
+ nullable=False,
+ server_default="viewer",
+ comment="Role: 'admin', 'editor', 'operator', 'viewer'.",
+ ),
+ sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.text("1")),
+ sa.Column("created_at", sa.DateTime(), nullable=False),
+ sa.PrimaryKeyConstraint("id"),
+ )
+ op.create_index(op.f("ix_user_id"), "user", ["id"], unique=False)
+ op.create_index(op.f("ix_user_username"), "user", ["username"], unique=True)
+
+
+def downgrade() -> None:
+ op.drop_index(op.f("ix_user_username"), table_name="user")
+ op.drop_index(op.f("ix_user_id"), table_name="user")
+ op.drop_table("user")
diff --git a/pyproject.toml b/pyproject.toml
index d66ac7e..37c504f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -26,6 +26,8 @@ dependencies = [
"httpx~=0.28",
"hishel~=0.1",
"python-multipart~=0.0",
+ "passlib[bcrypt]~=1.7",
+ "python-jose[cryptography]~=3.3",
]
requires-python = ">=3.9,<3.13"
diff --git a/spoolman/api/v1/auth.py b/spoolman/api/v1/auth.py
new file mode 100644
index 0000000..f4b76b9
--- /dev/null
+++ b/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"}
diff --git a/spoolman/api/v1/models.py b/spoolman/api/v1/models.py
index 49a32dc..f651f34 100644
--- a/spoolman/api/v1/models.py
+++ b/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):
diff --git a/spoolman/api/v1/router.py b/spoolman/api/v1/router.py
index e05a0ae..0d634c8 100644
--- a/spoolman/api/v1/router.py
+++ b/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)
diff --git a/spoolman/auth.py b/spoolman/auth.py
new file mode 100644
index 0000000..04327d4
--- /dev/null
+++ b/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))
diff --git a/spoolman/database/models.py b/spoolman/database/models.py
index c450072..9574e09 100644
--- a/spoolman/database/models.py
+++ b/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()