Security hotfix v0.5.1: enforce must_change_password + 2FA temp token + API key gates

Three high-confidence auth gaps fixed after a focused review following a
user report that admin/admin on the public demo returned a fully usable
admin JWT.

- get_current_user now enforces must_change_password server-side. Only
  /api/auth/me and /api/auth/change-password are allowed while the flag
  is set; every other endpoint returns 403. Previously the flag was only
  surfaced by the UI modal, which a direct API caller could ignore.

- Pre-2FA 'temp_token' was broken: create_access_token silently ignored
  the 'exp_minutes' key and minted a full 24h session JWT, and no
  endpoint looked at the pending_2fa claim, so the temp token bypassed
  2FA entirely. Fixed by adding an 'expires_minutes' parameter (now 2
  minutes) and rejecting pending_2fa=True tokens everywhere except
  /api/auth/login itself.

- API key auth now honors must_change_password (403 if the owning user
  is in forced-change state). Prevents working around the lockout by
  minting a key before changing the password.

- /api/recordings/{id}/play HTML now sends Referrer-Policy: no-referrer
  and Cache-Control: private, no-store, and the asciinema-player CDN
  assets are fetched with referrerpolicy='no-referrer', so the ?token=
  in the URL no longer leaks to third parties.

Verified end-to-end: admin/admin JWT now 403s on /api/auth/users and
/api/servers but works on /api/auth/me; after POST /api/auth/change-
password the same account receives a normal token that passes every
check. Temp token from the pre-2FA step returns 403 'Pending 2FA' on
every endpoint.

Docs: README screenshot sub-sections renamed from release-pack labels
to functional titles (jump host / snippets / shared terminal / session
recording / demo mode).

Author: kalexnolasco

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## v0.5.1 (2026-04-16) — Security hotfix
+
+### Security (please upgrade)
+
+Three authentication gaps fixed after a focused security review.
+
+- **`must_change_password` is now enforced server-side**. Previously the flag was only surfaced by the UI; a valid JWT from a `admin/admin` first-run login let attackers hit every admin endpoint (`/api/auth/users`, `/api/servers`, audit log, ...) without ever changing the password. `get_current_user` now returns `403 Password change required` for any path other than `/api/auth/me` and `/api/auth/change-password` while the flag is `True`. *(Credit: user report on the public demo.)*
+- **Pre-2FA "temp token" is now truly short-lived and scoped.** The `create_access_token({"pending_2fa": True, "exp_minutes": 2})` call ignored `exp_minutes` — the token got the full 24-hour session TTL, and no endpoint checked the `pending_2fa` claim, so the "temp" token bypassed 2FA completely. Fixed by: adding `expires_minutes` parameter to `create_access_token`, setting it to 2, and rejecting any token with `pending_2fa=True` on every endpoint except `/api/auth/login` itself.
+- **API keys cannot bypass forced password change.** An account with `must_change_password=True` can no longer create or use an API key until the password has been rotated. Prevents workaround paths when an admin issues a temporary password.
+- **Recording replay page no longer leaks the session token via Referer.** `GET /api/recordings/{id}/play` now sends `Referrer-Policy: no-referrer` and `Cache-Control: private, no-store`, and all third-party assets on the page (asciinema-player CDN) are fetched with `referrerpolicy="no-referrer"`.
+
+### Docs
+
+- README: screenshot sub-sections renamed to functional titles (jump host / snippets / shared terminal / session recording / demo mode) instead of release-pack labels, so the README always describes what the current version ships.
+
+---
+
 ## v0.5.0 (2026-04-15)
 
 ### Features

README.md

@@ -155,25 +155,36 @@ flowchart TB
 | ![Access Control](docs/screenshots/access-control.png) | ![Users](docs/screenshots/users.png) |
 | ![Audit](docs/screenshots/audit.png) | ![Light Theme](docs/screenshots/light-theme.png) |
 
-### Operations Pack — jump host, snippets, webhooks
+### Jump host, snippets, webhooks
 
 | | |
 |---|---|
