DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
Harden trusted handoff proxy and ticket lifetime; normalize CSV rows
Bingxi Zhao (Frank)e5598a72c57a
diff --git a/README.md b/README.mdindex 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.pyindex 6f364d63b..b7d70c7ac 100644--- a/deeptutor/api/routers/auth.py+++ b/deeptutor/api/routers/auth.py@@ -4,8 +4,12 @@ from contextvars import Token as _CtxTokenimport csvfrom datetime import datetime, timedelta, timezoneimport io+import ipaddressimport logging+import osimport re+import secrets+import timefrom fastapi import (APIRouter,@@ -48,6 +52,20 @@ from deeptutor.multi_user.identity import get_user_by_idfrom deeptutor.multi_user.learning_access import learning_policy_for_userfrom deeptutor.multi_user.models import AccountPresetfrom 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 = expectedparsed: list[tuple[int, AdminCreateUserRequest, str]] = []results: list[dict] = []diff --git a/deeptutor/multi_user/session_handoff.py b/deeptutor/multi_user/session_handoff.pyindex 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_ticketdef consume_ticket(self,@@ -424,7 +428,7 @@ class SessionHandoffStore:row is Noneor row["ticket_consumed_at"] is not Noneor 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.pyindex b1130f7a4..43672d4f9 100644--- a/tests/api/test_session_handoff.py+++ b/tests/api/test_session_handoff.py@@ -7,12 +7,22 @@ import sqlite3from fastapi import FastAPIfrom fastapi.testclient import TestClient+import pytestfrom deeptutor.api.routers import auth as auth_routerfrom deeptutor.multi_user import session_handofffrom 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)), bearerdef 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 == 403assert 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.pyindex 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_citem["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"