Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

Harden trusted handoff proxy and ticket lifetime; normalize CSV rows

Bingxi Zhao (Frank)e5598a72c57a
diff --git a/README.md b/README.md
index 2f6da7520..7975d37fb 100644
--- a/README.md
+++ b/README.md
@@ -864,7 +864,7 @@ The **first registered user becomes admin** and owns model catalogs, provider cr
**Enable it:** turn auth on in `data/user/settings/auth.json`, restart `deeptutor start`, register the first admin at `/register`, then add users from `/admin/users` and assign models, KBs, skills, partners, tool/MCP/CLI-app policy, and code-execution access through grants; configure shared books under each user's **Book access** panel.
-For split private/public origins, set `auth.private_login_hosts` (or `AUTH_PRIVATE_LOGIN_HOSTS`) to the private frontend hosts that may show password sign-in and registration. Keep the backend API reachable through the DeepTutor frontend proxy rather than exposing it directly, because that proxy supplies the trusted frontend-host boundary. Loopback is always allowed; when the list is non-empty, an authenticated user on a private origin can open **Profile → Public device sign-in** and create a short-lived, host-bound pairing link for an HTTPS public origin. The public `/handoff` page exchanges the one-time code for an equally short JWE ticket in a POST body, consumes the ticket once, and receives the normal HttpOnly session cookie.
+For split private/public origins, set `auth.private_login_hosts` (or `AUTH_PRIVATE_LOGIN_HOSTS`) to the private frontend hosts that may show password sign-in and registration. The backend accepts frontend-host assertions only from loopback by default. If the Web frontend connects from another container or host, set `AUTH_TRUSTED_FRONTEND_PROXY_IPS` to that frontend proxy's exact IP address on the backend process (comma-separated for more than one). Keep the backend API private to the frontend proxy and do not include general client networks in this list. Loopback is always allowed; when the list is non-empty, an authenticated user on a private origin can open **Profile → Public device sign-in** and create a short-lived, host-bound pairing link for an HTTPS public origin. The public `/handoff` page exchanges the one-time code for an equally short JWE ticket in a POST body, consumes the ticket once, and receives the normal HttpOnly session cookie.
> PocketBase stays a single-user integration — keep `integrations.pocketbase_url` blank for multi-user deployments unless you've wired up an external user store.
diff --git a/deeptutor/api/routers/auth.py b/deeptutor/api/routers/auth.py
index 6f364d63b..b7d70c7ac 100644
--- a/deeptutor/api/routers/auth.py
+++ b/deeptutor/api/routers/auth.py
@@ -4,8 +4,12 @@ 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,
@@ -48,6 +52,20 @@ 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,
@@ -83,8 +101,6 @@ _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(
@@ -92,6 +108,22 @@ PRIVATE_LOGIN_HOSTS = frozenset(
)
+# 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.
+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``.
@@ -110,6 +142,42 @@ def _cookie_attrs() -> dict:
}
+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
# ---------------------------------------------------------------------------
@@ -168,6 +236,24 @@ class RegisterRequest(BaseModel):
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."""
@@ -636,11 +722,14 @@ async def auth_status(
@router.post("/login")
-async def login(body: LoginRequest, response: Response) -> dict:
+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".
@@ -726,6 +815,178 @@ async def device_login(body: DeviceLoginRequest, response: Response) -> dict:
}
[email protected]("/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,
+ }
+
+
[email protected]("/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}
+
+
[email protected]("/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,
@@ -770,7 +1031,7 @@ async def logout(response: Response) -> dict:
@router.post("/register", status_code=status.HTTP_201_CREATED)
-async def register(body: RegisterRequest) -> dict:
+async def register(body: RegisterRequest, request: Request, response: Response) -> dict:
"""
Bootstrap-only registration.
@@ -786,6 +1047,9 @@ async def register(body: RegisterRequest) -> dict:
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.
@@ -1361,6 +1625,8 @@ async def admin_import_users(
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] = []
diff --git a/deeptutor/multi_user/session_handoff.py b/deeptutor/multi_user/session_handoff.py
index 01485e587..06e36c4a7 100644
--- a/deeptutor/multi_user/session_handoff.py
+++ b/deeptutor/multi_user/session_handoff.py
@@ -380,13 +380,17 @@ class SessionHandoffStore:
)
connection.commit()
raise HandoffRejected("Pairing code is not valid for this site")
+ claims = decrypt_ticket_payload(str(row["encrypted_ticket"]))
+ claims["exp"] = current + TICKET_LIFETIME_SECONDS
+ fresh_ticket = encrypt_ticket_payload(claims)
connection.execute(
"""
UPDATE handoff_records
- SET code_consumed_at=?, failed_attempts=0
+ SET code_consumed_at=?, failed_attempts=0,
+ encrypted_ticket=?, ticket_hash=?
WHERE code_hash=? AND code_consumed_at IS NULL
""",
- (current, code_hash),
+ (current, fresh_ticket, hash_secret(fresh_ticket), code_hash),
)
connection.commit()
except HandoffError:
@@ -395,7 +399,7 @@ class SessionHandoffStore:
except Exception:
connection.rollback()
raise
- return str(row["encrypted_ticket"])
+ return fresh_ticket
def consume_ticket(
self,
@@ -424,7 +428,7 @@ class SessionHandoffStore:
row is None
or row["ticket_consumed_at"] is not None
or row["code_consumed_at"] is None
- or row["expires_at"] + TICKET_LIFETIME_SECONDS <= current
+ or row["code_consumed_at"] + TICKET_LIFETIME_SECONDS <= current
):
if row is not None:
connection.execute(
diff --git a/tests/api/test_session_handoff.py b/tests/api/test_session_handoff.py
index b1130f7a4..43672d4f9 100644
--- a/tests/api/test_session_handoff.py
+++ b/tests/api/test_session_handoff.py
@@ -7,12 +7,22 @@ import sqlite3
from fastapi import FastAPI
from fastapi.testclient import TestClient
+import pytest
from deeptutor.api.routers import auth as auth_router
from deeptutor.multi_user import session_handoff
from deeptutor.services import auth as auth_service
+def _loopback_proxy(app):
+ async def forwarded(scope, receive, send):
+ if scope["type"] == "http":
+ scope = {**scope, "client": ("127.0.0.1", 12345)}
+ await app(scope, receive, send)
+
+ return forwarded
+
+
def _handoff_client(
tmp_path: Path,
monkeypatch,
@@ -45,7 +55,7 @@ def _handoff_client(
app = FastAPI()
app.include_router(auth_router.router, prefix="/api/auth")
- return TestClient(app), bearer
+ return TestClient(_loopback_proxy(app)), bearer
def test_private_create_public_exchange_and_complete(tmp_path, monkeypatch) -> None:
@@ -194,7 +204,7 @@ def test_private_login_host_policy_gates_password_login(tmp_path, monkeypatch) -
app = FastAPI()
app.add_api_route("/login", auth_router.login, methods=["POST"])
- with TestClient(app) as client:
+ with TestClient(_loopback_proxy(app)) as client:
refused = client.post(
"/login",
headers={"x-deeptutor-frontend-host": "app.example"},
@@ -208,3 +218,60 @@ def test_private_login_host_policy_gates_password_login(tmp_path, monkeypatch) -
assert refused.status_code == 403
assert allowed.status_code == 200
+
+
+def test_direct_backend_request_cannot_forge_private_frontend_host(tmp_path, monkeypatch) -> None:
+ _, bearer = _handoff_client(tmp_path, monkeypatch)
+ app = FastAPI()
+ app.include_router(auth_router.router, prefix="/api/auth")
+ with TestClient(app) as direct:
+ response = direct.post(
+ "/api/auth/session-handoff",
+ headers={
+ "x-deeptutor-frontend-host": "private.example:8443",
+ "host": "private.example:8443",
+ "Authorization": f"Bearer {bearer}",
+ },
+ json={"public_origin": "https://app.example"},
+ )
+ assert response.status_code == 403
+
+
+def test_pairing_ticket_expires_after_exchange_even_near_code_expiry(tmp_path, monkeypatch) -> None:
+ monkeypatch.setattr(session_handoff, "load_or_create_auth_secret", lambda: "test-secret")
+ store = session_handoff.SessionHandoffStore(tmp_path / "handoff.sqlite3")
+ created_at = 1000
+ ticket = session_handoff.encrypt_ticket_payload(
+ {"host": "app.example", "exp": created_at + 420}
+ )
+ record = store.create(
+ encrypted_ticket=ticket,
+ ticket_hash=session_handoff.hash_secret(ticket),
+ public_host="app.example",
+ now=created_at,
+ )
+ exchanged_at = created_at + session_handoff.CODE_LIFETIME_SECONDS - 1
+ fresh = store.exchange(code=record.code, public_host="app.example", now=exchanged_at)
+ assert (
+ session_handoff.decrypt_ticket_payload(fresh)["exp"]
+ == exchanged_at + session_handoff.TICKET_LIFETIME_SECONDS
+ )
+ assert (
+ store.consume_ticket(ticket=fresh, public_host="app.example", now=exchanged_at + 119)
+ == fresh
+ )
+
+
+def test_pairing_ticket_rejects_completion_after_its_exchange_window(tmp_path, monkeypatch) -> None:
+ monkeypatch.setattr(session_handoff, "load_or_create_auth_secret", lambda: "test-secret")
+ store = session_handoff.SessionHandoffStore(tmp_path / "handoff.sqlite3")
+ ticket = session_handoff.encrypt_ticket_payload({"host": "app.example", "exp": 2420})
+ record = store.create(
+ encrypted_ticket=ticket,
+ ticket_hash=session_handoff.hash_secret(ticket),
+ public_host="app.example",
+ now=2000,
+ )
+ exchanged = store.exchange(code=record.code, public_host="app.example", now=2299)
+ with pytest.raises(session_handoff.HandoffRejected):
+ store.consume_ticket(ticket=exchanged, public_host="app.example", now=2419)
diff --git a/tests/multi_user/test_admin_user_batches.py b/tests/multi_user/test_admin_user_batches.py
index 1d5c61b41..edc3bdf78 100644
--- a/tests/multi_user/test_admin_user_batches.py
+++ b/tests/multi_user/test_admin_user_batches.py
@@ -174,3 +174,21 @@ def test_batch_delete_reports_partial_results_and_protects_current_admin(batch_c
item["username"] for item in client.get("/api/auth/users", headers=headers["admin"]).json()
}
assert usernames == {"root"}
+
+
+def test_import_accepts_normalized_csv_header_without_losing_row_values(batch_client):
+ client, headers = batch_client
+ response = client.post(
+ "/api/auth/users/import",
+ files={
+ "file": (
+ "users.csv",
+ b" Username ,Password,Preset\nalice,alice-password-123,learner\n",
+ "text/csv",
+ )
+ },
+ headers=headers["admin"],
+ )
+ assert response.status_code == 200
+ assert response.json()["created_count"] == 1
+ assert response.json()["results"][0]["username"] == "alice"