-| ![Demo banner](docs/screenshots/v0.3/01-login-demo-banner.png) | ![Dashboard with jump host](docs/screenshots/v0.3/02-dashboard-jump-host.png) |
+| ![Dashboard with jump host](docs/screenshots/v0.3/02-dashboard-jump-host.png) | ![Add Server with Jump Via](docs/screenshots/v0.3/08-add-server-jump-via.png) |
 | ![Terminal snippets](docs/screenshots/v0.3/03-terminal-snippets-jump.png) | ![Snippet executed](docs/screenshots/v0.3/04-snippet-executed.png) |
-| ![SFTP via jump](docs/screenshots/v0.3/05-sftp-via-jump.png) | ![Add Server with Jump Via](docs/screenshots/v0.3/08-add-server-jump-via.png) |
-| ![Webhooks modal](docs/screenshots/v0.3/06-webhooks-modal.png) |  |
+| ![SFTP via jump](docs/screenshots/v0.3/05-sftp-via-jump.png) | ![Webhooks modal](docs/screenshots/v0.3/06-webhooks-modal.png) |
 
-### Shared terminal & session recording
+### Shared terminal sessions
 
-| Owner sees | Joiner sees |
+Click **🔗 Share** in the terminal toolbar to get a URL; anyone who opens it joins the same live SSH session (broadcast output, multiplexed input).
+
+| Owner | Joiner |
 |---|---|
 | ![Shared owner](docs/screenshots/v0.4/01-shared-terminal-owner.png) | ![Shared joiner](docs/screenshots/v0.4/02-shared-terminal-joiner.png) |
 
+### Session recording
+
+Enable `WEBGATE_RECORD_SESSIONS=true` and every SSH session is captured to an asciinema cast file with built-in browser replay.
+
 | Recordings list | Browser replay |
 |---|---|
 | ![Recordings](docs/screenshots/v0.4/04-recordings-modal.png) | ![Replay](docs/screenshots/v0.4/03-recording-replay.png) |
 
+### Public read-only demo mode
+
+`WEBGATE_DEMO_MODE=true` turns the app into a sandbox: banner, seeded `demo`/`demo` user, all writes blocked. Used by the live demo at [webgate-demo.fly.dev](https://webgate-demo.fly.dev/).
+
+![Demo banner](docs/screenshots/v0.3/01-login-demo-banner.png)
+
 ---
 
 ## Architecture
@@ -551,7 +562,7 @@ curl -s http://localhost:8443/api/health   # shows instance_id + monitor_role
 
 [`compose.ha.yml`](compose.ha.yml) spins up 2 webgate replicas + Postgres + nginx with `ip_hash` sticky sessions. On leader loss, the lease expires within 90 seconds and another replica picks it up automatically.
 
-> **Known limitation**: live shared-terminal sessions still need owner and joiner on the same worker. Sticky sessions mitigate it for same-browser joins; true cross-worker fan-out needs Redis pub/sub — planned for a later v0.5.x.
+> **Known limitation**: live shared-terminal sessions still need owner and joiner on the same worker. Sticky sessions mitigate it for same-browser joins; true cross-worker fan-out requires a Redis pub/sub layer (not yet implemented).
 
 ### Public read-only demo (Fly.io)
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "webgate"
-version = "0.5.0"
+version = "0.5.1"
 description = "Self-hosted web application for remote server management via SSH terminal and SFTP file browser"
 readme = "README.md"
 license = "MIT"

src/webgate/auth/routes.py

@@ -56,14 +56,25 @@
 AuthDep = Annotated[HTTPAuthorizationCredentials, Depends(security)]
 
 
-async def get_current_user(credentials: AuthDep, session: SessionDep) -> UserOut:
+async def get_current_user(
+    request: Request, credentials: AuthDep, session: SessionDep
+) -> UserOut:
+    """Resolve the user from JWT or API key and enforce account-level gates
+    (pending 2FA, forced password change). Only a short allowlist of endpoints
+    can be hit while a user is in one of those states."""
     token = credentials.credentials
 
     # Check if it's an API key (starts with "wg_")
     if token.startswith("wg_"):
         user = await authenticate_api_key(session, token)
         if not user:
             raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid API key")
+        if user.must_change_password:
+            # API keys cannot bypass a forced password change.
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Password change required before using API keys",
+            )
         return UserOut.model_validate(user)
 
     # Otherwise treat as JWT
