DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""Auth router — login, logout, status, registration, profile, and user-management endpoints."""
from contextvars import Token as _CtxToken
import csv
from datetime import datetime, timedelta, timezone
import io
import ipaddress
import logging
import os
import re
import secrets
import time
from fastapi import (
APIRouter,
Cookie,
Depends,
File,
Header,
HTTPException,
Request,
Response,
UploadFile,
WebSocket,
status,
)
from fastapi.responses import FileResponse, HTMLResponse
from pydantic import BaseModel, Field, ValidationError, field_validator
from deeptutor.services.config import load_auth_settings
# SameSite=None lets the cookie work when the browser accesses the frontend via
# 127.0.0.1 and the backend via localhost (different origins on the same machine).
# Browsers require Secure=True for SameSite=None, but that needs HTTPS — so in
# local dev we fall back to SameSite=Lax and tell users to use localhost:// URLs.
_SECURE = bool(load_auth_settings()["cookie_secure"])
_SAMESITE = "none" if _SECURE else "lax"
from deeptutor.multi_user.audit import log_admin_action, log_usage
from deeptutor.multi_user.context import (
reset_current_user,
set_current_user,
user_from_token_payload,
)
from deeptutor.multi_user.device_credentials import (
heartbeat_device_credential,
issue_device_credential,
list_device_credentials,
revoke_device_credential,
)
from deeptutor.multi_user.identity import get_user_by_id
from deeptutor.multi_user.learning_access import learning_policy_for_user
from deeptutor.multi_user.models import AccountPreset
from deeptutor.multi_user.paths import local_admin_user
from deeptutor.multi_user.session_handoff import (
CODE_LIFETIME_SECONDS,
TICKET_LIFETIME_SECONDS,
HandoffError,
HandoffRateLimited,
HandoffRejected,
canonical_host,
decrypt_ticket_payload,
encrypt_ticket_payload,
get_session_handoff_store,
hash_secret,
is_loopback_host,
public_origin,
)
from deeptutor.services.auth import (
AUTH_ENABLED,
POCKETBASE_ENABLED,
TOKEN_EXPIRE_HOURS,
TokenPayload,
add_user,
authenticate,
authenticate_device,
authenticate_pb,
create_token,
decode_token,
delete_user,
get_user_info,
is_first_user,
list_users,
register_pb,
set_avatar,
set_learner_profile,
set_role,
)
from deeptutor.services.auth import (
get_learner_profile as load_learner_profile,
)
from deeptutor.services.codex_auth.contracts import CodexAuthError
from deeptutor.services.codex_auth.service import deliver_codex_oauth_callback
logger = logging.getLogger(__name__)
router = APIRouter()
_COOKIE_NAME = "dt_token"
AUTH_COOKIE_NAME = _COOKIE_NAME
_COOKIE_MAX_AGE = TOKEN_EXPIRE_HOURS * 3600
_USER_IMPORT_MAX_BYTES = 2 * 1024 * 1024
_USER_IMPORT_MAX_ROWS = 500
_USER_BATCH_MAX_ROWS = 500
_FRONTEND_HOST_HEADER = "x-deeptutor-frontend-host"
_AUTH_RUNTIME_SETTINGS = load_auth_settings()
PRIVATE_LOGIN_HOSTS = frozenset(
str(host).lower().rstrip(".") for host in _AUTH_RUNTIME_SETTINGS.get("private_login_hosts", [])
)
# Only a frontend proxy on an explicitly trusted peer may assert the browser
# host. Never derive this identity from Host or X-Forwarded-* on a direct API call.
# The frontend's incoming Host is meaningful only when its public ingress
# rejects forged private hosts and direct access to its raw listener.
def _trusted_proxy_ips() -> frozenset[str]:
raw = os.environ.get("AUTH_TRUSTED_FRONTEND_PROXY_IPS", "127.0.0.1,::1")
trusted: set[str] = set()
for item in raw.split(","):
try:
trusted.add(str(ipaddress.ip_address(item.strip())))
except ValueError:
continue
return frozenset(trusted)
TRUSTED_FRONTEND_PROXY_IPS = _trusted_proxy_ips()
def _cookie_attrs() -> dict:
"""Attribute set shared by ``login``'s ``set_cookie`` and ``logout``'s
``delete_cookie``.
The deletion ``Set-Cookie`` must carry the same attributes as the one
that created the cookie — ``delete_cookie`` defaults ``secure=False``,
which browsers reject when paired with ``SameSite=None``, silently
keeping the old cookie. See #623. Reads the module globals at call time
so tests can monkeypatch ``_SECURE``/``_SAMESITE``.
"""
return {
"key": _COOKIE_NAME,
"httponly": True,
"samesite": _SAMESITE,
"secure": _SECURE,
}
def _request_frontend_host(request: Request) -> str:
peer = request.client.host if request.client else ""
try:
peer_ip = str(ipaddress.ip_address(peer))
except ValueError:
return ""
if peer_ip not in TRUSTED_FRONTEND_PROXY_IPS:
return ""
raw = request.headers.get(_FRONTEND_HOST_HEADER, "")
try:
return canonical_host(raw)
except HandoffError:
return ""
def _require_private_frontend(request: Request) -> None:
"""Restrict credential endpoints only when private hosts are configured."""
if not PRIVATE_LOGIN_HOSTS:
return
host = _request_frontend_host(request)
if is_loopback_host(host) or host in PRIVATE_LOGIN_HOSTS:
return
logger.warning(
"Credential endpoint refused for non-private frontend host policy",
)
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Sign-in is only available from a private DeepTutor origin",
)
def _no_store(response: Response) -> None:
response.headers["Cache-Control"] = "no-store"
# ---------------------------------------------------------------------------
# Schemas
# ---------------------------------------------------------------------------
class LoginRequest(BaseModel):
"""Payload for the POST /login endpoint."""
username: str
password: str
class DeviceLoginRequest(BaseModel):
"""Payload for the built-in device-credential login endpoint."""
pairing_code: str = Field(min_length=8, max_length=128)
pin: str = Field(min_length=6, max_length=6)
class DeviceCredentialCreateRequest(BaseModel):
"""Admin payload for issuing a local ordinary-user device credential."""
user_id: str = Field(min_length=1, max_length=64)
device_name: str = Field(min_length=1, max_length=80)
expires_in_days: int = Field(ge=1, le=365)
daily_limit_minutes: int = Field(ge=5, le=1440)
class RegisterRequest(BaseModel):
"""Payload for the POST /register endpoint."""
username: str
password: str
@field_validator("username")
@classmethod
def username_valid(cls, v: str) -> str:
import re
v = v.strip()
if not v:
raise ValueError("Email cannot be empty")
# Accept standard email addresses (used by PocketBase mode) or plain
# usernames (used by the built-in SQLite/JSON auth mode).
email_re = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
plain_re = re.compile(r"^[A-Za-z0-9_\-.]{3,64}$")
if not email_re.match(v) and not plain_re.match(v):
raise ValueError("Enter a valid email address")
return v
@field_validator("password")
@classmethod
def password_valid(cls, v: str) -> str:
if len(v) < 8:
raise ValueError("Password must be at least 8 characters")
return v
class SessionHandoffCreateRequest(BaseModel):
"""Private request that starts a one-time public handoff."""
public_origin: str = Field(min_length=8, max_length=2048)
class SessionHandoffExchangeRequest(BaseModel):
"""Public request that trades a pairing code for a JWE ticket."""
code: str = Field(min_length=16, max_length=256)
class SessionHandoffCompleteRequest(BaseModel):
"""Public request that trades a JWE ticket for the normal cookie."""
ticket: str = Field(min_length=32, max_length=8192)
class SetRoleRequest(BaseModel):
"""Payload for the PUT /users/{username}/role endpoint."""
role: str
@field_validator("role")
@classmethod
def role_valid(cls, v: str) -> str:
# Validate against the same whitelist the identity store enforces so
# the API layer and the storage layer share a single source of truth;
# a hardcoded subset here would 422 roles the store itself accepts.
from deeptutor.multi_user.models import VALID_ROLES
if v not in VALID_ROLES:
raise ValueError(f"Role must be one of {sorted(VALID_ROLES)}")
return v
class AdminCreateUserRequest(RegisterRequest):
"""Admin user-creation payload.
A preset configures an ordinary account; it never becomes a third role.
"""
preset: AccountPreset = "standard"
class AdminBatchDeleteRequest(BaseModel):
"""Usernames for an admin-initiated batch deletion."""
usernames: list[str] = Field(min_length=1, max_length=_USER_BATCH_MAX_ROWS)
@field_validator("usernames")
@classmethod
def usernames_valid(cls, value: list[str]) -> list[str]:
usernames: list[str] = []
for raw_username in value:
username = raw_username.strip()
if not username:
raise ValueError("Usernames cannot be empty")
if username not in usernames:
usernames.append(username)
if not usernames:
raise ValueError("At least one username is required")
return usernames
class AuthStatusResponse(BaseModel):
"""Response body for the GET /status endpoint."""
enabled: bool
authenticated: bool
user_id: str | None = None
username: str | None = None
role: str | None = None
is_admin: bool = False
avatar: str = ""
preset: AccountPreset | None = None
learning_policy: dict | None = None
class UserInfo(BaseModel):
"""Single user record returned by the GET /users and /profile endpoints."""
id: str = ""
username: str
role: str
created_at: str
disabled: bool = False
avatar: str = ""
preset: AccountPreset = "standard"
class LearnerProfileRequest(BaseModel):
age: int | None = Field(default=None, ge=3, le=120)
grade_level: str | None = Field(default=None, max_length=80)
curriculum: str | None = Field(default=None, max_length=80)
language: str | None = Field(default=None, max_length=80)
reading_level: str | None = Field(default=None, max_length=80)
explanation_style: str | None = Field(default=None, max_length=80)
# Markers settable through PUT /profile. Image markers ("img:<version>") are
# managed exclusively by the upload endpoint so users cannot point their
# avatar at a file that was never validated.
_ICON_MARKER_RE = re.compile(r"^icon:[a-z0-9-]{1,32}:[a-z0-9-]{1,32}$")
# User ids are generated as "u_<uuid hex>" (plus the "local-admin" /
# "env-admin" sentinels); reject anything else before it reaches the
# filesystem layer.
_USER_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
class UpdateProfileRequest(BaseModel):
"""Payload for the PUT /profile endpoint."""
avatar: str
@field_validator("avatar")
@classmethod
def avatar_valid(cls, v: str) -> str:
v = v.strip()
if v and not _ICON_MARKER_RE.match(v):
raise ValueError("Avatar must be empty or 'icon:<name>:<color>'")
return v
# ---------------------------------------------------------------------------
# Shared helper — extract token from cookie or Bearer header
# ---------------------------------------------------------------------------
def _bearer_token_from_header(authorization: str | None) -> str | None:
"""Parse ``Authorization: Bearer <token>`` without using ``HTTPBearer``.
``HTTPBearer`` is a class-based dependency whose ``__call__`` is annotated
``request: Request``. FastAPI doesn't inject a Request into WebSocket
dependency resolution, which makes ``HTTPBearer`` raise ``TypeError`` the
moment a router with this dep mounts a WS endpoint. Doing the parse by
hand keeps ``require_auth`` HTTP/WS-symmetric.
"""
if not authorization:
return None
parts = authorization.split(None, 1)
if len(parts) == 2 and parts[0].lower() == "bearer":
token = parts[1].strip()
return token or None
return None
def _extract_token(authorization: str | None, dt_token: str | None) -> str | None:
return _bearer_token_from_header(authorization) or dt_token
# ---------------------------------------------------------------------------
# Dependencies — reusable auth guards for other routers
# ---------------------------------------------------------------------------
def _install_current_user(payload: TokenPayload | None) -> _CtxToken:
"""Install the request-local current-user ContextVar from an auth result.
Single point of truth for ``payload → CurrentUser`` so HTTP and WebSocket
entry points produce identical user objects. ``payload is None`` means
"no JWT was required" (AUTH_ENABLED=false) and resolves to the local
admin user; a non-None payload resolves through ``user_from_token_payload``.
Returns the ContextVar reset token. HTTP callers ignore it (the request
ends with the task, so the var is GC'd with the task context). WebSocket
callers keep it and call ``reset_current_user`` in their ``finally`` block,
because a WS connection outlives the dependency-resolution task.
⚠ Invariant: every authenticated entry point MUST call this before the
handler runs. Skipping it leaves ``get_current_path_service()`` falling
back to the admin workspace — the silent-routing root cause of #481.
"""
user = local_admin_user() if payload is None else user_from_token_payload(payload)
return set_current_user(user)
async def require_auth(
authorization: str | None = Header(default=None, alias="Authorization"),
dt_token: str | None = Cookie(default=None, alias=_COOKIE_NAME),
request: Request = None,
) -> TokenPayload | None:
"""
FastAPI dependency that enforces authentication when AUTH_ENABLED=true.
Accepts the JWT from either:
- Authorization: Bearer <token> header
- dt_token cookie
``Header`` and ``Cookie`` are kept here in place of ``HTTPBearer`` so the
function stays usable from WebSocket call sites that don't go through
FastAPI's standard HTTP request lifecycle.
Returns the authenticated TokenPayload, or None if auth is disabled.
Raises HTTP 401 if auth is enabled but the token is missing or invalid.
Declared ``async def`` so the ``set_current_user`` call runs in the same
asyncio context as the endpoint. A sync dependency is dispatched via
``anyio.to_thread.run_sync``, which executes the function in a worker
thread under a *copy* of the request context; any ``ContextVar.set``
inside that thread is discarded when the thread returns, leaving the
endpoint to read the unset default. That regression was the root cause
of #481.
"""
if not AUTH_ENABLED:
_install_current_user(None)
_install_request_workspace(request)
return None
token = _extract_token(authorization, dt_token)
if not token:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Not authenticated",
headers={"WWW-Authenticate": "Bearer"},
)
payload = decode_token(token)
if not payload:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid or expired token",
headers={"WWW-Authenticate": "Bearer"},
)
_install_current_user(payload)
_install_request_workspace(request)
return payload
def _install_request_workspace(request) -> None:
from deeptutor.services.workspace.context import install_workspace_scope
from deeptutor.services.workspace.models import WorkspaceError
headers = getattr(request, "headers", {})
params = getattr(request, "query_params", {})
header = headers.get("x-deeptutor-workspace")
query = params.get("dt_workspace")
if header is not None and query is not None and header != query:
raise HTTPException(status_code=400, detail="Conflicting workspace scopes.")
try:
path = getattr(getattr(request, "url", None), "path", "")
from deeptutor.services.workspace.context import resolve_workspace_scope
from deeptutor.services.workspace.knowledge import library_request, library_viewer
library_request.set(
path.startswith(("/api/knowledge-bases", "/ws/knowledge-bases"))
and params.get("resource_library") == "true"
)
library_viewer.set(
resolve_workspace_scope(header if header is not None else query).workspace_id
if library_request.get() and (header is not None or query is not None)
else None
)
from deeptutor.services.skill.runtime import library_workspace
skill_workspace = (
params.get("skill_workspace", "") if path.startswith("/api/skills") else ""
)
library_workspace.set(skill_workspace)
catalog_management = library_request.get() or path.startswith(
("/api/skills", "/api/space/mcp")
)
management = path.startswith(
("/api/settings", "/api/auth", "/api/multi-user", "/api/task-board", "/api/calendar")
)
selected = install_workspace_scope(
None if management or catalog_management else header if header is not None else query
)
if skill_workspace:
from deeptutor.services.workspace import get_content_workspace_service
service = get_content_workspace_service()
service.validate_chat_binding(
skill_workspace,
existing=getattr(request, "method", "GET") in {"GET", "HEAD", "OPTIONS"},
)
if (
not management
and selected.archived
and getattr(request, "method", "GET") not in {"GET", "HEAD", "OPTIONS"}
):
raise WorkspaceError("Restore this workspace before changing its data.")
# Management/migration requests acquire their own exclusive lease.
task_board_request = path == "/api/task-board" or path.startswith("/api/task-board/")
if getattr(request, "method", None) is not None and (
not management
or (task_board_request and path != "/api/task-board/events")
or (path.startswith("/api/calendar/") and path != "/api/calendar/stream")
):
from deeptutor.services.workspace.activity import acquire_activity
state = getattr(request, "state", None)
if state is not None and getattr(state, "workspace_activity", None) is None:
state.workspace_activity = acquire_activity()
except WorkspaceError as exc:
raise HTTPException(status_code=404, detail=str(exc)) from exc
class _WsAuthFailed:
"""Sentinel: ws_require_auth failed and closed the WebSocket."""
ws_auth_failed: _WsAuthFailed = _WsAuthFailed()
async def ws_require_auth(ws: WebSocket) -> _CtxToken | _WsAuthFailed:
"""Authenticate a WebSocket connection and set the user ContextVar.
Must be called **before** ``ws.accept()`` so the server can reject
unauthenticated upgrades cleanly.
Returns a ContextVar reset token on success, or ``ws_auth_failed``
on failure (the WebSocket is already closed — the caller should
``return`` immediately).
Usage::
user_token = await ws_require_auth(ws)
if user_token is ws_auth_failed:
return
await ws.accept()
try:
...
finally:
reset_current_user(user_token)
"""
payload = None
if AUTH_ENABLED:
token = ws.query_params.get("token") or ws.cookies.get(_COOKIE_NAME)
payload = decode_token(token) if token else None
if not payload:
await ws.close(code=4001)
return ws_auth_failed
user_token = _install_current_user(payload)
try:
_install_request_workspace(ws)
except HTTPException:
reset_current_user(user_token)
await ws.close(code=4004)
return ws_auth_failed
return user_token
async def require_admin(
payload: TokenPayload | None = Depends(require_auth),
) -> TokenPayload:
"""
FastAPI dependency that requires the caller to be an admin.
Raises HTTP 403 if the authenticated user is not an admin.
When AUTH_ENABLED=false, all requests are treated as admin.
``async def`` mirrors ``require_auth`` so the dependency chain stays on
the event loop and the user ContextVar set by ``require_auth`` is visible
to the endpoint.
"""
if not AUTH_ENABLED:
return _local_admin_token_payload()
if payload is None or payload.role != "admin":
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Admin access required",
)
return payload
_LEARNER_KB_READ_ROUTES = frozenset(
{
"/api/knowledge-bases",
"/api/knowledge-bases/list",
"/api/knowledge-bases/{kb_name}",
"/api/knowledge-bases/{kb_name}/files",
"/api/knowledge-bases/{kb_name}/files/{filename:path}",
"/api/knowledge-bases/{kb_name}/file-preview-text/{filename:path}",
"/api/knowledge-bases/{kb_name}/visual-assets/{asset_id}",
"/api/knowledge-bases/{kb_name}/indexing-run",
"/api/knowledge-bases/{kb_name}/indexing-readiness",
"/api/knowledge-bases/{kb_name}/progress",
}
)
_PERSONAL_PAGE_ROUTES = frozenset(
{
("GET", "/api/settings/page-customization"),
("PUT", "/api/settings/page-customization/chat"),
("PUT", "/api/settings/page-customization/learning"),
}
)
_LEARNER_SETTINGS_WRITE_ROUTES = frozenset(
{
# UI preferences resolve through the per-user path service into the
# caller's OWN workspace (interface.json) — saving theme/language is
# safe for learning accounts.
("PUT", "/api/settings/ui"),
*_PERSONAL_PAGE_ROUTES,
# Per-user settings draft document. Applying a draft to the runtime
# catalog stays admin-gated in the endpoint itself.
("PUT", "/api/settings/draft"),
("DELETE", "/api/settings/draft"),
# Workspace self-management: the caller's own registrations inside
# their own scope directory. Data migration/export/root-migration
# routes under the same prefix stay denied — they move data across
# scopes and carry no internal admin gate.
("PUT", "/api/settings/workspace"),
("POST", "/api/settings/workspace/validate"),
("POST", "/api/settings/workspace/registrations"),
("PATCH", "/api/settings/workspace/registrations/{workspace_id}"),
}
)
def _learning_surface_for_path(
path: str, method: str = "GET", *, route_path: str | None = None
) -> str:
normalized = "/" + str(path or "").lstrip("/")
for root, surface in (
("/api/reading", "reading"),
("/api/courses", "reading"),
("/api/dashboard/learning-library/materials", "reading"),
("/api/dashboard/learning-library/reading", "reading"),
("/api/books", "books"),
("/api/dashboard/learning-library/books", "books"),
("/api/dashboard/learning-library/mastery", "chat"),
("/api/chat", "chat"),
("/api/question", "chat"),
("/api/question-notebook", "chat"),
("/api/sessions", "chat"),
# Task cards are private to the learner's current content workspace.
("/api/task-board", "chat"),
("/api/calendar", "chat"),
# Mastery Path progress/topics are the learner's own per-user data;
# the router already scopes every record to the current account, so
# all methods (including progress PATCH/POST) belong to "chat".
("/api/mastery-paths", "chat"),
):
if normalized == root or normalized.startswith(f"{root}/"):
return surface
# Match the resolved route template, not just the URL prefix: this keeps
# admin diagnostics and engine configuration GETs out of the learner shell.
if (
method.upper() == "GET"
and (normalized == "/api/knowledge-bases" or normalized.startswith("/api/knowledge-bases/"))
and route_path in _LEARNER_KB_READ_ROUTES
):
return "reading"
# Learner-safe settings/workspace writes, matched on the resolved route
# template like the KB reads above: the same URL prefixes also host
# admin-grade operations (catalog apply, data migration), so a plain
# prefix match would open too much.
if route_path and (method.upper(), route_path) in _LEARNER_SETTINGS_WRITE_ROUTES:
return "chat"
# Choosing the model for a chat turn is part of chat. The handler is
# already grant-filtered. Match this exact path only: a prefix of
# /api/settings would also open catalog writes on the same router (#1222).
if method.upper() == "GET" and normalized == "/api/settings/llm-options":
return "chat"
return ""
def _resolved_route_path(request: Request) -> str | None:
"""Keep include-time prefixes across FastAPI's flat and lazy routers."""
# Lazy router inclusion retains the original route in scope["route"].
# Its path omits include_router prefixes; the effective context owns the
# full matched template. Direct routes and older releases use the route.
fastapi_scope = request.scope.get("fastapi")
if isinstance(fastapi_scope, dict):
context = fastapi_scope.get("effective_route_context")
path = getattr(context, "path", None)
if isinstance(path, str):
return path
path = getattr(request.scope.get("route"), "path", None)
return path if isinstance(path, str) else None
async def require_learning_surface(
request: Request,
_: TokenPayload | None = Depends(require_auth),
) -> None:
"""Second-stage default-deny guard for configured learning accounts."""
from deeptutor.multi_user.learning_access import (
assert_learning_surface,
learning_surface_allowed,
)
route_path = _resolved_route_path(request)
# Personal presentation does not grant a learning surface. Any authenticated
# learner may customize these two pages, including reading-only accounts.
if (request.method, route_path) in _PERSONAL_PAGE_ROUTES:
return
# The landing page combines independent learning surfaces (#1987). Admit
# any granted surface; the handler filters its readers with the same policy.
if (
request.method == "GET"
and request.url.path == "/api/dashboard/learning-index"
and route_path == "/api/dashboard/learning-index"
and any(learning_surface_allowed(surface) for surface in ("books", "chat", "reading"))
):
return
# This aggregate filters each source by the current policy itself. Exact
# GET only: it must never open the rest of the dashboard to learners.
if request.method == "GET" and request.url.path == "/api/dashboard/learning-index":
return
try:
assert_learning_surface(
_learning_surface_for_path(
request.url.path,
request.method,
route_path=route_path,
)
)
except PermissionError as exc:
raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
def _local_admin_token_payload() -> TokenPayload:
"""Synthetic admin payload used when AUTH_ENABLED=false.
Mirrors the local admin identity (LOCAL_ADMIN_USERNAME / LOCAL_ADMIN_ID)
so audit logs and self-reference checks behave the same as in multi-user
mode. Values are kept aligned with ``local_admin_user()`` in
``deeptutor/multi_user/paths.py``.
"""
from deeptutor.multi_user.models import LOCAL_ADMIN_ID, LOCAL_ADMIN_USERNAME
return TokenPayload(
username=LOCAL_ADMIN_USERNAME,
role="admin",
user_id=LOCAL_ADMIN_ID,
)
# ---------------------------------------------------------------------------
# Public endpoints (no auth required)
# ---------------------------------------------------------------------------
@router.get("/openai-codex/callback")
async def receive_codex_oauth_callback(
request: Request,
code: str | None = None,
state: str | None = None,
error: str | None = None,
) -> HTMLResponse:
headers = {"Cache-Control": "no-store"}
try:
callback_state = state if len(request.query_params.getlist("state")) == 1 else None
await deliver_codex_oauth_callback(code, callback_state, error)
except CodexAuthError as exc:
return HTMLResponse(
(
"<!doctype html><title>DeepTutor Codex</title>"
"<p>Authentication could not be received. Return to DeepTutor and try again.</p>"
),
status_code=exc.http_status,
headers=headers,
)
return HTMLResponse(
(
"<!doctype html><title>DeepTutor Codex</title>"
"<p>Authentication received. You can return to DeepTutor.</p>"
),
headers=headers,
)
@router.get("/status", response_model=AuthStatusResponse)
async def auth_status(
authorization: str | None = Header(default=None, alias="Authorization"),
dt_token: str | None = Cookie(default=None, alias=_COOKIE_NAME),
) -> AuthStatusResponse:
"""Return whether auth is enabled and whether the current request is authenticated."""
if not AUTH_ENABLED:
return AuthStatusResponse(
enabled=False,
authenticated=True,
user_id="local-admin",
username="local",
role="admin",
is_admin=True,
preset="standard",
)
token = _extract_token(authorization, dt_token)
payload = decode_token(token) if token else None
avatar = ""
preset: AccountPreset | None = None
learning_policy = None
if payload is not None:
info = get_user_info(payload.username)
if info:
avatar = str(info.get("avatar") or "")
raw_preset = str(info.get("preset") or "standard")
if raw_preset == "learner":
preset = "learner"
elif raw_preset == "custom":
preset = "custom"
else:
preset = "standard"
learning_policy = learning_policy_for_user(
payload.user_id,
is_admin=payload.role == "admin",
)
# Guardians may attach a policy to a standard or custom account. That
# policy, not the stored label, is what the runtime must enforce and
# what clients need to render the scoped experience.
if learning_policy is not None and preset != "learner":
preset = "learner"
return AuthStatusResponse(
enabled=True,
authenticated=payload is not None,
user_id=payload.user_id if payload else None,
username=payload.username if payload else None,
role=payload.role if payload else None,
is_admin=payload.role == "admin" if payload else False,
avatar=avatar,
preset=preset,
learning_policy=learning_policy,
)
@router.post("/login")
async def login(body: LoginRequest, request: Request, response: Response) -> dict:
"""Validate credentials and set a JWT cookie."""
if not AUTH_ENABLED:
return {"ok": True, "message": "Auth is disabled — no login required."}
_require_private_frontend(request)
_no_store(response)
if POCKETBASE_ENABLED:
# PocketBase mode: email = username field for backwards-compat with the
# existing LoginRequest schema; users can pass their email as "username".
pb_result = authenticate_pb(body.username, body.password)
if not pb_result:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Incorrect email or password",
)
payload, pb_token = pb_result
response.set_cookie(value=pb_token, max_age=_COOKIE_MAX_AGE, **_cookie_attrs())
logger.info(f"User '{payload.username}' logged in via PocketBase (role={payload.role!r})")
return {
"ok": True,
"user_id": payload.user_id,
"username": payload.username,
"role": payload.role,
"is_admin": payload.role == "admin",
}
# Standard JWT + bcrypt mode
result = authenticate(body.username, body.password)
if not result:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Incorrect username or password",
)
token = create_token(result.username, result.role, result.user_id)
response.set_cookie(value=token, max_age=_COOKIE_MAX_AGE, **_cookie_attrs())
logger.info(f"User '{result.username}' logged in (role={result.role!r})")
return {
"ok": True,
"user_id": result.user_id,
"username": result.username,
"role": result.role,
"is_admin": result.role == "admin",
}
def _require_builtin_device_auth() -> None:
if not AUTH_ENABLED:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Device credentials require built-in authentication.",
)
if POCKETBASE_ENABLED:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Device credentials are not supported in PocketBase mode.",
)
@router.post("/device-login")
async def device_login(body: DeviceLoginRequest, response: Response) -> dict:
"""Exchange a device pairing code and PIN for the account's normal cookie."""
_require_builtin_device_auth()
payload = authenticate_device(body.pairing_code, body.pin)
if payload is None:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Incorrect device credentials",
)
token = create_token(
payload.username,
payload.role,
payload.user_id,
device_credential_id=payload.device_credential_id,
device_session_nonce=payload.device_session_nonce,
)
response.set_cookie(value=token, max_age=_COOKIE_MAX_AGE, **_cookie_attrs())
logger.info(f"User '{payload.username}' logged in with a device credential")
return {
"ok": True,
"user_id": payload.user_id,
"username": payload.username,
"role": payload.role,
"is_admin": payload.role == "admin",
"device_credential_id": payload.device_credential_id,
}
@router.post("/session-handoff")
async def create_session_handoff(
body: SessionHandoffCreateRequest,
request: Request,
response: Response,
authorization: str | None = Header(default=None, alias="Authorization"),
dt_token: str | None = Cookie(default=None, alias=_COOKIE_NAME),
payload: TokenPayload | None = Depends(require_auth),
) -> dict:
"""Create a host-bound, one-time pairing code from the private origin."""
_no_store(response)
if not AUTH_ENABLED or payload is None or not PRIVATE_LOGIN_HOSTS:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Session handoff requires authentication and configured private login hosts.",
)
_require_private_frontend(request)
try:
target_origin = public_origin(body.public_origin)
target_host = canonical_host(target_origin.removeprefix("https://"))
now = int(time.time())
ticket_claims: dict[str, object] = {
"nonce": secrets.token_urlsafe(24),
"host": target_host,
# Rotated at code exchange; this initial upper bound cannot expire
# before a valid pairing code is presented.
"exp": now + CODE_LIFETIME_SECONDS + TICKET_LIFETIME_SECONDS,
}
if POCKETBASE_ENABLED:
ticket_claims.update(
{"mode": "pocketbase", "token": _extract_token(authorization, dt_token)}
)
else:
ticket_claims.update(
{
"mode": "builtin",
"username": payload.username,
"role": payload.role,
"user_id": payload.user_id,
"device_credential_id": payload.device_credential_id,
"device_session_nonce": payload.device_session_nonce,
}
)
ticket = encrypt_ticket_payload(ticket_claims)
record = get_session_handoff_store().create(
encrypted_ticket=ticket,
ticket_hash=hash_secret(ticket),
public_host=target_host,
rate_key=payload.user_id or payload.username,
)
except HandoffRateLimited:
raise HTTPException(
status_code=status.HTTP_429_TOO_MANY_REQUESTS,
detail="Too many handoff requests. Try again later.",
)
except HandoffError:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Enter a valid HTTPS public origin",
)
logger.info(
"Created session handoff for user=%s target_host=%s",
payload.username,
target_host,
)
return {
"ok": True,
"code": record.code,
"handoff_url": f"{target_origin}/handoff?code={record.code}",
"expires_at": record.expires_at,
"expires_in": CODE_LIFETIME_SECONDS,
}
@router.post("/session-handoff/exchange")
async def exchange_session_handoff(
body: SessionHandoffExchangeRequest,
request: Request,
response: Response,
) -> dict:
"""Consume a pairing code and return a short-lived ticket in the response body."""
_no_store(response)
host = _request_frontend_host(request)
if not host:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Pairing request has no valid frontend host",
)
try:
ticket = get_session_handoff_store().exchange(
code=body.code,
public_host=host,
)
except HandoffRateLimited:
raise HTTPException(
status_code=status.HTTP_429_TOO_MANY_REQUESTS,
detail="Too many handoff requests. Try again later.",
)
except HandoffError:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Pairing code is invalid, expired, or already used",
)
logger.info("Exchanged session handoff code for host=%s", host)
return {"ok": True, "ticket": ticket}
@router.post("/session-handoff/complete")
async def complete_session_handoff(
body: SessionHandoffCompleteRequest,
request: Request,
response: Response,
) -> dict:
"""Consume a ticket once and issue the normal HttpOnly session cookie."""
_no_store(response)
host = _request_frontend_host(request)
if not host:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Handoff request has no valid frontend host",
)
try:
ticket = get_session_handoff_store().consume_ticket(
ticket=body.ticket,
public_host=host,
)
claims = decrypt_ticket_payload(ticket)
if str(claims.get("host")) != host:
raise HandoffRejected("Invalid handoff ticket")
try:
expires_at = int(claims.get("exp"))
except (TypeError, ValueError):
raise HandoffRejected("Invalid handoff ticket") from None
if expires_at <= int(time.time()):
raise HandoffRejected("Invalid handoff ticket")
mode = str(claims.get("mode"))
if mode == "pocketbase":
token = str(claims.get("token") or "")
if not token or decode_token(token) is None:
raise HandoffRejected("Invalid handoff ticket")
elif mode == "builtin":
token = create_token(
str(claims.get("username") or ""),
str(claims.get("role") or "user"),
str(claims.get("user_id") or ""),
device_credential_id=str(claims.get("device_credential_id") or ""),
device_session_nonce=str(claims.get("device_session_nonce") or ""),
)
else:
raise HandoffRejected("Invalid handoff ticket")
except HandoffRateLimited:
raise HTTPException(
status_code=status.HTTP_429_TOO_MANY_REQUESTS,
detail="Too many handoff requests. Try again later.",
)
except HandoffError:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Handoff ticket is invalid, expired, or already used",
)
response.set_cookie(value=token, max_age=_COOKIE_MAX_AGE, **_cookie_attrs())
logger.info("Completed session handoff for host=%s", host)
return {"ok": True}
@router.post("/device/heartbeat")
async def device_heartbeat(
response: Response,
payload: TokenPayload | None = Depends(require_auth),
) -> dict:
"""Refresh a device lease and account bounded daily usage."""
if not AUTH_ENABLED:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Device credentials require built-in authentication.",
)
if payload is None or not payload.device_credential_id or not payload.device_session_nonce:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="This session does not use a device credential.",
)
try:
device = heartbeat_device_credential(
payload.device_credential_id,
user_id=payload.user_id,
session_nonce=payload.device_session_nonce,
)
except ValueError:
response.delete_cookie(**_cookie_attrs())
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Device session is no longer active",
) from None
return {"ok": not device.pop("limit_reached"), **device}
@router.post("/logout")
async def logout(response: Response) -> dict:
"""Clear the JWT cookie.
Deletion attributes mirror ``login`` structurally via ``_cookie_attrs()``
(see the rationale there and #623).
"""
response.delete_cookie(**_cookie_attrs())
return {"ok": True}
@router.post("/register", status_code=status.HTTP_201_CREATED)
async def register(body: RegisterRequest, request: Request, response: Response) -> dict:
"""
Bootstrap-only registration.
Public endpoint that creates the *first* admin account when the user store
is empty. Once an admin exists, this endpoint is closed; further accounts
must be created by an admin via ``POST /api/auth/users``.
Only available when AUTH_ENABLED=true.
"""
if not AUTH_ENABLED:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Auth is disabled — registration is not available.",
)
_require_private_frontend(request)
_no_store(response)
if POCKETBASE_ENABLED:
# PocketBase deployments are documented as single-user. Keep registration
# closed and require admins to provision users in the PocketBase admin UI.
if not is_first_user():
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Self-registration is closed. Ask an administrator to create your account.",
)
result = register_pb(username=body.username, email=body.username, password=body.password)
if not result:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="Registration failed — username or email may already be taken.",
)
logger.info(f"First user registered via PocketBase: '{body.username}'")
return {
"ok": True,
"user_id": result.get("id", ""),
"username": body.username,
"role": "user",
"is_first_user": True,
"is_admin": False,
}
# Standard mode — only allowed before the first admin exists.
if not is_first_user():
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Self-registration is closed. Ask an administrator to create your account.",
)
existing = {u["username"] for u in list_users()}
if body.username in existing:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="Username already taken",
)
add_user(body.username, body.password)
user_id = ""
role = "user"
for item in list_users():
if item.get("username") == body.username:
user_id = str(item.get("id") or "")
role = str(item.get("role") or "user")
break
logger.info(f"First user (admin) registered: '{body.username}'")
return {
"ok": True,
"user_id": user_id,
"username": body.username,
"role": role,
"is_first_user": True,
"is_admin": role == "admin",
}
@router.get("/is_first_user")
async def check_is_first_user() -> dict:
"""Return whether the user store is empty (used by the register UI)."""
return {"is_first_user": is_first_user() if AUTH_ENABLED else False}
# ---------------------------------------------------------------------------
# Profile endpoints (any authenticated user, self-service)
# ---------------------------------------------------------------------------
_AVATAR_MAX_BYTES = 1 * 1024 * 1024
_AVATAR_MEDIA_TYPES = {"png": "image/png", "jpg": "image/jpeg", "webp": "image/webp"}
def _sniff_image(data: bytes) -> str | None:
"""Detect a supported raster image format from its magic bytes.
The uploaded filename and Content-Type are attacker-controlled, so the
stored extension (and the media type served back) is derived from the
bytes alone. SVG is deliberately unsupported — serving user-supplied SVG
is a stored-XSS vector.
"""
if data[:8] == b"\x89PNG\r\n\x1a\n":
return "png"
if data[:3] == b"\xff\xd8\xff":
return "jpg"
if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
return "webp"
return None
def _require_profile_identity(payload: TokenPayload | None) -> TokenPayload:
"""Shared guard for the self-service profile endpoints."""
if not AUTH_ENABLED or payload is None:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Auth is disabled — profiles are not available.",
)
return payload
@router.get("/profile", response_model=UserInfo)
async def get_profile(
payload: TokenPayload | None = Depends(require_auth),
) -> UserInfo:
"""Return the current user's own account info."""
current = _require_profile_identity(payload)
info = get_user_info(current.username)
if info is None:
# PocketBase-backed identities have no local record; fall back to the
# token claims so the profile page still renders.
return UserInfo(
id=current.user_id,
username=current.username,
role=current.role,
created_at="",
)
return UserInfo(**info)
@router.put("/profile")
async def update_profile(
body: UpdateProfileRequest,
payload: TokenPayload | None = Depends(require_auth),
) -> dict:
"""Update the current user's own avatar marker (icon choice or reset).
Only the validated ``icon:<name>:<color>`` form (or empty string) is
accepted here; ``img:`` markers are owned by the upload endpoint.
"""
current = _require_profile_identity(payload)
if not set_avatar(current.username, body.avatar):
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
# The marker no longer references an uploaded image, so drop the file.
from deeptutor.multi_user.identity import delete_avatar_file
if current.user_id and _USER_ID_RE.match(current.user_id):
delete_avatar_file(current.user_id)
return {"ok": True, "avatar": body.avatar}
@router.put("/profile/avatar")
async def upload_avatar(
file: UploadFile = File(...),
payload: TokenPayload | None = Depends(require_auth),
) -> dict:
"""Upload an avatar image for the current user.
The client is expected to crop/resize before uploading; the server only
enforces a size cap and validates the format by magic bytes. Not available
in PocketBase mode (those identities have no local user record).
"""
current = _require_profile_identity(payload)
if POCKETBASE_ENABLED:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Avatar upload is not available in PocketBase mode.",
)
if not current.user_id or not _USER_ID_RE.match(current.user_id):
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Cannot store an avatar for this account.",
)
info = get_user_info(current.username)
if info is None:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
data = await file.read(_AVATAR_MAX_BYTES + 1)
if len(data) > _AVATAR_MAX_BYTES:
raise HTTPException(
status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
detail="Avatar image is too large (max 1 MB).",
)
ext = _sniff_image(data)
if ext is None:
raise HTTPException(
status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
detail="Avatar must be a PNG, JPEG or WebP image.",
)
from deeptutor.multi_user.identity import save_avatar_file
# Bump the version embedded in the marker so clients cache-bust the URL.
previous = str(info.get("avatar") or "")
version = 1
if previous.startswith("img:"):
try:
version = int(previous.split(":", 1)[1]) + 1
except ValueError:
version = 1
marker = f"img:{version}"
save_avatar_file(current.user_id, data, ext)
if not set_avatar(current.username, marker):
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
logger.info(f"User '{current.username}' uploaded a new avatar ({ext}, {len(data)} bytes)")
return {"ok": True, "avatar": marker}
@router.delete("/profile/avatar")
async def remove_avatar(
payload: TokenPayload | None = Depends(require_auth),
) -> dict:
"""Remove the current user's uploaded avatar image and reset the marker."""
current = _require_profile_identity(payload)
from deeptutor.multi_user.identity import delete_avatar_file
if current.user_id and _USER_ID_RE.match(current.user_id):
delete_avatar_file(current.user_id)
set_avatar(current.username, "")
return {"ok": True, "avatar": ""}
@router.get("/avatar/{user_id}")
async def get_avatar_image(
user_id: str,
_: TokenPayload | None = Depends(require_auth),
) -> FileResponse:
"""Serve a stored avatar image. Any authenticated user may view avatars
(they appear in the admin table and next to the viewer's own profile)."""
if not _USER_ID_RE.match(user_id):
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Avatar not found")
from deeptutor.multi_user.identity import get_avatar_file
target = get_avatar_file(user_id)
if target is None:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Avatar not found")
media_type = _AVATAR_MEDIA_TYPES.get(target.suffix.lstrip("."), "application/octet-stream")
headers = {
# Private user content; the marker version in the URL handles busting.
"Cache-Control": "private, max-age=86400",
"X-Content-Type-Options": "nosniff",
"Content-Disposition": "inline",
}
return FileResponse(path=str(target), media_type=media_type, headers=headers)
# ---------------------------------------------------------------------------
# Admin-only endpoints
# ---------------------------------------------------------------------------
@router.get("/devices")
async def list_devices(
user_id: str | None = None,
include_revoked: bool = False,
_: TokenPayload = Depends(require_admin),
) -> dict:
"""List local device credential metadata without credential secrets."""
_require_builtin_device_auth()
credentials = list_device_credentials(user_id=user_id, include_revoked=include_revoked)
users = {str(user.get("id") or ""): str(user.get("username") or "") for user in list_users()}
return {
"devices": [
{**device, "username": users.get(device["user_id"], "")} for device in credentials
]
}
@router.post("/devices", status_code=status.HTTP_201_CREATED)
async def issue_device(
body: DeviceCredentialCreateRequest,
current: TokenPayload = Depends(require_admin),
) -> dict:
"""Issue a revocable device credential for an ordinary local account."""
_require_builtin_device_auth()
if get_user_by_id(body.user_id) is None:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
try:
device, pairing_code, pin = issue_device_credential(
user_id=body.user_id,
device_name=body.device_name,
expires_at=datetime.now(timezone.utc) + timedelta(days=body.expires_in_days),
daily_limit_minutes=body.daily_limit_minutes,
)
except ValueError as exc:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
log_admin_action(
"device_credential_issue",
target_user_id=body.user_id,
summary={
"device_credential_id": device["id"],
"device_name": device["device_name"],
"expires_at": device["expires_at"],
"daily_limit_minutes": device["daily_limit_minutes"],
},
)
logger.info(
f"Admin '{current.username if current else 'local'}' issued device "
f"credential {device['id']} for user id '{body.user_id}'"
)
return {
"device": device,
"pairing_code": pairing_code,
"pin": pin,
}
@router.delete("/devices/{device_credential_id}")
async def revoke_device(
device_credential_id: str,
current: TokenPayload = Depends(require_admin),
) -> dict:
_require_builtin_device_auth()
device = revoke_device_credential(
device_credential_id,
revoked_by=str(current.user_id if current else ""),
)
if device is None:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="Device credential not found",
)
log_admin_action(
"device_credential_revoke",
target_user_id=device["user_id"],
summary={"device_credential_id": device["id"]},
)
return {"device": device, "ok": True}
@router.get("/users", response_model=list[UserInfo])
async def get_users(_: TokenPayload = Depends(require_admin)) -> list[UserInfo]:
"""List all registered users. Requires admin role."""
return [UserInfo(**u) for u in list_users()]
def _require_local_learner(current: TokenPayload) -> tuple[str, dict]:
"""Resolve a self-service profile request to its local learner account."""
if current.role == "admin":
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN, detail="Learner profile required"
)
account = get_user_by_id(current.user_id)
if account is None or account[0] != current.username:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
if str(account[1].get("preset") or "standard") != "learner":
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN, detail="Learner profile required"
)
return account
@router.get("/profile/learner-profile")
async def get_current_learner_profile(current: TokenPayload = Depends(require_auth)) -> dict:
"""Return the authenticated learner's own profile."""
_require_local_learner(current)
profile = load_learner_profile(current.username)
return {"learner_profile": profile}
@router.put("/profile/learner-profile")
async def put_current_learner_profile(
body: LearnerProfileRequest,
current: TokenPayload = Depends(require_auth),
) -> dict:
"""Update only the authenticated learner's own profile."""
_require_local_learner(current)
from deeptutor.multi_user.learner_profile import normalize_profile
try:
profile = normalize_profile(body.model_dump(exclude_none=True))
except ValueError as exc:
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)
) from exc
updated = set_learner_profile(current.username, profile)
log_usage(
"learner_profile",
current.user_id,
"self_update",
{"fields": sorted(profile or {})},
)
return {"learner_profile": updated}
@router.get("/users/{username}/learner-profile")
async def get_learner_profile(username: str, _: TokenPayload = Depends(require_admin)) -> dict:
"""Return the structured profile managed for an ordinary learner."""
from deeptutor.multi_user.identity import get_user
user = get_user(username)
if (
user is None
or str(user.get("role") or "user") == "admin"
or str(user.get("preset") or "standard") != "learner"
):
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
return {"learner_profile": user.get("learner_profile")}
@router.put("/users/{username}/learner-profile")
async def put_learner_profile(
username: str,
body: LearnerProfileRequest,
current: TokenPayload = Depends(require_admin),
) -> dict:
from deeptutor.multi_user.identity import get_user
from deeptutor.multi_user.learner_profile import normalize_profile
user = get_user(username)
if (
user is None
or str(user.get("role") or "user") == "admin"
or str(user.get("preset") or "standard") != "learner"
):
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
try:
profile = normalize_profile(body.model_dump(exclude_none=True))
except ValueError as exc:
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)
) from exc
updated = set_learner_profile(username, profile)
log_admin_action(
"learner_profile_update",
target_user_id=str(user.get("id") or ""),
summary={"fields": sorted(profile or {})},
)
logger.info("Admin '%s' updated learner profile for '%s'", current.username, username)
return {"learner_profile": updated}
def _validation_message(exc: ValidationError) -> str:
parts = []
for error in exc.errors():
location = ".".join(str(item) for item in error.get("loc", ()))
parts.append(f"{location or 'row'}: {error.get('msg', 'Invalid value')}")
return "; ".join(parts)
def _create_admin_user(
body: AdminCreateUserRequest,
current: TokenPayload | None,
) -> dict:
"""Create one ordinary account through the shared admin provision path."""
actor = current.username if current else "local"
if POCKETBASE_ENABLED:
if body.preset != "standard":
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Only the standard preset is available in PocketBase mode.",
)
result = register_pb(username=body.username, email=body.username, password=body.password)
if not result:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="Failed to create user — username may already be taken.",
)
logger.info("Admin '%s' created PocketBase user '%s'", actor, body.username)
return {
"ok": True,
"user_id": result.get("id", ""),
"username": body.username,
"role": "user",
"is_admin": False,
"preset": "standard",
}
if any(item.get("username") == body.username for item in list_users()):
raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Username already taken")
add_user(body.username, body.password, preset=body.preset)
created = next(
(item for item in list_users() if item.get("username") == body.username),
None,
)
user_id = str(created.get("id") or "") if created else ""
role = str(created.get("role") or "user") if created else "user"
preset = str(created.get("preset") or "standard") if created else "standard"
if role != "user":
delete_user(body.username)
raise HTTPException(
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
detail="Only non-admin users can be provisioned by this endpoint.",
)
if preset == "learner":
from deeptutor.multi_user.grants import learner_grant, save_grant
try:
save_grant(user_id, learner_grant(user_id))
except Exception as exc:
rolled_back = False
try:
rolled_back = delete_user(body.username)
except Exception:
logger.exception(
"Failed to roll back user '%s' after learner grant initialization failed",
body.username,
)
if not rolled_back:
logger.error(
"Learner account '%s' may remain after grant initialization failed",
body.username,
)
raise HTTPException(
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
detail="The learner preset could not be initialized.",
) from exc
logger.info(
"Admin '%s' created user '%s' (role=%r, preset=%r)",
actor,
body.username,
role,
preset,
)
return {
"ok": True,
"user_id": user_id,
"username": body.username,
"role": role,
"is_admin": False,
"preset": preset,
}
@router.post("/users", status_code=status.HTTP_201_CREATED)
async def admin_create_user(
body: AdminCreateUserRequest,
current: TokenPayload = Depends(require_admin),
) -> dict:
"""Admin-only: create one ordinary user account."""
if not AUTH_ENABLED:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Auth is disabled — user creation is not available.",
)
return _create_admin_user(body, current)
@router.post("/users/import")
async def admin_import_users(
file: UploadFile = File(...),
current: TokenPayload = Depends(require_admin),
) -> dict:
"""Admin-only: provision ordinary users from a CSV file.
The response is row-oriented so one invalid record does not erase the
context of the valid records around it. Passwords are never returned.
"""
if not AUTH_ENABLED:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Auth is disabled — user import is not available.",
)
content = await file.read(_USER_IMPORT_MAX_BYTES + 1)
await file.close()
if len(content) > _USER_IMPORT_MAX_BYTES:
raise HTTPException(
status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
detail="User import file exceeds 2 MB.",
)
try:
text = content.decode("utf-8-sig")
except UnicodeDecodeError as exc:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="User import must be a UTF-8 CSV file.",
) from exc
reader = csv.DictReader(io.StringIO(text, newline=""))
fieldnames = [str(name or "").strip().lower() for name in reader.fieldnames or []]
expected = ["username", "password", "preset"]
if fieldnames != expected:
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
detail="CSV header must be exactly: username,password,preset",
)
# DictReader keeps the original header spelling as dictionary keys.
reader.fieldnames = expected
parsed: list[tuple[int, AdminCreateUserRequest, str]] = []
results: list[dict] = []
rows = list(reader)
if not rows:
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
detail="User import file contains no user rows.",
)
if len(rows) > _USER_IMPORT_MAX_ROWS:
raise HTTPException(
status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
detail=f"User import cannot exceed {_USER_IMPORT_MAX_ROWS} rows.",
)
for row_number, row in enumerate(rows, start=2):
username = str(row.get("username") or "").strip()
if row.get(None):
results.append(
{
"row": row_number,
"username": username[:100],
"ok": False,
"error": "Row has more values than the CSV header.",
}
)
continue
try:
body = AdminCreateUserRequest(
username=username,
password=str(row.get("password") or ""),
preset=str(row.get("preset") or "").strip() or "standard",
)
except ValidationError as exc:
results.append(
{
"row": row_number,
"username": username[:100],
"ok": False,
"error": _validation_message(exc),
}
)
continue
parsed.append((row_number, body, username[:100]))
for row_number, body, username in parsed:
try:
created = _create_admin_user(body, current)
except HTTPException as exc:
detail = exc.detail if isinstance(exc.detail, str) else "Failed to create user"
results.append({"row": row_number, "username": username, "ok": False, "error": detail})
except Exception:
logger.exception("Admin user import failed for row %s", row_number)
results.append(
{
"row": row_number,
"username": username,
"ok": False,
"error": "Failed to create user.",
}
)
else:
results.append({"row": row_number, "username": username, "ok": True, "user": created})
results.sort(key=lambda result: result["row"])
created_count = sum(1 for result in results if result["ok"])
failed_count = len(results) - created_count
logger.info(
"Admin '%s' imported users: %s created, %s failed",
current.username if current else "local",
created_count,
failed_count,
)
return {
"ok": failed_count == 0,
"created_count": created_count,
"failed_count": failed_count,
"results": results,
}
def _delete_admin_user(username: str, current: TokenPayload | None) -> tuple[int, str]:
if current and username == current.username:
return 400, "You cannot delete your own account"
# Capture the id before the record disappears so the avatar file can go too.
info = get_user_info(username)
removed = delete_user(username)
if not removed:
return 404, "User not found"
user_id = str(info.get("id") or "") if info else ""
if user_id and _USER_ID_RE.match(user_id):
from deeptutor.multi_user.identity import delete_avatar_file
delete_avatar_file(user_id)
actor = current.username if current else "local"
logger.info("Admin '%s' deleted user '%s'", actor, username)
return 200, ""
@router.delete("/users/{username}", status_code=status.HTTP_200_OK)
async def remove_user(
username: str,
current: TokenPayload = Depends(require_admin),
) -> dict:
"""Delete a user. Admins cannot delete their own account."""
status_code, detail = _delete_admin_user(username, current)
if status_code != 200:
raise HTTPException(status_code=status_code, detail=detail)
return {"ok": True}
@router.post("/users/batch-delete")
async def batch_remove_users(
body: AdminBatchDeleteRequest,
current: TokenPayload = Depends(require_admin),
) -> dict:
"""Delete selected users and report each outcome separately."""
results: list[dict] = []
for username in body.usernames:
_status_code, detail = _delete_admin_user(username, current)
results.append({"username": username, "ok": not detail, "error": detail or None})
deleted_count = sum(1 for result in results if result["ok"])
failed_count = len(results) - deleted_count
logger.info(
"Admin '%s' batch-deleted users: %s deleted, %s failed",
current.username if current else "local",
deleted_count,
failed_count,
)
return {
"ok": failed_count == 0,
"deleted_count": deleted_count,
"failed_count": failed_count,
"results": results,
}
@router.put("/users/{username}/role", status_code=status.HTTP_200_OK)
async def update_user_role(
username: str,
body: SetRoleRequest,
current: TokenPayload = Depends(require_admin),
) -> dict:
"""Change a user's role. Admins cannot change their own role."""
if current and username == current.username:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="You cannot change your own role",
)
updated = set_role(username, body.role)
if not updated:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
logger.info(
f"Admin '{current.username if current else 'local'}' set '{username}' role to {body.role!r}"
)
return {"ok": True, "username": username, "role": body.role}