@@ -76,6 +87,23 @@ async def get_current_user(credentials: AuthDep, session: SessionDep) -> UserOut
     user = await get_user_by_id(session, int(user_id))
     if user is None:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="User not found")
+
+    path = request.url.path
+    # Pre-2FA temp token: only /api/auth/login is allowed (for the code step).
+    if payload.get("pending_2fa"):
+        if path != "/api/auth/login":
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Pending 2FA: submit totp_code via /api/auth/login to obtain a session token",
+            )
+    # Forced password change: only /api/auth/me and /api/auth/change-password are allowed.
+    if user.must_change_password and path not in {
+        "/api/auth/me", "/api/auth/change-password",
+    }:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Password change required",
+        )
     return UserOut.model_validate(user)
 
 
@@ -120,9 +148,11 @@ async def login(request: Request, body: UserLogin, session: SessionDep) -> Login
     # Check if 2FA is enabled
     if user.totp_enabled and user.totp_secret:
         if not body.totp_code:
-            # Issue a short-lived temp token for 2FA verification
+            # Short-lived pre-2FA token: only accepted by /api/auth/login
+            # itself (gated in get_current_user) and expires in 2 minutes.
             temp_token = create_access_token(
-                {"sub": str(user.id), "pending_2fa": True, "exp_minutes": 2}
+                {"sub": str(user.id), "pending_2fa": True},
+                expires_minutes=2,
             )
             return LoginOut(requires_2fa=True, temp_token=temp_token)
         # Verify the TOTP code

src/webgate/auth/service.py

@@ -2,6 +2,7 @@
 
 import json
 import logging
+import secrets
 from datetime import UTC, datetime, timedelta
 from typing import Any
 
@@ -10,7 +11,7 @@
 from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from webgate.auth.models import User
+from webgate.auth.models import ApiKey, User
 from webgate.config import settings
 
 logger = logging.getLogger(__name__)
@@ -24,9 +25,12 @@ def verify_password(plain: str, hashed: str) -> bool:
     return bcrypt.checkpw(plain.encode(), hashed.encode())
 
 
-def create_access_token(data: dict[str, Any]) -> str:
+def create_access_token(data: dict[str, Any], expires_minutes: int | None = None) -> str:
+    """Mint a signed JWT. `expires_minutes` overrides the default session TTL
+    for short-lived tokens (e.g. the 2-minute pre-2FA token)."""
     to_encode = data.copy()
-    expire = datetime.now(UTC) + timedelta(minutes=settings.jwt_expire_minutes)
+    minutes = expires_minutes if expires_minutes is not None else settings.jwt_expire_minutes
+    expire = datetime.now(UTC) + timedelta(minutes=minutes)
     to_encode["exp"] = expire
     return jwt.encode(to_encode, settings.secret_key, algorithm=settings.jwt_algorithm)
 
@@ -113,3 +117,81 @@ async def update_user_password(
 async def delete_user(session: AsyncSession, user: User) -> None:
     await session.delete(user)
     await session.commit()
+
+
+def generate_api_key() -> str:
+    """Generate a random API key like 'wg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'."""
+    return "wg_" + secrets.token_hex(24)
+
+
+async def create_api_key(session: AsyncSession, user_id: int, name: str) -> tuple[ApiKey, str]:
+    """Create an API key. Returns (model, plaintext_key)."""
+    key = generate_api_key()
+    key_obj = ApiKey(
+        user_id=user_id,
+        name=name,
+        key_hash=hash_password(key),
+        key_prefix=key[:10],
+    )
+    session.add(key_obj)
+    await session.commit()
+    await session.refresh(key_obj)
+    return key_obj, key
+
+
+async def get_api_keys(session: AsyncSession, user_id: int) -> list[ApiKey]:
+    """List all API keys for a user."""
+    result = await session.execute(
+        select(ApiKey).where(ApiKey.user_id == user_id).order_by(ApiKey.created_at.desc())
+    )
+    return list(result.scalars().all())
+
+
+async def delete_api_key(session: AsyncSession, key_id: int, user_id: int) -> bool:
+    """Delete an API key. Returns True if found and deleted."""
+    result = await session.execute(
+        select(ApiKey).where(ApiKey.id == key_id, ApiKey.user_id == user_id)
+    )
+    key_obj = result.scalar_one_or_none()
+    if not key_obj:
+        return False
+    await session.delete(key_obj)
+    await session.commit()
+    return True
+
+
+async def authenticate_api_key(session: AsyncSession, key: str) -> User | None:
+    """Look up API key by prefix, then verify hash. Update last_used_at."""
+    prefix = key[:10]
+    result = await session.execute(
+        select(ApiKey).where(ApiKey.key_prefix == prefix)
+    )
+    for api_key in result.scalars().all():
+        if verify_password(key, api_key.key_hash):
+            api_key.last_used_at = datetime.now(UTC)
+            user_result = await session.execute(
+                select(User).where(User.id == api_key.user_id)
+            )
+            user = user_result.scalar_one_or_none()
+            await session.commit()
+            return user
+    return None
+
+
+def generate_totp_secret() -> str:
+    import pyotp
+
+    return pyotp.random_base32()
+
+
+def get_totp_uri(secret: str, username: str) -> str:
+    import pyotp
+
+    return pyotp.totp.TOTP(secret).provisioning_uri(name=username, issuer_name="webgate")
+
+
+def verify_totp(secret: str, code: str) -> bool:
+    import pyotp
+
+    totp = pyotp.TOTP(secret)
+    return totp.verify(code, valid_window=1)

src/webgate/recordings/routes.py

@@ -81,11 +81,15 @@ async def play_recording(
     # Embed asciinema-player from CDN. The cast file is fetched via the
     # download endpoint so JWT auth is honored.
     started = rec.started_at.isoformat()
+    # Referrer-Policy no-referrer prevents leaking the ?token= to any
+    # external asset (CDN, browser history peeks, etc.). The meta refresh
+    # is a belt-and-braces for older browsers.
     html = f"""<!doctype html>
 <html><head>
 <meta charset="utf-8">
+<meta name="referrer" content="no-referrer">
 <title>webgate replay #{rec.id} — {rec.server_name}</title>
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/asciinema-player@3.7.0/dist/bundle/asciinema-player.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/asciinema-player@3.7.0/dist/bundle/asciinema-player.css" referrerpolicy="no-referrer">
 <style>
   body {{ background:#1a1b26; color:#c0caf5; font-family:system-ui,sans-serif; margin:0; padding:20px; }}
   .meta {{ display:flex; gap:24px; font-size:13px; margin-bottom:16px; color:#9ba3c5; }}
@@ -101,13 +105,16 @@ async def play_recording(
   <span>💾 {rec.size_bytes:,} bytes</span>
 </div>
 <div id=\"player\"></div>
-<script src=\"https://cdn.jsdelivr.net/npm/asciinema-player@3.7.0/dist/bundle/asciinema-player.min.js\"></script>
+<script src=\"https://cdn.jsdelivr.net/npm/asciinema-player@3.7.0/dist/bundle/asciinema-player.min.js\" referrerpolicy="no-referrer"></script>
 <script>
   AsciinemaPlayer.create('cast?token={token}', document.getElementById('player'),
     {{ idleTimeLimit: 2, theme: 'tango', fit: 'width' }});
 </script>
 </body></html>"""
-    return HTMLResponse(content=html)
+    return HTMLResponse(
+        content=html,
+        headers={"Referrer-Policy": "no-referrer", "Cache-Control": "private, no-store"},
+    )
 
 
 @router.get("/{recording_id}/cast")